Records & data model
Every piece of customer data is a record of an object type. Contacts, companies and orders are built in; your organisation can add more objects and fields. The same endpoints work for all of them; only the objectKey in the path changes.
Objects and fields
An object has a key (contact, order, subscription) and a set of typed fields. Look up an object's fields before writing to it:
curl https://crm.codefab.dev/api/v1/objects/contact/fields \-H "X-API-Key: $CRM_API_KEY"
Field values are validated on every write: types (text, number, date, email, phone, boolean, enum…), required fields and allowed values. A write with problems is rejected as a whole, with one entry per field in errors.
List columns
Which fields the app's record list shows as columns is one choice per object for the whole organisation: PATCH /objects/{objectKey} with {"listColumns": ["first_name", "last_name", "email"]} (at most 8, in order; [] goes back to the automatic choice: name fields, then email, then the rest). A chosen field that can be sorted on is indexed. The record API is not affected: it always returns every field.
A column can also show a linked record's name, such as each contact's company: put "link:<association key>" in listColumns (e.g. "link:contact_company"). POST /api/v1/objects/{objectKey}/records:linkColumns with {"ids": […], "associations": ["contact_company"]} returns, per record, the first three linked records (id, label, objectKey) and the total, which is what the list shows.
Changing a field
PATCH /objects/{objectKey}/fields/{fieldId} changes a field's label, flags (required, unique, indexed, pii) or rules, such as a list field's options, but never its key or type. GET …/fields/{fieldId}/stats shows what a change would run into: empty records (before making a field required), values several records share (before making it unique) and how many records use each option. An option that records still use can't be removed (409 option_in_use); change those values first.
To change the stored values themselves, run a change of values: replace one value with another (or clear it), or fill_empty. Preview it, then start it. It runs in the background, one at a time per organisation:
curl -X POST "https://crm.codefab.dev/api/v1/objects/contact/fields/$FIELD_ID/migrations:preview" \-H "X-API-Key: $CRM_API_KEY" -H "Content-Type: application/json" \-d '{"kind": "replace", "from": "gold", "to": "silver"}'# {"matching": 120, "examples": [{"recordId": "…", "label": "anna@example.com", "before": "gold", "after": "silver"}]}curl -X POST "https://crm.codefab.dev/api/v1/objects/contact/fields/$FIELD_ID/migrations" \-H "X-API-Key: $CRM_API_KEY" -H "Content-Type: application/json" \-d '{"kind": "replace", "from": "gold", "to": "silver"}'
Follow it with GET …/migrations/{id} (status, processed, changed, failed) or stop it with POST …/migrations/{id}:cancel. Each record is changed like an edit, validated and noted on its timeline, but no automation starts because of it.
Creating and updating
| Goal | Request |
|---|---|
| Create a record | POST /objects/{objectKey}/records |
| Create or update by your ID | PUT /objects/{objectKey}/records:upsert |
| Up to many at once | POST /objects/{objectKey}/records:batchUpsert |
| Change some fields | PATCH /objects/{objectKey}/records/{id} |
| Delete | DELETE /objects/{objectKey}/records/{id} |
Prefer upserts for syncs. Send your own identifier as externalId: the first call creates the record, later calls update it. Retrying after a timeout is then always safe.
curl -X POST https://crm.codefab.dev/api/v1/objects/order/records:batchUpsert \-H "X-API-Key: $CRM_API_KEY" \-H "Content-Type: application/json" \-d '{"items": [{ "externalId": "SO-2291", "data": { "order_number": "SO-2291", "total": 1249 } },{ "externalId": "SO-2292", "data": { "order_number": "SO-2292", "total": 389 } }]}'
A batch reports each item separately (created, updated or failed with its errors), so one bad row never blocks the rest.
Linking records
Objects relate to each other through associations, such as a contact's orders. Link two records by association key:
curl -X POST https://crm.codefab.dev/api/v1/objects/contact/records/{contactId}/associations \-H "X-API-Key: $CRM_API_KEY" \-H "Content-Type: application/json" \-d '{ "associationKey": "contact_order", "targetRecordId": "8f14e45f-ceea-4e7a-9b1c-3d2a5c6e7f80" }'
Linked records are listed under /associations on either side, and segments can filter on them ("contacts with an order over 1 000 SEK").
Orders from people and companies
An order belongs to a contact, a company or both. Send at least one of the links contact_order and company_order when you create an order, or the create fails with 400 required_link_missing. A sync can link by your own ids:
{"externalId": "order-58213","data": { "number": "58213", "status": "paid" },"links": [{ "associationKey": "company_order", "targetExternalId": "company-5560001234" }]}
Messages about an order go to the order's contact. When the order has none, they go to the company's contact person: a contact linked to the company through contact_company with the role contact_person. When there are several, the one whose email matches the order's checkout_email gets it. When the company has no contact person, receipts and other transactional messages go to the company's own email or phone field, unless an admin has switched that off under Settings → Email (PUT /api/v1/settings/company-messages). Marketing never goes to a company's own address.
Tags, notes and follow-ups
Records can carry tags (free-form labels used by segments and automations), a timeline of notes, calls, emails and events, and follow-ups, which are tasks with a due date. Each has its own endpoints in the API reference.
Follow-up lists are read a page at a time with GET /api/v1/followups/page (same cursor as below, plus totals: how many match per urgency group). POST /api/v1/followups:bulk completes or deletes many at once, either the ids you give or every follow-up a filter matches:
curl -X POST "https://crm.codefab.dev/api/v1/followups:bulk" -H "X-API-Key: $CRM_API_KEY" -H "Content-Type: application/json" -d '{"action": "complete", "scope": "all", "status": "open", "q": "Contact bounced"}'
The answer says how many changed (changed) and whether more matched than one request handles (more: run it again).
What writes trigger
Creating or changing a record through the API behaves exactly like doing it in the app: it fires record.created / record.updated webhooks, updates segment membership, and can enrol the record in automations whose trigger matches.
Bringing in history (backfill)
When an integration first syncs a shop's existing customers and orders, those writes are history, not news. Nobody should get a "welcome" or "thanks for your order" email for a purchase from last year. Send the header X-Backfill: true on those requests:
curl -X POST https://crm.codefab.dev/api/v1/objects/order/records:batchUpsert \-H "X-API-Key: cfk_…" -H "X-Backfill: true" -H "Content-Type: application/json" \-d '{"items": [ … ]}'
Backfilled writes update records, links, segments, the timeline and webhooks as usual, but start no automations. CSV imports in the app always work this way. Drop the header once the sync is live, so new customers and orders trigger automations again.