> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# display_id vs id

Pivotal resources carry two identifiers:

| Field        | Type          | Example                     | Where it shines                                     |
| ------------ | ------------- | --------------------------- | --------------------------------------------------- |
| `id`         | string (cuid) | `cl9bn00of0000g7l8gcq8c4xk` | DB foreign keys, internal storage, API integrations |
| `display_id` | integer       | `245`                       | URLs, support tickets, conversations between humans |

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:

```typescript
function isDisplayId(value: string): boolean {
  return /^\d+$/.test(value);
}

async function loadCustomer(idLike: string) {
  const res = await fetch(`https://my.pivotal.app/api/v1/customers/${idLike}`, {
    headers: { Authorization: `Bearer ${process.env.PIVOTAL_API_KEY}` },
  });
  if (!res.ok) return null;
  return res.json(); // returns { id, display_id, ... } regardless of which you passed
}
```

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:

```bash
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](/api/welcome/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.