Public API Custom Fields Endpoint

This endpoint returns the custom fields configured on a brayv.ai account, so an external system can discover the exact keys, types, and options to send inside custom_fields on the Lead Submission API and the Contact Update API.

Endpoint

GET https://api.brayv.ai/v1/accounts/{account_id}/custom-fields
Authorization: Bearer {api_key}

Replace {account_id} with the brayv.ai account ID whose custom fields you need.

Authentication

Send the API key in the Authorization header:

Authorization: Bearer brayv_live_...

The same keys used for lead submission work here. A key is scoped to either one account or an organization that has access to the target account. Rate limits are shared with the other public endpoints, per key and per account.

Query Parameters

Parameter	Type	Default	Notes
`include_inactive`	boolean	`false`	Also return custom fields that have been deactivated in brayv.ai. Deactivated fields are not accepted by the lead or contact endpoints.

Response

An array of custom fields, sorted by name.

[
  {
    "id": "lead_priority",
    "name": "Lead Priority",
    "field_type": "select",
    "options": ["Low", "Medium", "High"],
    "is_active": true
  },
  {
    "id": "preferred_service_date",
    "name": "Preferred Service Date",
    "field_type": "date",
    "options": null,
    "is_active": true
  },
  {
    "id": "service_type",
    "name": "Service Type",
    "field_type": "multiselect",
    "options": ["HVAC", "Plumbing", "Electrical"],
    "is_active": true
  }
]

Field	Meaning
`id`	The key to use inside `custom_fields`. Generated from the field's name when it was created and does not change if the field is renamed.
`name`	The label shown in brayv.ai.
`field_type`	One of `text`, `number`, `date`, `select`, `radio`, `multiselect`, `checkbox`.
`options`	The configured choices for `select`, `radio`, and `multiselect` fields. `null` for other types.
`is_active`	Whether the field is currently in use.

Using the Result

Send values keyed by id:

{
  "custom_fields": {
    "lead_priority": "High",
    "preferred_service_date": "2026-10-02",
    "service_type": ["HVAC", "Plumbing"]
  }
}

Expected values by field_type:

`field_type`	Expected value	Behavior
`text`	string	Saved as submitted.
`number`	number or numeric string	Saved if numeric, otherwise ignored.
`date`	parseable date string	Saved as `YYYY-MM-DD`, otherwise ignored.
`select`	string matching one of `options`	Case-insensitive match. Non-matching values ignored.
`radio`	string matching one of `options`	Case-insensitive match. Non-matching values ignored.
`multiselect`	string or string[] matching `options`	Matching options are saved. Non-matching options ignored.
`checkbox`	boolean-like value	Accepts `true`, `false`, `1`, `0`, `yes`, `no`, `y`, `n`, `on`, `off`, `t`, `f`.

A custom field value that does not validate never fails the request. It is dropped and reported in that request's ignored_fields.

Custom field IDs are stable, so it is safe to fetch this list once during setup and cache it. Fetch it again when the account adds a field or changes a field's options.

Errors

Status	When
`401`	Missing or invalid API key.
`403`	Key is not authorized for this account.
`404`	Account not found.
`429`	Rate limit exceeded for this key and account.

This endpoint is read-only and is available while an account is paused for a payment issue or inactive, so an integration can still look up field IDs while billing is being sorted out.

Example cURL

curl "https://api.brayv.ai/v1/accounts/ACCOUNT_ID/custom-fields" \
  -H "Authorization: Bearer brayv_live_YOUR_API_KEY"

With deactivated fields included:

curl "https://api.brayv.ai/v1/accounts/ACCOUNT_ID/custom-fields?include_inactive=true" \
  -H "Authorization: Bearer brayv_live_YOUR_API_KEY"

Related Articles