Structured Field Values

Address, AddressV2, Date and StringOrNumber each define their own JSON value shape. These shapes are shared across companies; a tenant configuration selects a field’s type and does not redefine that type’s members. Read a field’s typeInfo.kind from its configuration before writing its value. The API validates values against that declared field type on create and update, including values nested in custom objects and policy transactions. Invalid values receive a 400 response with the affected field path. Address and AddressV2 are independent field types with different shapes. A company may configure both. Custom objects such as NumberLimit instead define their members in the tenant’s objects configuration.

Address

Structured postal address as a single flat set of components. Used wherever a property, mailing, or risk location appears in your field model. Address is a permanent field type with its own flat storage contract. It is not an alternate input shape for AddressV2. Required sub-fields: none. A partial address (e.g. street + city, no county) is valid — Address sub-fields are all optional, so partial address values are accepted. (Whether an address must exist at all is governed by the embedding field’s own required condition.)

Sub-field	Type	Required	Description
`street`	string	no	Street number and route (e.g. `"350 5th Avenue"`)
`city`	string	no	City or locality
`state`	string	no	State or first-order administrative region. US: 2-letter postal code
`county`	string	no	County or second-order administrative area
`country`	string	no	Country name
`zipCode`	string	no	Postal / zip code as a JSON string. Always quoted (`"02140"`, never `02140`)

{
  "mailingAddress": {
    "street": "350 5th Avenue",
    "city": "New York",
    "state": "NY",
    "county": "New York County",
    "country": "United States",
    "zipCode": "10001"
  }
}

zipCode must be a JSON string, never a number. JSON numbers cannot represent leading zeros — 02140 parses as 2140, silently corrupting the ZIP. The API rejects numeric zipCode values with 400:

{
  "error": {
    "code": "InvalidAddressZipCode",
    "message": "Field 'mailingAddress.zipCode' must be a string. JSON numbers cannot preserve leading-zero ZIP codes (e.g. \"02109\" parses as 2109); send the value as a string. Got number 2109."
  }
}

This is the most common failure when payloads are generated from spreadsheets, OpenAPI codegen with the wrong type, or LLMs that “helpfully” unquote numeric-looking strings — always quote ZIP codes in your payload.

AddressV2

A postal address modelled as an authoritative entered address plus an optional geocode computed from it. AddressV2 is not a superset of Address — the sub-fields are renamed and re-nested. A payload written for Address is not a valid AddressV2, and vice versa. Check the field’s configured type before writing it; see the warning at the top of this page. Read one half or the other, never a blend. enteredAddress is what a person typed or confirmed, and is the half to render as the address. geocode carries provider output only — county, coordinates, precision. There is deliberately no county in enteredAddress and no street text in geocode. Required sub-fields: none at the top level; all three are optional, as is every sub-field of enteredAddress. The one requiredness rule sits inside geocode: if you send a geocode object at all, status and source must both be present and non-empty.

Sub-field	Type	Required	Description
`enteredAddress`	object	no	The address components as entered or confirmed (table below)
`entryMethod`	string	no	How the address was entered: `"autocomplete"` or `"manual"`. An input modality, not a quality signal — a manually entered address is geocoded exactly like an autocompleted one
`geocode`	object	no	Provider output for the entered address, or `null` when none has been recorded (table below)

`enteredAddress`

Sub-field	Type	Required	Description
`address1`	string	no	Street number and route (e.g. `"350 5th Avenue"`)
`address2`	string	no	Unit, suite, floor or apartment designator (e.g. `"Apt 4"`). Does not affect geocoding
`city`	string	no	City or locality
`state`	string	no	State or first-order administrative region. US: 2-letter USPS code
`zipCode`	string	no	Postal / zip code as a JSON string. Always quoted (`"02140"`, never `02140`)
`countryCode`	string	no	Country code or name supplied by the integration; no code list is enforced

There is no county here. County is provider output and lives on geocode.

`geocode`

Never typed or edited by a user. null when no geocode has been recorded.

Sub-field	Type	Required	Description
`status`	string	yes	`"matched"` (a usable result), `"unmatched"` (the provider ran and returned nothing usable — re-running returns the same nothing), or `"failed"` (errored, timed out, or never ran — the only status worth retrying)
`source`	string	yes	`"resolved"` (the platform called a geocoding provider) or `"provided"` (the caller supplied the result and it was stored as given)
`provider`	string	no	Name of the provider that produced the result. `null` for a caller-supplied geocode
`placeId`	string	no	Provider-specific identifier for the matched place, when the provider returns one
`county`	string	no	County or second-order administrative area as returned by the provider
`location`	object	no	`{ latitude, longitude }` in decimal degrees, or `null` when the provider returned no geometry. Kept as a pair so a consumer never reads one coordinate without the other
`granularity`	string	no	How precisely the coordinates locate the address, and therefore how far `county` can be trusted. Meaningful only when `status` is `"matched"`
`geocodedFromFingerprint`	string	no	Opaque marker of the entered components this result was computed from. Treat as opaque; do not parse it
`geocodedAt`	string	no	ISO-8601 timestamp of when the geocode was produced

granularity, most precise first:

Value	What the coordinates are pinned to
`premise`	A specific building or parcel. The county is that parcel’s own
`route or address range`	The right street, interpolated between known house numbers. Accurate to a block
`postal code`	The ZIP centroid. No street survived the match, and a ZIP can straddle two counties, so the county is inferred from wherever the centroid lands. A PO Box with a valid ZIP lands here
`locality`	The city or town centroid. The weakest county claim on the ladder

