Public IDs
Every object in the API has a numeric ID and a public ID: an opaque
string of the form prefix_ followed by 32 hex characters, e.g.
gid_3520a1ec234dbabe1232def67e858855.
Responses return both fields (public_ID next to ID), and every
endpoint that takes an ID accepts both forms interchangeably — you can
migrate at your own pace.
Public IDs are stable (the same object always keeps the same public ID) and safe to use in URLs, webhooks and your own database. The prefix tells you which type of object the ID refers to:
| Prefix | Object | Example endpoints |
|---|---|---|
| gid | Contact group | /v1/groups/{ID} |
| con | Contact | /v1/contact/{ID} |
| lid | Sent (outbound) message | /v1/message/logging/{ID}, /v1/message/{ID} |
| cnv | Grouped history entry | /v1/message/history/{ID}, /v1/message/{ID} |
| inb | Inbound (received) message | /v1/message/inbound/{ID} |
| cam | Outbox / scheduled message | /v1/outbox/{ID} |
| num | Virtual number (inbox) | /v1/vmn |
| tpl | Message template | /v1/messagetemplates/{ID} |
| bdy | Birthday message | /v1/birthday-message/{ID} |
| sub | Teammate/Subaccount | /v1/subaccount/{ID} |
| snd | Sender ID | /v1/senderids/{ID} |
| wsn | Sender registration request | /v1/senderids (registration accounts) |
| opt | Opt-out | /v1/optouts/{ID} |
| cus | White label account | /v1/customer |
Error behaviour: a public ID that is corrupt, forged or of the wrong type for the
parameter (e.g. a con_ ID where a group is expected) returns http status code
400 (Bad Request). A well-formed public ID that doesn’t belong to your account returns
404 (Not Found), exactly like a numeric ID.
