API reference

Custom fields

Custom fields are the fields a workspace adds to its records — a region, a renewal date, a contract number. Read their definitions here; read and write their values in each record’s custom_fields.

Scope: The read scope of the record type
Records: Contacts, companies, deals, leads, tasks
Access: Read-only definitions

The custom field object

Fields are created and edited in the app. Use key in your code, not label: labels are for people, and get renamed.

Attributes

keystring
The key under custom_fields on records, for example region.
labelstring
The name shown in the app.
typeenum
The value type. See value formats.
One oftextlong_textnumbercurrencypercentdatedatetimeselectmulti_selectcheckboxurlemailphoneuserrelationtagsformulalookup
optionsobject[]
The choices of select, multi_select and tags fields; empty for other types.
- idstring
  What records store: write this value.
- labelstring
  What the app shows.
- colorstring
  Option colour as a hex code.
requiredboolean
Whether the app requires a value.
entityenum
The record type the field belongs to.
One ofcontactcompanydealleadtask

The custom field object

{
  "key": "region",
  "label": "Region",
  "type": "select",
  "options": [
    {
      "id": "emea",
      "label": "EMEA",
      "color": "#64748b"
    },
    {
      "id": "amer",
      "label": "Americas",
      "color": "#94a3b8"
    },
    {
      "id": "apac",
      "label": "APAC",
      "color": "#475569"
    }
  ],
  "required": false,
  "entity": "contact"
}

Writing values

Records carry their values in custom_fields, keyed by field key. An update merges what you send into what is stored: keys you leave out keep their values, and null clears a key.

Set one field, clear another

curl -X PATCH https://acme.nextora.co/api/v1/contacts/3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": {
      "region": "apac",
      "renewal_date": null
    }
  }'

Response200 OK

{
  "data": {
    "id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "first_name": "Ada",
    "last_name": "Brennan",
    "full_name": "Ada Brennan",
    "email": "[email protected]",
    "phone": "+44 20 7946 0958",
    "position": "Head of Operations",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "company": {
      "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
      "name": "Northwind Analytics"
    },
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "tags": [
      "enterprise",
      "renewal-2027"
    ],
    "source": "website",
    "custom_fields": {
      "region": "apac"
    },
    "last_activity_at": "2026-10-08T14:12:09Z",
    "created_at": "2026-09-14T09:30:00Z",
    "updated_at": "2026-10-10T09:48:02Z"
  }
}

Use the keys from the definitions, with values in the format of the field’s type.

Value formats

Type	Value	Example
`text`, `long_text`, `url`, `email`, `phone`	String	`"EMEA expansion"`
`number`, `currency`, `percent`	Number	`4200000`
`date`	String, `YYYY-MM-DD`	`"2027-01-31"`
`datetime`	String, ISO 8601	`"2026-11-02T09:00:00Z"`
`checkbox`	Boolean	`true`
`select`	An option’s `id`	`"emea"`
`multi_select`, `tags`	Array of option `id`s	`["emea", "apac"]`
`user`	A user ID	`"6a2d9c4e-1f8b-4e3a-b7d5-9c0e2f4a6b18"`
`relation`	A record ID, or an array of IDs when the field links several	`"2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56"`
`formula`, `lookup`	Computed by Nextora; read-only	—

List custom fields

GET/api/v1/custom-fields

Requires the read scope of the record type: contacts:read for contact, companies:read for company, deals:read for deal, leads:read for lead, tasks:read for task.

Returns the custom-field definitions of one record type.

Query parameters

entityenumRequired
The record type.
One ofcontactcompanydealleadtask

Returns

A list of custom field objects.

GET/api/v1/custom-fields

curl -G https://acme.nextora.co/api/v1/custom-fields \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -d entity=contact

Response200 OK

{
  "data": [
    {
      "key": "region",
      "label": "Region",
      "type": "select",
      "options": [
        {
          "id": "emea",
          "label": "EMEA",
          "color": "#64748b"
        },
        {
          "id": "amer",
          "label": "Americas",
          "color": "#94a3b8"
        },
        {
          "id": "apac",
          "label": "APAC",
          "color": "#475569"
        }
      ],
      "required": false,
      "entity": "contact"
    },
    {
      "key": "renewal_date",
      "label": "Renewal date",
      "type": "date",
      "options": [],
      "required": false,
      "entity": "contact"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}