display_id vs id

Pivotal resources carry two identifiers:

Any path parameter that takes an id (/customers/{id}, /contacts/{id}, /onboardings/{id}, /customers/{customerId}/contacts) accepts either. Pivotal looks at the value: if it’s all digits, it resolves as a display_id; otherwise it’s treated as a cuid.

Both lookups return the same row. There’s no performance difference worth mentioning either way.

When to use display_id

• URLs you’ll share with humans. pivotal.app/customers/245 is easier to read out loud than the cuid.
• Support tickets and Slack threads. “Customer 245 is stuck” lands better than “customer cl9bn00of0000g7l8gcq8c4xk is stuck”.
• CSV exports. Excel handles a 3-digit ID better than a 25-character one.
• Logs you’ll eyeball. Easier to grep customer=245 than the full cuid.

When to use id (cuid)

• Foreign keys in your own DB. id is guaranteed never to collide across workspaces — display_id 245 exists in every workspace and means different things in each.
• API-to-API integrations. Stable, opaque, doesn’t change shape.
• Logging across services. A cuid is unambiguous when it lands in a search index next to data from other tenants.

The collision risk

Two different workspaces will both have a customer with display_id 245. If your code stores a Pivotal id in your DB and might be used across workspaces (or might be used by a partner later), prefer the cuid.

If everything in your system runs against one workspace and one API key, display_id is fine.

Mixed-input handlers

If you accept a Pivotal customer id from a webhook or a third party, normalize early:

1
function isDisplayId(value: string): boolean {
2
  return /^\d+$/.test(value);
3
}
4
5
async function loadCustomer(idLike: string) {
6
  const res = await fetch(`https://my.pivotal.app/api/v1/customers/${idLike}`, {
7
    headers: { Authorization: `Bearer ${process.env.PIVOTAL_API_KEY}` },
8
  });
9
  if (!res.ok) return null;
10
  return res.json(); // returns { id, display_id, ... } regardless of which you passed
11
}

The response always carries both fields, so once you’ve looked up a record by display_id you can stash the cuid for future calls.

What’s in the URL

When Pivotal renders a customer page, the URL is /customers/{display_id}-{slug}. Example: /customers/245-aurora. The slug is decorative — Pivotal ignores it when routing, so /customers/245-totally-wrong-slug still loads customer 245. We include the slug for human-readability and SEO inside the workspace.

API paths don’t include the slug. /api/v1/customers/245 and /api/v1/customers/aurora are not the same: the second one looks up by cuid (and will 404 because aurora isn’t a cuid).

To look up by slug, list and filter:

$
curl "https://my.pivotal.app/api/v1/customers?slug=aurora&limit=1" \
>
  -H "Authorization: Bearer $PIVOTAL_API_KEY"

(Filter on the list endpoint, take data[0].)

Webhook payloads (when they land)

When webhooks ship, every event payload will include both id and display_id on every embedded object. Your handlers can match on either depending on what they store.