Writing an `AddressV2` field

Send enteredAddress. The platform geocodes server-side on save and fills geocode for you:

{
  "mailingAddress": {
    "enteredAddress": {
      "address1": "350 5th Avenue",
      "address2": "Suite 1200",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "countryCode": "US"
    },
    "entryMethod": "manual"
  }
}

Reading the same field back returns the geocode alongside it:

{
  "mailingAddress": {
    "enteredAddress": {
      "address1": "350 5th Avenue",
      "address2": "Suite 1200",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "countryCode": "US"
    },
    "entryMethod": "manual",
    "geocode": {
      "status": "matched",
      "source": "resolved",
      "provider": "google",
      "placeId": "ChIJ...",
      "county": "New York County",
      "location": { "latitude": 40.7484, "longitude": -73.9857 },
      "granularity": "premise",
      "geocodedFromFingerprint": "...",
      "geocodedAt": "2026-08-14T14:32:07.412Z"
    }
  }
}

Four behaviours worth knowing before you write one:

Geocoding never gates the write. A provider miss or outage is recorded as an "unmatched" or "failed" geocode, not a 4xx or 5xx on your save.
You can supply your own geocode. Send it with source: "provided" and it is stored as given, with no provider lookup. A geocode sent with any other source is discarded and replaced by the platform’s own result.
An unchanged entered address keeps its geocode verbatim. address2 is excluded from the components the geocode is computed from, so adding a suite number to an already-matched address does not re-geocode it or lose its match.
Only top-level AddressV2 fields are geocoded on save. An AddressV2 value nested inside a custom object is stored as you send it.

zipCode must be a JSON string, never a number — same reason as on Address. JSON numbers cannot represent leading zeros, so 02140 parses as 2140 and silently corrupts the ZIP. On AddressV2 the path is enteredAddress.zipCode, and a numeric value is rejected with 400 as an ordinary shape violation:

{
  "error": {
    "code": "InvalidFieldModelV1Data",
    "message": "Field 'mailingAddress.enteredAddress.zipCode' expected string, got number"
  }
}

Date

A calendar day pinned to an IANA time zone — the day a person wrote on the policy, not an instant. One canonical form, stored and returned as-is. Required sub-field: date. timezone is optional on a write (it defaults to America/New_York) and is always present in a response.

Sub-field	Type	Required	Description
`date`	string	yes	The calendar day as `YYYY-MM-DD`, zero-padded. Must name a real calendar day — `"2026-02-30"` is rejected with `400`
`timezone`	string	no	IANA time zone identifier (e.g. `"America/New_York"`, `"UTC"`). `"UTC"` and its alias `"Etc/UTC"` are accepted; an unknown zone is rejected with `400`

{
  "inspectionDate": {
    "date": "2026-03-15",
    "timezone": "America/New_York"
  }
}

This shape is accepted on every FMV1 write path — entity CRUD (exposures, events, quotes, custom objects) and policy transactions alike — and responses always use it. The policy term dates are no exception: the root policyStartDate / policyEndDate on policy transactions are ordinary Date fields and accept this canonical object. See the policy transaction endpoints. The policy endorsement deltas channel stores each value exactly as sent, so for a Date field it accepts only this shape, with both sub-fields stated — see the API changelog entry of 2026-09-04.

StringOrNumber

A discriminated value that is either a string or a number, chosen per-row. The two typed slots are mutually exclusive — the inactive one is null. Required sub-fields: kind. The text / number slots are optional (the inactive slot is null).

Sub-field	Type	Required	Description
`kind`	string	yes	Discriminator: `"text"` or `"number"` — selects which slot is populated
`text`	string	no	The string value when `kind` is `"text"`; `null` otherwise
`number`	number	no	The numeric value when `kind` is `"number"`; `null` otherwise

{
  "deductibleOrWaiver": {
    "kind": "number",
    "number": 5000,
    "text": null
  }
}

Cardinality

Any of these field types can appear as a single value or as a list, depending on how the field is configured. List-cardinality fields enforce the same field-type validation per array element — each item must satisfy its type’s value contract.

{
  "additionalLocations": [
    {
      "street": "1 Main St",
      "city": "Cambridge",
      "state": "MA",
      "county": "Middlesex County",
      "country": "United States",
      "zipCode": "02140"
    },
    {
      "street": "500 Boylston St",
      "city": "Boston",
      "state": "MA",
      "county": "Suffolk County",
      "country": "United States",
      "zipCode": "02116"
    }
  ]
}

V1 API Changelog — the strict-validation rule was rolled out on 2026-04-28 and corrected to field-type requiredness on 2026-06-26.

Getting Started

User

Companies

Entities

Submission and Quote Lifecycle

Event Lifecycle

OFAC Screening

Policy Transactions

Financials

Rating

Notes

Tasks

Configuration Management

Company Files

Forms

Document Generation

Submission Parsing

Reference

Structured Field Values

Address

AddressV2

`enteredAddress`

`geocode`

Writing an `AddressV2` field

Date

StringOrNumber

Cardinality

​Address

​AddressV2

​enteredAddress

​geocode

​Writing an AddressV2 field

​Date

​StringOrNumber

​Cardinality

​Related

Address

AddressV2

`enteredAddress`

`geocode`

Writing an `AddressV2` field

Date

StringOrNumber

Cardinality

Related