Records and ids

Identifiers are opaque strings. Never assume their format, length or ordering, and never build one. Pagination cursors are opaque in the same way. Human numbers such as orderNumber or contactNumber are for people: use id to address a record.

Only some resources have a writable field for a reference from your system. The table is generated from the spec.

POST /api/v1/contacts/lookup takes up to 200 references and compares each one, exactly and without any normalisation, with the contactNumber of the contacts, and with nothing else. It returns two lists: notFound, the references that match no contact, and contacts, the contacts that matched, each with id, name and contactNumber. It writes nothing, even though it is a POST.

The response does not pair a reference with a contact, and the order of contacts is not guaranteed. Pair them yourself by comparing each contact's contactNumber with your reference. Because contactNumber is not unique, several contacts may come back for one reference: decide what to do in that case instead of taking the first one. Use notFound to learn what to create, and keep the Filmo id in your own table once you have it.

Store your external id and the Filmo id side by side in your own database. An Idempotency-Key only deduplicates retries for 24 hours; it does not replace that table (Idempotency). With the table you can update the right record, detect duplicates and decide what to delete. For the pattern in a CRM, see the contact sync tutorial.

The values of custom fields are read in the customFields map of a record, keyed by the identifier of the field definition. The definitions come from GET /api/v1/custom-fields, with the entity each applies to (applyAt), the type and the values a dropdown accepts. Values travel inside each resource; the definitions endpoint does not return them. v1 has no operation that writes a custom field: the create and update bodies have no customFields property, so set them in the app.

• Tags: GET /api/v1/tags returns the vocabulary with how many entities use each. POST /api/v1/tags/{tagId}/assignments attaches an existing tag to an entity. DELETE /api/v1/tags/{tagId}/assignments removes the link and does not delete the tag.
• Notes: POST /api/v1/notes writes a note on an entity, and GET /api/v1/notes reads the notes of one entity, never all of them. Who wrote a note is not returned. Mentioning users notifies them in Filmo.