ID formats

Three ID shapes cover every resource on the Partner API:

1. Bare UUIDs — the underlying database keys, written into response bodies as-is for the top-level resources.
2. Prefixed ULIDs — <prefix>_&lt;26 Crockford base32> for resources that benefit from a self-describing opaque id (jobs, content, scheduled posts, events, request IDs).
3. Custom shapes — app_<24 hex> for SDK apps. That's the only exception.

You don't need to memorize the prefixes — every path param accepts the bare UUID too. See the tolerance rule below.

Catalog

Every resource you'll see at the boundary. This table is the source of truth; if you find an endpoint emitting something different, file a bug.

Prefixed ULID format

<prefix>_&lt;26 characters of Crockford base32>. Crockford base32 is the 32-character alphabet 0123456789ABCDEFGHJKMNPQRSTVWXYZ — no I, L, O, or U to avoid visual confusion.

• 26 chars carry 130 bits, slightly more than a UUID's 128. Collision risk is negligible.
• Not monotonic. We don't rely on the ULID time prefix for ordering; the leading chars are random entropy. Sort on createdAt, not the id string.
• Case-insensitive in spirit (Crockford), but we always emit uppercase body after the lowercase prefix. Don't re-case them before sending back.

The generator is shared across event IDs, request IDs, and every other prefixed ULID the API mints — same logic everywhere.

Request ID format

Every response carries X-Request-Id: req_<26 Crockford base32>. The same value appears as error.requestId in every 4xx/5xx body — copy that one line into a support ticket and we can pull the full trace.

HTTP/1.1 200 OK
X-Request-Id: req_RKT95R73PHHF5N1AMH9H2Q58MC

If you set your own X-Request-Id request header, we use it as-is (up to 128 chars) so your traces can span the proxy. Otherwise we mint one.

Event ID format

Webhook deliveries carry X-Layers-Event-Id: evt_<26 Crockford base32>. The id is stable across retries of the same event — dedupe on it in your handler. Replays (via POST /v1/webhook-deliveries/:id/replay) mint a fresh event id and set data.replayOf to the original delivery id.

SDK app format

The odd one out: SDK apps use app_<24 hex chars>, not a ULID. This pre-dates the partner ID conventions — SDK app IDs ship into customer binaries and the shorter hex form was baked into the client SDKs before the prefix catalog existed. They're still opaque; treat them as strings.

The tolerance rule

Every path param that documents a prefixed id also accepts the bare UUID. The handler strips the prefix if present and uses the remainder as the lookup key; it doesn't care which you sent.

GET /v1/content/cnt_01HX9Y6K7EJ4T2ABCDEF01234   ← prefixed
GET /v1/content/01HX9Y6K7EJ4T2ABCDEF01234       ← bare

Both resolve the same row. This is not a validation — a malformed id (wrong length, wrong charset) still falls through to a NOT_FOUND. Every content, scheduled-post, social-account, and leased-account path param behaves this way.

Which to use when

• Storing a reference in your system — save the exact string we returned. Don't normalize, don't re-prefix, don't parse it.
• Calling back with it — pass it through verbatim.
• Displaying to an end-user — the prefixed form (cnt_01HX...) is the intended UX. It's self-describing at a glance and pastes cleanly into logs.
• Grepping logs for a specific id — the prefixed form is unambiguous; the bare UUID form can collide with unrelated UUIDs in a large log corpus.

See also

• Common patterns — error envelope, request ID
• Jobs — job IDs and the polling pattern
• Webhooks — event IDs and delivery IDs
• Idempotency — partner-created IDs as stronger idempotency