Quickstart

This walkthrough takes you from an empty workspace to a customer, contact, and onboarding visible in the Pivotal UI. Total wall time: about three minutes.

1. Create an API key

Open Admin > API Keys inside your workspace and click Create key. Pick a name (local-dev, prod-server, ci) and the environment:

• Live — pivotal_… — mutates production state, fires webhooks, counts against the live quota.
• Test — pivotal_test_… — mutates production state too, but skips outbound integration calls (Slack, Resend, Stripe). See Test mode.

Copy the key once and stash it in your secret manager. Pivotal stores only a hash; the cleartext is shown exactly once at create time.

2. Confirm the key works

Hit /me. It echoes the key’s identity and the workspace it belongs to. No side effects, costs one request from your rate limit.

$
curl https://my.pivotal.app/api/v1/me \
>
  -H "Authorization: Bearer pivotal_REPLACE_ME"

You should see something like:

1
{
2
  "object": "api_key_identity",
3
  "key_name": "local-dev",
4
  "key_prefix": "pivotal_abc1",
5
  "org_id": "org_2pXh…",
6
  "org_slug": "vml",
7
  "mode": "live"
8
}

If you get a 401, double-check the header format — it’s Authorization: Bearer <key>, not Bearer: <key> or Authorization: <key>.

3. Create a customer

$
curl https://my.pivotal.app/api/v1/customers \
>
  -H "Authorization: Bearer pivotal_REPLACE_ME" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Aurora Outfitters",
>
    "slug": "aurora",
>
    "domain": "aurora.com",
>
    "status": "onboarding"
>
  }'

slug is the URL-safe handle. Pivotal also returns a display_id (the small integer that appears in URLs like /customers/245).

1
{
2
  "object": "customer",
3
  "id": "cl9bn00of0000g7l8gcq8c4xk",
4
  "display_id": 245,
5
  "name": "Aurora Outfitters",
6
  "slug": "aurora",
7
  "domain": "aurora.com",
8
  "status": "onboarding",
9
  "created_at": "2026-05-26T17:21:09.412Z",
10
  "updated_at": "2026-05-26T17:21:09.412Z"
11
}

4. Attach a primary contact

$
curl https://my.pivotal.app/api/v1/customers/245/contacts \
>
  -H "Authorization: Bearer pivotal_REPLACE_ME" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Mira Chen",
>
    "email": "mira@aurora.com",
>
    "title": "Head of Ops",
>
    "is_primary": true
>
  }'

Note the path — contacts always live under a customer. The 245 is the customer’s display_id; the customer’s cuid works just as well.

5. Open an onboarding

$
curl https://my.pivotal.app/api/v1/onboardings \
>
  -H "Authorization: Bearer pivotal_REPLACE_ME" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "customer_id": "245",
>
    "phase": "before_getting_started",
>
    "state": "active",
>
    "target_launch_date": "2026-07-15T00:00:00Z"
>
  }'

Refresh /customers/aurora in the Pivotal UI. You should see Mira on the customer card and the loyalty launch onboarding in the sidebar. The activity feed will show an entry for each API call — the calling key’s name is the actor.

Next