Object IDs

Every object of the API has an id. Store it in your system when you need to come back to the object: names and titles can change, IDs never do.

Object	`id`	Example
Card, folder	String	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Event	String with the prefix `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Upload	String with the prefix `upl_`	`"upl_8b0c…"`
OAuth application	String with the prefix `app_`	`"app_5f1c…"`
Collection, user, group, API key, webhook, job and most others	Integer	`3`

Treat IDs as opaque. Do not parse them, and do not assume a format beyond the type: a string ID can be any string, up to the length its field allows.

New kinds of objects that you are likely to refer to from your own systems get string IDs with a short prefix that names the kind, followed by 32 hexadecimal characters.

References between objects

Objects refer to each other by ID, in fields named <object>_id: collection_id, owner_id, folder_id. To get the related object in the same response, use expand[].

Path parameters that take an ID are named the same way: {card_id}, {webhook_id}, {upload_id}.

Collections by ID

Collections have both an id and a unique name, such as support. Paths that existed before IDs were preferred take the name of the collection:

GET /v1/collections/support/stats

The same paths also take the ID, written as id:<number>:

curl https://api.example.com/v1/collections/id:3/stats \
  -H "Authorization: Bearer $SURSA_API_KEY"

Prefer the id: form in new code: an administrator can rename a collection, but its ID stays the same. A segment of digits alone, such as /v1/collections/3, still means the collection named 3. A collection name cannot contain :, so the two forms never mix up.

In request bodies and query parameters, collection_id stands next to the earlier collection (the name). When you pass both, collection_id wins. A collection_id that does not exist in the organization, or that the key is not allowed to see, returns 404 with the code collections.not_found.

curl -G https://api.example.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "collection_id=3"

Your own IDs

Cards can carry the ID of the record they come from in your system, in external_id: up to 512 characters, unique among the cards of the organization. With it you never have to store the Sursa ID of a card:

Endpoint	What it does
`PUT /v1/cards-by-external-id/{external_id}`	Creates the card, or replaces its content if it exists.
`GET /v1/cards-by-external-id/{external_id}`	Reads the card.
`GET /v1/cards?external_id=…`	Finds the card in a list, with other filters.

URL-encode the external_id when it is part of the path: crm/A-1042 becomes crm%2FA-1042.

Documents of a custom source have their own external_id within their source. The two do not collide: a card of a custom source is changed by sending the document to its source again, not with PUT /v1/cards-by-external-id/…, which answers 409 with the code cards.managed_by_source in that case.