Objects, fields and records
The data model: fourteen standard objects, nineteen field kinds in five families, what a record stores, and which parts of a live object can still change.
An object is a kind of thing a workspace keeps — an account, a quote, a task. A field is one piece of information an object’s records hold. A record is one instance. Every endpoint under /objects works on one of those three.
Standard objects
Fourteen standard objects exist, and each belongs to a module. POST /bootstrap installs the ones the workspace’s enabled modules own, so which objects a workspace has depends on what it has switched on. Running it again leaves already-installed objects as they are.
| Module | Objects |
|---|---|
| core, always on | account 取引先 · contact 取引先責任者 · lead リード · opportunity 商談 · activity 活動 · event 行動 · task タスク · note ノート |
cpq |
product 商品 · quote 見積 · quote_line_item 見積明細 · contract 契約 |
marketing |
campaign キャンペーン · campaign_member キャンペーンメンバー |
Read GET /objects rather than assuming the full list. marketing has no endpoint in this API at all, so its two objects exist but are not reachable through it.
The labels are Japanese, and so are the select options on standard fields. A label is display copy — what a user sees in the application — and it is stored once rather than translated per request, so it comes back in the language the product is authored in. Match on the key, never on the label.
activity (活動) and event (行動) are different objects and a frequent confusion. An activity is a logged contact, carrying the channel it came through, its result and how warm it left the lead. An event is a scheduled meeting, carrying a type and how it shows on a calendar.
Field kinds
Nineteen kinds exist, in five families. What a family is decides whether you can write it, filter it, or configure it.
Thirteen scalar kinds are stored in one column and configured by nothing but their type: text, longtext, decimal, currency, percent, boolean, date, datetime, email, url, phone, user, address.
| Kind | What it holds |
|---|---|
text |
A single line, at most 16,384 characters |
longtext |
A document — a note’s body, minutes — at most 1,000,000 characters, bounded by the request size rather than the line limit |
decimal, currency, percent |
A decimal string, never a number. See conventions |
date |
YYYY-MM-DD |
datetime |
ISO 8601 with an offset; a value without one is refused |
email, url, phone |
A validated address, an http/https URL, a string of at most 255 characters |
user |
A user id. Whether that user belongs to the organization is checked by the application; the column itself is text |
address |
Five parts — postalCode, prefecture, city, street, building — a Japanese address, not a free-form one |
Two option kinds, select and multi_select, hold values from a list the field defines. A multi-select takes at most 200 options and refuses a repeat.
relation points at a record in another object. The field names its targetObjectId and its cardinality when it is created.
formula computes one arithmetic step, not an expression: left, an operator from add, subtract, multiply, divide, and right, where each side names another field by key.
Two virtual kinds, rollup and days_since, have no column at all: the client computes them from other records or fields. Nothing is stored and nothing can be written, so a record write that carries one is refused with field_not_scalar.
What a record stores
A record answers id, objectId, name, revision, createdAt, updatedAt, archivedAt, values — one entry per field — and, when the object has relation fields, relations.
name and updated_at are reserved filter and sort keys, which is a different list from the response shape above: a view sorts on updated_at, while a response carries updatedAt.
Empty is one state, not five. An absent key, null, a blank string, an empty multi-select, and an address with every part blank are all the same thing, and all stored as no value. Reading one back gives null whichever form you sent.
A select option is its own stored value, so writing an option the field does not offer is refused with field_value_invalid. On the standard fields that means an option list is only ever added to, never renamed: the old string is what the existing records hold.
Creating and changing a field
Adding an object or a field needs the custom_objects module; reading and writing records does not.
POST /objects/{objectId}/fields takes a different body per family — seven shapes in all. Every one carries key, label, required and visibleByDefault; the option families add options, at most 200 of them, each 1 to 120 characters; a relation adds targetObjectId.
Almost nothing about a field moves once it exists. PATCH accepts key, type and targetObjectId but refuses to change them, and it does not accept options at all. Only label and required are adjustable. Plan the key, the kind and the option list before the field has records; see custom objects.
visibleByDefault is list metadata: whether a list shows the field before anyone picks columns. It has nothing to do with who may read the field — that is permissions.
Converting a lead
A lead becomes an account and a contact. GET /objects/{objectId}/records/{recordId}/conversion-matches finds candidates to merge into instead of creating duplicates.
The scan is bounded. partial: true means the scan stopped before it ran out of records, so finding nothing proves nothing. Treat an empty result under partial as “unknown”, not as “no match exists”.