Field and custom-field definitions across contacts, accounts and opportunities. 4 operation(s) from the published Apollo OpenAPI.
openapi: 3.1.0
info:
title: Apollo.io Fields API
version: '1.0'
summary: Programmatic access to Apollo's sales intelligence and engagement platform — data enrichment,
prospect and company search, and go-to-market workflow management.
description: 'The Apollo API provides programmatic access to [Apollo](https://www.apollo.io/), the all-in-one
sales intelligence and engagement platform. Use it to enrich people and company data (individually
or in bulk), search Apollo''s database of over 240 million contacts and 30 million companies, and
manage accounts, contacts, deals, sequences, tasks, calls, and conversations in your go-to-market
workflows.
## Base URL
All API requests are made to `https://api.apollo.io/api/v1`.
## Authentication
- **Apollo users** authenticate with an API key passed in the `x-api-key` request header. See [Create
API Keys](https://docs.apollo.io/docs/create-api-key).
- **Apollo partners** building integrations on behalf of mutual users authenticate with the [OAuth
2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).
## Rate limits & credits
Rate limits and credit consumption depend on your [Apollo pricing plan](https://docs.apollo.io/docs/api-pricing).
Check your current limits and usage with the [View API Usage Stats and Rate Limits](https://docs.apollo.io/reference/view-api-usage-stats)
endpoint. For more details, see [Rate Limits](https://docs.apollo.io/reference/rate-limits) and the
[API FAQs](https://docs.apollo.io/docs/apollo-api-faqs).
New to the API? Start with the [Apollo API overview](https://docs.apollo.io/reference/apollo-api).'
termsOfService: https://www.apollo.io/terms/api
contact:
name: Apollo API Support
url: https://docs.apollo.io/
servers:
- url: https://api.apollo.io/api/v1
tags:
- name: Fields
description: List, create, and update the fields and custom fields in your Apollo account.
security:
- apiKey: []
- bearerAuth: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: '[Recommended] API key, passed in the `x-api-key` request header.
See [Create API Keys](https://docs.apollo.io/docs/create-api-key).'
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'OAuth 2.0 access token, used by Apollo partners building integrations.
See the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).'
paths:
/fields:
get:
summary: Get a List of Fields
description: '## Endpoint essentials
**API key access:** `api/v1/fields/index` or `Master API key`
**OAuth scopes:** `custom_fields_list`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
Use the Get a List of Fields endpoint to retrieve information about all of the fields that exist
in your Apollo account.'
tags:
- Fields
operationId: get-a-list-of-fields
parameters:
- name: source
in: query
required: false
schema:
type: string
enum:
- system
- custom
- crm_synced
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
fields:
- id: contact.id
category: person
context:
- finder
- csv_export
description: null
editable: false
example: 673c929202c6025d8bc4e680
field_name: contact.id
group: basic_info
icon_class: user
label: Identifier
modality: contact
parent: null
source: system
type: string
finder_view_ids: []
project_workspace_id: null
finder_views: []
is_local: false
- id: contact.attr1
category: person
context:
- finder
- csv_export
description: null
editable: false
example: Test Corp
field_name: contact.attr1
group: basic_info
icon_class: company
label: Person
modality: contact
parent: null
source: system
type: association
finder_view_ids: []
project_workspace_id: null
finder_views: []
is_local: false
- id: contact.attr2
category: person
context:
- prompt
- formula
- snippets
- finder
description: null
editable: false
example: John
field_name: contact.attr2
group: basic_info
icon_class: user
label: First name
modality: contact
parent: contact.name
source: system
type: string
finder_view_ids: []
project_workspace_id: null
finder_views: []
is_local: false
- id: account.694095a80f1b6000110fc556
category: company
context:
- csv_export
- finder
- prompt
description: null
editable: false
example: null
field_name: Custom field name
group: null
icon_class: null
label: last name
modality: account
parent: account.other_custom_field
source: custom
type: string
finder_view_ids: []
project_workspace_id: null
finder_views: []
is_local: false
created_at: '2025-12-15T23:11:36.084Z'
schema:
type: object
properties:
fields:
type: array
items:
type: object
properties:
id:
type: string
label:
type: string
modality:
type: string
description: Entity type this field belongs to (contact, account, opportunity,
lead, custom_object)
context:
type: string
description: High‑level context for the field (contact, account, opportunity,
lead, custom_object)
type:
type: string
description: Field data type (text, number, date, datetime, boolean, picklist,
multi_select, url, email, phone, currency)
source:
type: string
description: Field source (system, custom, crm_synced)
project_workspace_id:
type: string
meta:
type: object
additionalProperties: true
description: Extended configuration for the field
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- label
- modality
- type
'401':
description: '401'
content:
text/plain:
examples:
Check API key:
value: Invalid API key. See https://docs.apollo.io/reference/authentication for how
to authenticate.
'403':
description: '403'
content:
application/json:
examples:
Need master API key:
value: "{\n \"error\": \"This API key is not authorized to access api/v1/fields/index.\
\ Request an API key from your administrator that includes this endpoint in its configured\
\ scope.\",\n \"error_code\": \"API_INACCESSIBLE\"\n}"
schema:
type: object
properties:
error:
type: string
example: This API key is not authorized to access api/v1/fields/index. Request an
API key from your administrator that includes this endpoint in its configured scope.
error_code:
type: string
example: API_INACCESSIBLE
'429':
description: '429'
content:
application/json:
examples:
Too many requests:
value: "{\n \"message\": \"The maximum number of API calls allowed for api/v1/fields\
\ is 600 times per hour. To change your rate limit, upgrade your Apollo plan at https://app.apollo.io/#/settings/plans/upgrade.\"\
\n}"
schema:
type: object
properties:
message:
type: string
example: The maximum number of API calls allowed for api/v1/fields is 600 times per
hour. To change your rate limit, upgrade your Apollo plan at https://app.apollo.io/#/settings/plans/upgrade.
post:
summary: Create a Custom Field
description: '## Endpoint essentials
**API key access:** `api/v1/fields/create` or `Master API key`
**OAuth scopes:** `custom_field_write`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
The Create a Custom Field endpoint lets you add custom fields to your Apollo account, helping
your team capture unique details with <a href="https://knowledge.apollo.io/hc/en-us/articles/4412498825869-Create-Custom-Contact-Fields"
target="_blank">custom contact</a>, <a href="https://knowledge.apollo.io/hc/en-us/articles/4412498754445-Create-Custom-Account-Fields"
target="_blank">custom account</a>, or <a href="https://knowledge.apollo.io/hc/en-us/articles/4415062486669-Create-a-Deal"
target="_blank">custom deal fields</a>.<br><br>Use these fields to enhance your sequences and
deliver more personalized, relevant outreach.'
tags:
- Fields
operationId: create-a-custom-field
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
label:
type: string
description: 'Name of the custom field you want to create. Example: `Test Name`'
modality:
type: string
description: 'The modality of the custom field you want to create. Example: `contact`'
enum:
- contact
- account
- opportunity
type:
type: string
description: 'What kind of custom field you want to create. Example: `textarea`'
enum:
- string
- textarea
- number
- date
- datetime
- boolean
meta:
type: object
properties:
max_length:
type: number
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
typed_custom_fields:
- id: 32d42c92-5be4-4ec4-96c7-f689b43ec8a8
name: Test Name
modality: contact
text_field_max_length: 120
schema:
type: object
properties:
typed_custom_fields:
type: array
items:
type: object
properties:
id:
type: string
example: 32d42c92-5be4-4ec4-96c7-f689b43ec8a8
name:
type: string
example: Test Name
modality:
type: string
example: contact
text_field_max_length:
type: number
example: 120
'401':
description: '401'
content:
text/plain:
examples:
Check API key:
value: Invalid API key. See https://docs.apollo.io/reference/authentication for how
to authenticate.
'403':
description: '403'
content:
application/json:
examples:
Need master API key:
value: "{\n \"error\": \"api/v1/fields this api_key\",\n \"error_code\": \"API_INACCESSIBLE\"\
\n}"
schema:
type: object
properties:
error:
type: string
example: This API key is not authorized to access api/v1/fields. Request an API key
from your administrator that includes this endpoint in its configured scope.
error_code:
type: string
example: API_INACCESSIBLE
deprecated: false
patch:
summary: Update a Custom Field
description: '## Endpoint essentials
**API key access:** `api/v1/fields/update` or `Master API key`
**OAuth scopes:** `custom_field_write`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
Use the Update a Custom Field endpoint to change fields that already exist in your Apollo Workspace,
such as renaming a field, changing the maximum length of a text field, or updating the values
available in a picklist.<br><br>Pass the field under the `fields` array, where each object identifies
the field by its unique `id`. To find field IDs, call the <a href="https://docs.apollo.io/reference/get-a-list-of-fields">Get
a List of Fields</a> endpoint with `source: custom`. Update 1 field per request.<br><br>Only custom
fields can be updated. System fields, and the child fields of a JSON field, cannot be updated.<br><br>Apollo
only changes the parameters you include in your request, so you can omit any parameter that you
want to leave as-is.<br><br><b>Updates overwrite the field''s current configuration.</b> The values
you send replace the field''s existing configuration for every record of that modality, and the
change cannot be cleanly undone. Removing or renaming picklist options in particular can drop
or rewrite data already stored on your records.<br><br><b>Picklist fields:</b> every update to
a `picklist` or `multipicklist` field must include the complete set of options you want to keep
in `meta.picklist_values`, even when you are only renaming the field.'
tags:
- Fields
operationId: update-a-custom-field
requestBody:
required: true
content:
application/json:
examples:
Rename a field:
value:
fields:
- id: contact.694095a80f1b6000110fc556
label: Renewal owner
Change the maximum length of a text field:
value:
fields:
- id: contact.694095a80f1b6000110fc556
meta:
max_length: 240
Add an option to a picklist field:
value:
fields:
- id: account.694095a80f1b6000110fc557
meta:
picklist_values:
- id: 694095a80f1b6000110fc561
name: Gold
- id: 694095a80f1b6000110fc562
name: Silver
- name: Platinum
Rename a picklist option without losing stored values:
value:
fields:
- id: account.694095a80f1b6000110fc557
meta:
picklist_values:
- id: 694095a80f1b6000110fc561
name: VIP
- id: 694095a80f1b6000110fc562
name: Silver
schema:
type: object
required:
- fields
properties:
fields:
type: array
description: The field you want to update. Apollo only changes the parameters you include,
so you can omit any parameter you want to leave as-is. Update 1 field per request.
items:
type: object
required:
- id
properties:
id:
type: string
description: 'The ID of the field you want to update, in `modality.field_id` format.
<br><br>To find field IDs, call the <a href="https://docs.apollo.io/reference/get-a-list-of-fields">Get
a List of Fields</a> endpoint with `source: custom` and use the `id` value of
the field you want to change. <br><br>Only custom fields can be updated. System
fields and child fields of a JSON field cannot be updated. <br><br>Example:
`contact.694095a80f1b6000110fc556`'
modality:
type: string
description: <b>Read-only. This parameter cannot be updated.</b> A field's modality
is set when the field is created and is fixed for the life of the field. If
you include `modality` in your request, Apollo ignores the value you send and
keeps the field's existing modality, so the call succeeds but the modality does
not change. <br><br>To capture the same data against a different modality, use
the <a href="https://docs.apollo.io/reference/create-a-custom-field">Create
a Custom Field</a> endpoint to create a new field instead.
type:
type: string
description: <b>Read-only. This parameter cannot be updated.</b> A field's data
type is set when the field is created. You can send `type` only if it matches
the field's current type; sending a different type fails with `Cannot change
field type after creation`. <br><br>To store the data as a different type, use
the <a href="https://docs.apollo.io/reference/create-a-custom-field">Create
a Custom Field</a> endpoint to create a new field instead.
label:
type: string
description: 'A new name for the field, as it appears in Apollo. <br><br>Names
that start with `powerup_` are reserved by Apollo and cause the request to fail.
<br><br>Example: `Renewal owner`'
field_group_id:
type: string
description: 'The ID of the field group, or folder, that you want to move this
field into. <br><br>Example: `694095a80f1b6000110fc558`'
autorun_downstream_enrichment:
type: boolean
description: 'When `true`, enrichment for this field re-runs automatically whenever
the data it depends on changes. <br><br>Example: `true`'
schedule:
type: object
description: The schedule Apollo uses to automatically re-run this field's enrichment.
Only applies to enrichment columns that Apollo computes for you.
properties:
enabled:
type: boolean
description: Whether the schedule is active.
schedule_type:
type: string
description: How often the schedule runs, such as daily, weekly, or monthly.
schedule_timezone:
type: string
description: 'The timezone that Apollo evaluates the schedule in. <br><br>Example:
`America/Los_Angeles`'
run_limit:
type: number
description: The maximum number of records Apollo processes in a single scheduled
run.
max_executions:
type: number
description: The maximum number of times the schedule runs before it stops.
end_date:
type: string
format: date
description: 'The date when the schedule stops running. <br><br>Example: `2026-12-31`'
reset_execution_count:
type: boolean
description: Set to `true` to reset the number of executions Apollo has counted
against `max_executions`.
schedule_config:
type: object
description: The specific time the schedule runs. Which parameters apply depends
on `schedule_type`.
properties:
hour:
type: number
description: The hour of the day, from `0` to `23`.
minute:
type: number
description: The minute of the hour, from `0` to `59`.
day_of_week:
type: number
description: The day of the week, for weekly schedules.
day_of_month:
type: number
description: The day of the month, for monthly schedules.
interval:
type: number
description: How many units of `schedule_type` Apollo waits between runs.
meta:
type: object
description: Additional configuration for the field. Which parameters apply depends
on the field's `type`.
properties:
max_length:
type: number
description: 'The maximum number of characters the field accepts. Only applies
to `string` and `textarea` fields. <br><br>Example: `240`'
picklist_values:
type: array
description: The complete set of options for a `picklist` or `multipicklist`
field. <br><br><b>Required for every update to a picklist field, including
a change that only renames the field.</b> If you omit it, the request fails
with `Picklist fields must have at least one option`. <br><br>This parameter
replaces the field's options, so send every option you want to keep. Any
option you leave out is removed from the field. <br><br>To rename or remap
an existing option, include that option's existing `id`. An option sent
without its `id` is deleted and recreated, which orphans the values already
stored on your records.
items:
type: object
properties:
name:
type: string
description: 'The option as it appears in Apollo. <br><br>Example: `Tier
1`'
id:
type: string
description: 'The ID of an existing option, from the <a href="https://docs.apollo.io/reference/get-a-list-of-fields">Get
a List of Fields</a> endpoint. Include it to keep the option and rename
it, so that values already stored on your records are preserved. Omit
it to add a new option. <br><br>Example: `694095a80f1b6000110fc561`'
mapped_crm_id:
type: string
description: The ID of the matching picklist value in your CRM.
reassign_from:
type: array
description: The IDs of options that Apollo reassigns to this option.
Use this to merge options without losing the data on your records.
items:
type: string
picklist_value_set_id:
type: string
description: The ID of an existing picklist value set to attach to this field.
Only applies to `picklist` and `multipicklist` fields.
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
fields:
- id: contact.694095a80f1b6000110fc556
category: person
context:
- finder
- csv_export
description: null
editable: true
example: null
field_name: Renewal owner
group: null
icon_class: null
label: Renewal owner
modality: contact
parent: null
source: custom
type: string
finder_view_ids: []
project_workspace_id: null
context_card_ids: []
product_profile_ids: []
is_system_field: false
finder_views: []
is_local: false
created_at: '2025-12-15T23:11:36.084Z'
meta:
max_length: 240
computed_type: manual
visibility_status: active
typed_custom_fields:
- id: 694095a80f1b6000110fc556
name: Renewal owner
modality: contact
text_field_max_length: 240
schema:
type: object
properties:
fields:
type: array
description: The fields as they exist after the update. If updating a field caused
Apollo to remove a child field, that child appears here as an object with `id` and
`deleted` set to `true`.
items:
type: object
properties:
id:
type: string
label:
type: string
modality:
type: string
description: Entity type this field belongs to (contact, account, opportunity,
lead, custom_object)
type:
type: string
source:
type: string
description: Field source (system, custom, crm_synced)
meta:
type: object
additionalProperties: true
description: Extended configuration for the field
deleted:
type: boolean
description: Only present, and always `true`, when Apollo removed this field
as a result of the update.
created_at:
type: string
format: date-time
required:
- id
typed_custom_fields:
type: array
description: The underlying custom field records for the fields you updated. Only
present when the update touched at least 1 custom field.
items:
type: object
properties:
id:
type: string
name:
type: string
modality:
type: string
text_field_max_length:
type: number
field_groups:
type: array
description: The field groups associated with the fields you updated. Only present
when the fields belong to at least 1 field group.
items:
type: object
additionalProperties: true
picklist_value_sets:
type: array
description: The picklist value sets for the fields you updated. Only present when
the update touched a `picklist` or `multipicklist` field.
items:
type: object
additionalProperties: true
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-io/refs/heads/main/openapi/apollo-io-fields-api-openapi.yml