Value Formats

This page documents the value format accepted on record aliases — the Value property of RecordAliasRequest. The required format depends on the field type the alias maps to.

📘

Same rules apply to submission answers

If you're populating submission answers instead of records, see Answer formats — same encoding rules, different request shape.

Quick reference

📘

Not supported on records

Linked fields are not supported via the records API.

Name

The value is a JSON-encoded string representing an object with first, middle, and last. Include middle only when the underlying field's UseMiddleName is true.

Object shape:

{ "first": "John", "middle": "Michael", "last": "Smith" }

On the wire (note the escaped quotes — this is a string value, not a nested object):

{
  "alias": "client_name",
  "value": "{\"first\":\"John\",\"middle\":\"Michael\",\"last\":\"Smith\"}"
}

{
  alias: "client_name",
  value: JSON.stringify({ first: "John", middle: "Michael", last: "Smith" })
}

new RecordAliasRequest
{
    Alias = "client_name",
    Value = JsonSerializer.Serialize(new { first = "John", middle = "Michael", last = "Smith" })
}

🚧

Common mistake

Sending "value": { "first": "John", ... } (a nested object) will be rejected. The field is typed as a string — the JSON must be serialised first.

Address

Same encoding rule as Name — the value is a JSON-encoded string.

Object shape:

{
  "address": "123 Main St",
  "city": "Brisbane",
  "state": "QLD",
  "zip": "4000",
  "country": "Australia"
}

On the wire:

{
  "alias": "client_address",
  "value": "{\"address\":\"123 Main St\",\"city\":\"Brisbane\",\"state\":\"QLD\",\"zip\":\"4000\",\"country\":\"Australia\"}"
}

{
  alias: "client_address",
  value: JSON.stringify({
    address: "123 Main St",
    city: "Brisbane",
    state: "QLD",
    zip: "4000",
    country: "Australia"
  })
}

All sub-properties except address are optional, but supplying them produces better-rendered documents.

DateTime

Format: yyyy-MM-dd HH:mm (24-hour clock, no timezone).

{ "alias": "engagement_start", "value": "2026-05-14 09:30" }

Email

Any RFC-5322 valid email address.

{ "alias": "client_email", "value": "[email protected]" }

Phone

Free-form. We recommend E.164 (+61412345678) or the locale-formatted variant ((123) 456-7890). The value is not parsed — it is rendered verbatim.

{ "alias": "client_phone", "value": "(123) 456-7890" }

Number and Currency

Digits only, no separators or symbols.

{ "alias": "matter_value", "value": "123456789" }

Id

Format depends on the jurisdiction configured for the underlying field.

{ "alias": "client_abn", "value": "12 234 678 901" }

Option-based fields (Radio, Select, Checkbox)

Put the option's value (its display text) directly in Value. Get the available option values from the form definition under the field's Options array.

• Radio / Select — a single option value:

{ "alias": "client_gender", "value": "male" }

• Checkbox — multiple option values joined by ;:

{ "alias": "preferred_contact", "value": "email;sms;phone" }

🚧

Option values containing ;

If any option value itself contains a semicolon, it will be ambiguous when joined with others. Avoid ; in option labels on fields you intend to populate via records.