Pre-release — content may change.

GuidesCustom Fields

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
}
FieldDirectionDescription
valueread / writeThe actual data for the section. This is the object validated against the JSON schema. Send the complete object when updating.
$schemaread / writeUUID-based schema identifier, formatted as urn:uuid:<uuid>. Identifies which schema the value belongs to.
schema_slugread / writeHuman-readable schema identifier (e.g. custom-fields). Preferred over $schema — see below.
versionread / writeOptimistic-locking version. Send it back to guard against concurrent updates — see Preventing concurrent updates.
keyread-onlyThe schema's key. Informational; not used to route an update.
validread-onlyWhether the stored value passed schema validation. Computed by the server — do not set it.

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.

1. GET the person
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',
);
2 & 3. Modify the complete value, then PATCH
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 as custom-fields. Easier to read and less error-prone.
  • $schema — the UUID-based identifier, formatted as urn: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.

  1. Include the current version (from your GET) in each field you PATCH.
  2. If the stored version has changed since you read it — because someone else saved in the meantime — the request fails with 409 Conflict and code record_conflict.
  3. 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

GET + PATCH with conflict retry
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 GET first
  • Included the complete value (not just the changed properties)
  • Set a schema identifier (schema_slug preferred, or $schema)
  • Included the current version to guard against concurrent updates
  • A plan to retry on 409 record_conflict

On this page