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
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
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

GoalRequest
Create a recordPOST /objects/{objectKey}/records
Create or update by your IDPUT /objects/{objectKey}/records:upsert
Up to many at oncePOST /objects/{objectKey}/records:batchUpsert
Change some fieldsPATCH /objects/{objectKey}/records/{id}
DeleteDELETE /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
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
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:

JSON
{
"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
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
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.