Resource IDs

Every resource exposed through the Public API has a stable, prefixed identifier of the form <prefix>_<26 base32 chars>.

msg_01HXYZABCDEFGHJKMNPQRSTVWX

The one exception is the WhatsApp phone_number_id — that’s Meta’s identifier and uses a different format. See phone_number_id below.

Prefix table

Prefix	Resource
org_	Organisation
msg_	Message
cnv_	Conversation
ctc_	Contact
tmpl_	Template
wbs_	Webhook subscription
wbd_	Webhook delivery
sec_	Webhook signing secret
evt_	Event (Kirimdev-native envelope id)
cus_	Customer (multi-tenant platform mode)
csl_	Customer setup link
key_	API key
lbl_	Label
key_	API key
req_	Request id (response envelope + X-Request-Id header)
del_	Delivery (generic)

There is no kirim-prefixed id for WhatsApp accounts or users. Accounts are addressed by Meta’s digit-only phone_number_id; conversation assignees carry a raw internal user nanoid (no prefix).

Format

• Length: 4 (prefix) + 1 (_) + 26 (id body) = 31 characters total for most resources. tmpl_* is 32 chars (5-char prefix).
• Alphabet: Crockford base32 (0-9 and A-Z minus I L O U). Always uppercase in the id body.
• URL-safe: No characters require percent-encoding.

Stability commitments

• Permanent. Once Kirimdev hands you an id, that id refers to that exact resource for as long as the resource exists. Hard deletes remove the row entirely, but the id is never reused for a new row.
• Opaque. The body of the id encodes no public meaning. Do not parse, decode, or sort by it. Order resources by created_at (always returned alongside).
• Globally unique within Kirimdev. No two resources share an id, even across organisations.
• Tenant-scoped retrieval. Every endpoint that takes an id enforces that the resource belongs to the caller’s organisation. A cross-org id returns 404 resource_not_found — never 403, to avoid leaking existence.

phone_number_id

The phone_number_id is the WhatsApp Business phone number’s identifier as assigned by Meta. It’s a different beast from Kirimdev’s prefixed ids and appears in every path-scoped endpoint.

GET  /v1/106540352242922/messages
POST /v1/106540352242922/messages
GET  /v1/106540352242922/messages/msg_01HXYZABCDEFGHJKMNPQRSTVWX
GET  /v1/106540352242922/conversations
GET  /v1/106540352242922/templates

Properties

Property	Value
Format	Digits only, typically 15–17 characters
Issuer	Meta (WhatsApp Business Platform)
Stability	Permanent for the lifetime of the phone number
Position	URL path segment, never request body
Discovery	GET /v1/accounts exposes it as the phone_number_id field on each connected account

Example

// GET /v1/accounts → 200
{
  "data": [
    {
      "object": "account",
      "phone_number": "+628111222333",
      "phone_number_id": "106540352242922",
      "name": "Acme Inc",
      "status": "connected"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Accounts are addressed by phone_number_id (Meta’s WhatsApp Business phone number id) in path segments like /v1/{phone_number_id}/messages. They do not carry a kirim-prefixed resource id of their own.

Pluck phone_number_id from there and use it as the path segment for every message, conversation, contact, and template operation against that line.

Note

Endpoints that operate at the organisation level — /v1/health, /v1/me, /v1/accounts, /v1/labels, /v1/webhook_subscriptions, /v1/webhook_deliveries — do not take a phone_number_id in the path. Labels and webhooks span all the phone numbers in your org.

What about internal IDs?

Internally Kirimdev uses 12-character nanoids as primary keys. The public id (msg_…) is stored on a separate column (external_id) and is the only id form ever returned through the API. If you see a shorter id-shaped string somewhere in a payload (e.g. assigned_to on conversations), it’s the internal user id — the only resource without a prefixed external_id contract today.

Anti-patterns

• Don’t sort by id. Crockford base32 is lexicographic but the id body is not strictly time-monotonic across all resources. Sort by created_at instead.
• Don’t substring-match prefixes for routing. Use the resource type implied by the endpoint, not the id prefix on the wire.
• Don’t store IDs you didn’t get from Kirimdev. Generated ids (yours or anyone else’s) won’t match the storage format and will fail validation with 400 invalid_field_value.
• Don’t hardcode a phone_number_id in source. Fetch it from /v1/accounts at startup or load it from config. Reconnecting a phone number issues a new id.

What’s next

List accounts

Discover the phone_number_id for every connected line. API →

Send a message

The most common path-scoped endpoint. API →

Pagination

How created_at-ordered lists page through resources. Read →

Errors

invalid_phone_number and resource_not_found envelopes. Read →