Updating Data via the API
Read and write Additional Info data (data_fields) safely through the API
The values a person or organization has saved in their Additional Info sections are exposed through the API as data_fields — an array on the person or organization resource. This page explains how to read and update them correctly.
The golden rule: always send the complete value for a field. Updating a data_field replaces its stored value entirely — it is not a partial/deep merge. If you PATCH a field with only some of its properties, the omitted properties are removed and the update may fail schema validation. Always start from the current value, modify it, and send the whole thing back.
How data_fields are returned
Each entry in the data_fields array describes one Additional Info section and the data saved against it:
{
"$schema": "urn:uuid:b3427c65-5383-438b-9c8e-409753b08b4e",
"key": "education",
"schema_slug": "custom-fields",
"version": 3,
"value": {
"school": "University of Toronto",
"degree": "bachelor",
"graduationYear": 2018
},
"valid": true
}| Field | Direction | Description |
|---|---|---|
value | read / write | The actual data for the section. This is the object validated against the JSON schema. Send the complete object when updating. |
$schema | read / write | UUID-based schema identifier, formatted as urn:uuid:<uuid>. Identifies which schema the value belongs to. |
schema_slug | read / write | Human-readable schema identifier (e.g. custom-fields). Preferred over $schema — see below. |
version | read / write | Optimistic-locking version. Send it back to guard against concurrent updates — see Preventing concurrent updates. |
key | read-only | The schema's key. Informational; not used to route an update. |
valid | read-only | Whether the stored value passed schema validation. Computed by the server — do not set it. |
Recommended pattern: GET → modify → PATCH
Because an update replaces the whole value, always base your change on the latest data:
GET the current resource
Retrieve the person or organization and read its data_fields array. Keep the value and version for the field you intend to change.
Modify the complete value
Change the properties you need, keeping every other property in the value object intact.
PATCH the full field
Send the field back with its complete value, a schema identifier (schema_slug or $schema), and the version you read in step 1.
Worked example
Suppose a person has the education section above and you want to update only graduationYear.
const res = await fetch(`${apiUrl}/people/${personId}`, {
headers: {
Authorization: `Bearer ${jwt}`,
Accept: 'application/vnd.api+json',
},
});
const person = await res.json();
// Find the field you want to update
const education = person.data.attributes.data_fields.find(
(f) => f.schema_slug === 'custom-fields',
);const updatedField = {
schema_slug: education.schema_slug, // identify the schema
version: education.version, // guard against concurrent edits
value: {
...education.value, // keep every existing property
graduationYear: 2020, // change only what you need
},
};
await fetch(`${apiUrl}/people/${personId}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${jwt}`,
'Content-Type': 'application/vnd.api+json',
},
body: JSON.stringify({
data: {
type: 'people',
id: personId,
attributes: {
data_fields: [updatedField],
},
},
}),
});You only need to include the data_fields you are changing in the PATCH — other sections are left untouched. But within each field you send, the value must be complete.
Schema identification
Every field you update must say which schema its value belongs to. Use one of:
schema_slug(recommended) — a stable, human-readable identifier such ascustom-fields. Easier to read and less error-prone.$schema— the UUID-based identifier, formatted asurn:uuid:b3427c65-5383-438b-9c8e-409753b08b4e.
If you provide both, $schema takes precedence. If you provide only schema_slug, the server resolves it to the matching $schema for you.
The identifier must match a schema that is actually available on that resource. If it doesn't resolve to an available schema, the field is ignored or the update fails validation.
Preventing concurrent updates
data_fields use optimistic locking through the version field so that two clients editing the same section at the same time don't silently overwrite each other.
- Include the current
version(from your GET) in each field you PATCH. - If the stored version has changed since you read it — because someone else saved in the meantime — the request fails with
409 Conflictand coderecord_conflict. - On a conflict, retry: GET the latest data, re-apply your change to the fresh
value, and PATCH again.
A 409 response looks like:
{
"errors": [
{
"status": 409,
"code": "record_conflict",
"source": { "pointer": "/data" },
"title": "Record version conflict",
"detail": "Someone edited this record at the same time you did. Please fetch the latest version and re-issue the request."
}
]
}Retry pattern
async function updateEducationYear(personId, newYear, attempts = 3) {
for (let attempt = 0; attempt < attempts; attempt++) {
// 1. Always read the latest data
const person = await getPerson(personId);
const education = person.data.attributes.data_fields.find(
(f) => f.schema_slug === 'custom-fields',
);
// 2. Merge your change into the complete value
const field = {
schema_slug: education.schema_slug,
version: education.version,
value: { ...education.value, graduationYear: newYear },
};
// 3. Attempt the update
const res = await patchPerson(personId, { data_fields: [field] });
if (res.status !== 409) return res; // success (or a non-conflict error)
// else: someone else updated it — loop and try again with fresh data
}
throw new Error('Could not update after multiple conflicts');
}Omitting version skips the concurrency check — the update will apply regardless of what changed since your read. Include version whenever you want to avoid clobbering concurrent edits, which is almost always.
Validation errors
The value is validated against the section's JSON schema on every update. If it doesn't conform — a required property is missing, an enum value is invalid, a type is wrong — the request fails with a validation error (HTTP 422) that points at data_fields, and nothing is saved for that field. This is another reason to always send the complete, valid value.
Checklist
Before you PATCH a data_field, confirm you have:
- Read the latest value with a
GETfirst - Included the complete
value(not just the changed properties) - Set a schema identifier (
schema_slugpreferred, or$schema) - Included the current
versionto guard against concurrent updates - A plan to retry on
409 record_conflict