User-definable contact field schema — fields, choice option lists, field groups and tabs, plus primary-value marks on multi-valued fields. The field set differs per account and must be read before writing contact data. 15 operation(s).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nimble-contacts-fields-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Nimble Contacts Fields API
version: v1
description: '# Overview
Nimble is a relationship-focused CRM for your entire team.'
x-logo:
url: https://www.nimble.com/wp-content/themes/new_nimble/images/nimble-logo-white.svg
backgroundColor: '#2685c4'
servers:
- url: https://app.nimble.com
security:
- ApiKey: []
tags:
- name: Contacts Fields
description: '## Legacy contacts metadata
Contact\''s metadata contains information about all basic and custom
fields created in Nimble for a user.'
paths:
/api/v1/contacts/fields:
get:
description: Return all available metadata for company's fields
operationId: list-company-contacts-fields
summary: List all available metadata for company fields
tags:
- Contacts Fields
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactsFieldsMetadata'
description: fields metadata
post:
operationId: post-contact-field
summary: Create new field
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.CreateFieldRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/{field_id}:
parameters:
- in: path
name: field_id
required: true
schema:
type: string
delete:
description: Deletes field by id
operationId: delete-contact-field
summary: Delete contact field by id
tags:
- Contacts Fields
parameters:
- in: query
name: preflight_checks
required: true
schema:
type: boolean
responses:
'200':
description: Successful deleted
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: if preflight_checks is true and field is used in contacts
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
put:
description: Updates existing field
operationId: put-contact-field
summary: Update existing field by id
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
group_id:
description: If not null, move field to specified group. Null if remove field from grooup
type:
- string
- 'null'
insert_after:
description: If not null, move field after another field or group with specified id. If null, then moved field to be the first one
type:
- string
- 'null'
name:
maxLength: 50
minLength: 1
type: string
presentation:
$ref: '#/components/schemas/Fields.FieldPresentation'
tab_id:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: field updated
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/groups:
post:
description: Create new fields group
operationId: create-contacts-fields-group
summary: Create new contacts fields group
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
insert_after:
description: If not null, inserts a new group after another group or field with specified id. If null, then tab is inserted as the first one
type:
- string
- 'null'
logo_id:
type: string
name:
maxLength: 50
minLength: 1
type: string
tab_id:
type: string
required:
- name
- tab_id
- logo_id
- insert_after
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/groups/{group_id}:
parameters:
- in: path
name: group_id
required: true
schema:
type: string
delete:
description: Deletes group by id
operationId: delete-contacts-fields-group
summary: Delete contacts fields group by id
tags:
- Contacts Fields
parameters:
- in: query
name: preflight_checks
required: true
schema:
type: boolean
responses:
'200':
description: Successful deleted
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: ''
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: if preflight_checks is true and any field in group is used
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
put:
description: Updates existing fields group
operationId: put-contacts-fields-group
summary: Update contacts fields group by id
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
insert_after:
description: If not null, move group after another field or group with specified id. If null, then move group to the first position
type:
- string
- 'null'
logo_id:
type: string
name:
maxLength: 50
minLength: 1
type: string
tab_id:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: group updated
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: group not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/tabs:
post:
description: Create new fields tabs
operationId: post-contacts-fields-tab
summary: Create new contacts fields tab
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
contact_types:
items:
$ref: '#/components/schemas/Contacts.ContactType'
type: array
insert_after:
description: If not null, inserts a new tab after another tab with specified id. If null, then tab is inserted as the first one
type:
- string
- 'null'
tab_name:
maxLength: 50
minLength: 1
type: string
required:
- tab_name
- contact_types
- insert_after
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/tabs/{tab_id}:
parameters:
- in: path
name: tab_id
required: true
schema:
type: string
delete:
description: Deletes tab by id
operationId: delete-contacts-tab-by-id
summary: Delete contacts tab by id
tags:
- Contacts Fields
parameters:
- in: query
name: preflight_checks
required: true
schema:
type: boolean
responses:
'200':
description: Successful deleted
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: tab not found
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: if preflight_checks is true and at least one field in tab used in contacts
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
put:
description: Updates existing fields tab
operationId: put-contacts-tab-by-id
summary: Update contacts fields tab by id
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
contact_types:
$ref: '#/components/schemas/Contacts.ContactType'
insert_after:
description: Moves tab after another tab with specified id. If null, then move tab to the first position
type:
- string
- 'null'
tab_name:
maxLength: 50
minLength: 1
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: tab updated
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: tab not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/{field_id}/choices:
post:
operationId: post-contact-choice-field
summary: Create choice for field
parameters:
- in: path
name: field_id
schema:
type: string
required: true
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
id:
type: string
insert_after:
description: If not null, inserts a new choice after another choice with specified id. If null, then inserted choice to be the first one in field
type:
- string
- 'null'
value:
type: string
required:
- id
- value
- insert_after
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: choice created
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/{field_id}/choices/{id}:
parameters:
- in: path
name: id
required: true
schema:
type: string
delete:
description: Deletes choice by id
operationId: delete-contact-choice-field
summary: Delete contact choice by id
tags:
- Contacts Fields
parameters:
- in: query
name: preflight_checks
required: true
schema:
type: boolean
- in: path
name: field_id
schema:
type: string
required: true
- in: path
name: id
schema:
type: string
required: true
responses:
'200':
content:
application/json:
schema:
properties:
tabs:
items:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
type: array
description: Successful deleted
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: choice not found
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: if preflight_checks is true and choise is used in any contacts
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
put:
parameters:
- in: path
name: field_id
schema:
type: string
required: true
- in: path
name: id
schema:
type: string
required: true
description: Updates choise
operationId: put-contacts-field-choice
summary: Update field choice
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
id:
type: string
insert_after:
description: If not null, move choice after another choice with specified id. If null, then moved choice to be the first one
type:
- string
- 'null'
value:
type: string
required:
- id
responses:
'200':
content:
application/json:
schema:
properties:
tabs:
items:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
type: array
description: choice updated
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: choice or field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contact/{contact_id}/field:
delete:
parameters:
- in: path
name: contact_id
schema:
type: string
required: true
description: delete is_primary mark from field
operationId: delete-primary-mark-from-contact-field
summary: Delete is_primary mark from field
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.UpdateIsPrimaryRequest'
required: true
responses:
'200':
description: success
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
put:
description: mark field with is_primary flag
operationId: put-primary-mark-to-contact-field
summary: Mark field with is_primary flag
parameters:
- in: path
name: contact_id
schema:
type: string
required: true
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.UpdateIsPrimaryRequest'
required: true
responses:
'200':
description: success
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
components:
schemas:
Contacts.ContactType:
enum:
- person
- company
type: string
Fields.LongStringFieldValuesType:
type: object
properties:
field_kind:
enum:
- long_string
Errors.NotFoundError:
example:
object_id: 4f2acc3142a053dda595f00b
object_type: deal
properties:
object_id:
type: string
object_type:
type: string
required:
- object_type
- object_id
type: object
Errors.PreflightCheckError:
example:
message: Some contacts cannot be updated because of their privacy settings
nse_query:
and:
- is_editable:
is: false
- _id:
in:
- 5dfb9c3e84a6b90f0c01c23a
- 5dfb9c3e84a6b90f0c01c23b
total: 10
type: non_editable_contacts
properties:
message:
type: string
nse_query:
description: problem contacts selection query
type: object
total:
type: integer
type:
description: unique and stable identifier of error type
type: string
required:
- type
- message
- total
- nse_query
type: object
Fields.CreateFieldRequest:
type: object
properties:
field_type:
$ref: '#/components/schemas/Fields.FieldTypeOnFieldCreation'
group_id:
type:
- string
- 'null'
insert_after:
description: If not null, inserts a new field after another field or group with specified id. If null, then inserted field to be the first one
type:
- string
- 'null'
name:
maxLength: 50
minLength: 1
type: string
presentation:
$ref: '#/components/schemas/Fields.FieldPresentation'
tab_id:
type: string
multiples:
type: boolean
description: whether this field can hold multiple values (by default, false)
required:
- name
- tab_id
- group_id
- field_type
- presentation
- insert_after
Fields.DateTimePresentation:
type: object
properties:
date_format:
type:
- string
- 'null'
description: 'strftime-like format template as described in
https://docs.python.org/2.7/library/datetime.html#strftime-and-strptime-behavior
or null if client should use date format from user settings
'
ignore_specific_time:
type:
- boolean
- 'null'
description: 'show if time should be presented in the field. Applicable only if date_format is None.
Must be null if date_format specified
'
required:
- date_format
- ignore_specific_time
Errors.ValidationError:
description: request was malformed
example:
errors:
/:
message: 'missing required properties: ["calendar_id", "summary"]'
/base_occurrence/start_dtime:
message: Can't parse value 20000-01-01T01:01:00 as DATE-TIME
message: 'Invalid value {} (dict): missing required properties: []"calendar_id", "summary"]'
code: 245
human_readable_error: 'Invalid value {} (dict): missing required properties: []"calendar_id", "summary"]"'
extra:
- {}
properties:
errors:
description: 'mapping where keys are paths to problematic request attributes
and values are objects with single message attribute
'
type: object
message:
type: string
code:
type: integer
description: legacy that you <span style='color:red'>SHOULD NOT USE</span>
human_readable_error:
type: string
description: Error message with some changes making it easier to read.
extra:
type: array
items:
type: object
description: extra data that would be useful to provide
required:
- message
- errors
- human_readable_error
type: object
Fields.ContactFieldsTab:
properties:
tab_id:
type: string
tab_name:
type: string
contact_types:
$ref: '#/components/schemas/Contacts.ContactType'
is_standard:
type: boolean
members:
description: a member could be a group of fields or separate field
type: array
items:
oneOf:
- $ref: '#/components/schemas/Fields.ContactFieldsGroup'
- $ref: '#/components/schemas/Fields.ContactField'
available_actions:
description: 'edit_all - available all operations with tab
rearrange_only - available just moving tab between other tabs
view_only - tab can''t be changed
'
enum:
- edit_all
- rearrange_only
- view_only
Fields.DecimalNumberPresentation:
type: object
properties:
number_type:
enum:
- decimal
fraction_digits:
type: integer
minimum: 1
required:
- type
- fraction_digits
Fields.UpdateIsPrimaryRequest:
properties:
field_id:
type: string
position:
minimum: 0
type: integer
required:
- field_id
- position
- is_primary
type: object
Errors.PreflightCheckFailures:
description: action cannot be applied to all specified contacts
properties:
errors:
items:
$ref: '#/components/schemas/Errors.PreflightCheckError'
type: array
required:
- errors
type: object
Fields.IntegerNumberPresentation:
type: object
properties:
number_type:
enum:
- integer
required:
- type
Fields.FieldType:
oneOf:
- $ref: '#/components/schemas/Fields.StringFieldValuesType'
- $ref: '#/components/schemas/Fields.LongStringFieldValuesType'
- $ref: '#/components/schemas/Fields.ChoiceFieldValuesType'
- $ref: '#/components/schemas/Fields.NumberFieldValuesType'
- $ref: '#/components/schemas/Fields.DateTimeFieldValuesType'
- $ref: '#/components/schemas/Fields.BooleanFieldValuesType'
- $ref: '#/components/schemas/Fields.AddressFieldValuesType'
- $ref: '#/components/schemas/Fields.AttachmentFieldValuesType'
- $ref: '#/components/schemas/Fields.UserFieldValuesType'
- $ref: '#/components/schemas/Fields.EmploymentFieldValuesType'
Fields.ChoiceFieldValuesType:
type: object
properties:
field_kind:
enum:
- choice
values:
$ref: '#/components/schemas/Commons.PossibleValues'
Fields.StringFieldValuesType:
type: object
properties:
field_kind:
enum:
- string
validation_rule:
$ref: '#/components/schemas/Fields.TextValidationRule'
Fields.AddressFieldValuesType:
type: object
properties:
field_kind:
enum:
- address
Fields.EmploymentFieldValuesType:
type: object
properties:
field_kind:
enum:
- employment
Fields.FieldPresentation:
description: 'how values of the field should look. Must match to corresponding field_type. Date and number
fields must have an appropriate presentation. There is no presentation for other types
'
oneOf:
- $ref: '#/components/schemas/Fields.IntegerNumberPresentation'
- $ref: '#/components/schemas/Fields.DecimalNumberPresentation'
- $ref: '#/components/schemas/Fields.PercentageNumberPresentation'
- $ref: '#/components/schemas/Fields.FinancialNumberPresentation'
- $ref: '#/components/schemas/Fields.DateTimePresentation'
Fields.TextValidationRule:
type: object
properties:
type:
enum:
- email
- url
Fields.FinancialNumberPresentation:
type: object
properties:
number_type:
enum:
- financial
currency:
type:
- string
- 'null'
required:
- type
- currency
Fields.PercentageNumberPresentation:
type: object
properties:
number_type:
enum:
- percentage
fraction_digits:
type: integer
minimum: 1
required:
- type
- fraction_digits
Fields.ContactFieldsGroup:
type: object
properties:
type:
enum:
- group
type: string
name:
type: string
group_id:
type: string
logo_id:
type: string
fields:
type: array
items:
$ref: '#/components/schemas/Fields.ContactField'
Commons.PossibleValues:
type: object
properties:
ordering_type:
type: string
enum:
- ordinal
- alphabetic
values:
type: array
items:
type: object
properties:
id:
type: string
value:
type: string
Fields.ContactField:
type: object
properties:
type:
enum:
- field
type: string
name:
type: string
field_id:
type: string
modifier:
type: string
multiples:
type: boolean
read_only:
description: if contacts values of this field is editable. It is different from available_actions.read_only
type: boolean
field_type:
$ref: '#/components/schemas/Fields.FieldType'
presentation:
$ref: '#/components/schemas/Fields.FieldPresentation'
available_actions:
description: 'edit_all - all operations with field available
edit_choices_only - just choices of field available for changing
view_only - field can''t be changed
'
enum:
- edit_all
- edit_choices_only
- view_only
Fields.UserFieldValuesType:
type: object
properties:
field_kind:
enum:
- user
Fields.ContactsFieldsMetadata:
type: object
properties:
tabs:
items:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
type: array
required:
- tabs
description: Contain the structure of contacts tabs, groups, and fields.
Fields.FieldTypeOnFieldCreation:
oneOf:
- $ref: '#/components/schemas/Fields.StringFieldValuesType'
- $ref: '#/components/schemas/Fields.LongStringFieldValuesType'
- $ref: '#/components/schemas/Fields.ChoiceFieldValuesType'
- $ref: '#/components/schemas/Fields.NumberFieldValuesType'
- $ref: '#/components/schemas/Fields.DateTimeFieldValuesType'
- $ref: '#/components/schemas/Fields.BooleanFieldValuesType'
- $ref: '#/components/schemas/Fields.AddressFieldValuesType'
- $ref: '#/components/schemas/Fields.UserFieldValuesType'
Fields.DateTimeFieldValuesType:
type: object
properties:
field_kind:
enum:
- datetime
Fields.AttachmentFieldValuesType:
type: object
properties:
field_kind:
enum:
- attachment
Fields.BooleanFieldValuesType:
type: object
properties:
field_kind:
enum:
- boolean
Fields.NumberFieldValuesType:
type: object
properties:
field_kind:
enum:
- number
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-Nimble-Token
x-tagGroups:
- name: Guides
tags:
- Authentication
- Handling Errors
- name: API Reference
tags:
- Users
- Contacts
- Contacts Fields
- Contacts Pipelines
- Search Contacts
- Activities
- Tasks
- Deals
- Deals Fields
- Deals Pipelines
- Deals Pipelines Fields
- Messages