JSON custom profile fields

Preview feature

The JSON custom field type is in preview and may be subject to change. Please contact us to provide feedback.

Text and date custom profile fields hold a single value each. A JSON custom field holds a whole structured object instead, so related data stays together in one field on the customer profile.

You can optionally attach a JSON Schema to the field. The schema does two jobs: Atomic rejects data that does not match it, and every value the schema describes becomes individually selectable when you build an Action Flow.

Example use-cases

• Account or product data: store a customer's list of accounts, each with a balance, type and opening date, then personalize a card with the balance of a specific account.
• Policy or claim details: keep the details of an insurance policy together, and branch an Action Flow on the renewal date or cover level.
• Preferences and settings: hold a nested set of communication preferences, and check one of them before sending.
• Loyalty or rewards status: store tier, points balance and expiry together so a single field drives both targeting and card content.

Add a JSON custom field

1. Go to Configuration > Customer profiles > Custom fields. Alternatively, open the command palette and type 'Field'.
2. Click New field.
3. Give the field a Field label. The Field name is generated for you, and cannot be changed after the field is created.
4. Set Field type to JSON (preview).
5. Optionally paste a schema into Field JSON Schema. See Using a JSON Schema below.
6. Click Save.

Using a JSON Schema

The schema is optional, but we recommend adding one. It is written in JSON Schema format, and it is what makes the field's individual values available to Action Flows.

Here is a schema for an example customer's savings products:

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "products": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "fundType": {"type": "string"},
          "lastDeposit": {"type": "string"}
        }
      }
    },
    "metrics": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "productsCount": {"type": "number"}
      }
    }
  }
}

A few things worth knowing:

• Add "additionalProperties": false to each "object" in your schema. Without it, any extra, unknown key-value pair sent to Atomic is accepted and stored.
• Use "required" to list the properties that must be present.
• You can reuse a shape by putting it in definitions or $defs and pointing at it with $ref, as long as the reference stays within the same schema.
• The editor checks that your schema is valid JSON as you type. You cannot save the field while it is invalid.
• With no schema, Atomic stores whatever valid JSON you send without checking its shape, and none of the field's values are offered in the Action Flow context picker.

What happens when data does not match

If a schema is set, every write to the field is checked against it:

• The Users API rejects the request with a 400 response and an error naming the field, for example Profile data for field Kiwisaver is invalid against schema. No part of the profile update is applied.
• In the Workbench, the customer record shows JSON is invalid against schema and Save stays disabled.

Add data to a JSON field

You can populate a JSON custom field in several ways.

Users API. Send the value as normal JSON, nested inside the profile:

{
  "users": [
    {
      "id": "customer-123",
      "profile": {
        "kiwisaver": {
          "products": [{"fundType": "growth", "lastDeposit": "2026-01-01"}],
          "metrics": {"productsCount": 1}
        }
      }
    }
  ]
}

The SDKs. Update the profile from your app in the same shape you would use for any other custom field.

JWT claim mapping. You can map a claim from your JWT onto a JSON custom field. The claim can be a structured object or array, or a JSON-encoded string, and Atomic stores it either way. A claim that is not valid JSON, or that fails the field's schema, is skipped and the rest of the profile still updates.

Manually in the Workbench. Open a customer from the Customers screen, choose the Custom fields tab, and edit the value directly.

Use JSON values in Action Flows

Wherever you can insert a customer value in an Action Flow, open the context picker and look under Profile values. Each value described by your schema appears there on its own, named field label.path, for example Kiwisaver.metrics.productsCount.

Selecting one inserts a reference to that single value, so you can use it in card content, conditions, variables and request bodies just like a text or date field.

Values inside an array are addressed by position, so the first product's fund type is products.0.fundType.

Filter and segment on a JSON field

JSON fields support one filter condition: Contains Shape. You supply a fragment of JSON, and the filter matches customers whose field contains it.

For example, this matches every customer with at least one growth fund:

{"products": [{"fundType": "growth"}]}

You can use the same condition when building a segment.

FAQs and troubleshooting

Do I have to provide a schema?

No. Without one, Atomic stores any valid JSON you send. You will not get validation, and the field's individual values will not appear in the Action Flow context picker, so most customers should add one.

I added a schema but no values appear in the context picker.

Atomic reads the paths from the properties and items in your schema, following any $ref that points inside the same schema. A $ref to another document, such as a URL, cannot be resolved, so write those definitions into the schema itself. A schema with no properties or items describes no addressable values and produces no paths.

Can I change a field from text to JSON, or edit the schema later?

You can change the type and edit the schema at any time. Existing data is not migrated or re-checked, so a customer's stored value can predate the current schema. The next write to that customer's profile is validated against the new schema.

Can I import JSON fields from a CSV?

Not currently. The CSV importer handles text and date custom fields only. Use the Users API or the SDKs for JSON fields.

How large can the value be?

There is no hard limit, but keep values to the data you actually use in Action Flows and targeting. Large profile values slow down every read of that customer's profile.

Who can create custom fields?

Creating and editing custom fields requires edit permission on the environment. See the Permissions guide.