Fields

Use these endpoints to retrieve field definitions and create or update custom fields in your team's Apollo workspace. You can define the information your team captures for contacts, accounts, and deals, then use field IDs when adding values to individual records.

Key concepts

System and custom fields	System fields are built into Apollo. Custom fields capture information specific to your team, including custom contact fields and custom account fields. Use `source` to retrieve system, custom, or CRM-synced fields. Only custom fields can be updated through these endpoints.
Modality and field type	Modality identifies which records use the field: `contact`, `account`, or `opportunity` for deals. Type determines the values the field accepts, such as text, numbers, dates, or booleans. Choose the type when creating the field; it can't be changed afterward.
Identifying a field	Get a list of fields returns IDs in `modality.field_id` format. Use the full ID when updating a field's definition. When setting a custom field value through `typed_custom_fields`, use only the part after the dot as the key. For example, `contact.507f1f77bcf86cd799439011` becomes `507f1f77bcf86cd799439011`. Picklist options have separate IDs that identify the available choices.
Field definitions and record values	Creating or updating a custom field changes its definition, such as its label or available options. To set the field's value on a specific contact, account, or deal, use the corresponding create or update endpoint for that record.

Choose an endpoint

I want to . . .	Use this
Retrieve field definitions, optionally filtered by source	Get a list of fields
Retrieve only custom field definitions	Get a list of fields with `source` set to `custom`
Create a custom field for contacts, accounts, or deals	Create a custom field
Change a custom field's label or configuration	Update a custom field

Get a list of all custom fields is deprecated. Use get a list of fields with source set to custom instead.

Example workflows

Capture qualification details on contacts
Update a custom fields configuration

Capture qualification details on contacts

Create a field for qualification research, then save a value on a contact.

Call get a list of fields with source set to custom to check whether a suitable contact field already exists.
If you need a new field, call create a custom field with a label, modality set to contact, and type set to textarea for multi-line research notes. Then retrieve the new field with get a list of fields.
From the selected field's id, retain only the part after the dot. For example, if the ID is contact.507f1f77bcf86cd799439011, use 507f1f77bcf86cd799439011 as the custom field key.
Call search for contacts to find the saved contact and retain their id.
Pass the contact ID to update a contact. In typed_custom_fields, use the custom field key from step 3 with the research notes as its value.

The field definition can be reused across contacts. Each contact stores its own value.

Learn more: Use the create a custom field and update a contact references to dig in to the workflow.

Update a custom field's configuration

Adjust an existing field as your team's information needs change.

Call get a list of fields with source set to custom. Identify the field and retain its full id, including the modality prefix, and current configuration.
Pass an object containing the field ID and the changes in the fields array of update a custom field. For example, include label to rename the field. Update one field per request.

Field configuration changes apply across records that use the field. For picklist fields, include every option you want to keep in meta.picklist_values, even when only renaming the field. Preserve existing option IDs to retain stored values; omitted options are removed.

Learn more: Use the update a custom field reference to explore supported changes and picklist handling.