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
description: Nimble CRM Contacts Fields operations. Split by tag from the OpenAPI Nimble publishes at https://www.nimble.com/developers/docs/ (embedded Redoc spec). Base host https://app.nimble.com.
version: v1
servers:
- url: https://app.nimble.com
security:
- ApiKey: []
tags:
- name: Contacts Fields
description: "## Legacy contacts metadata\n\nContact\\'s metadata contains information about all basic and custom\nfields created in Nimble for a user. Below is it\\'s typical structure.\nPlease note that this listing doesn\\'t contain all metadata as the full\nlist is very big. The typical records are shown here. All default\ncontact fields are [described here](#tag/Contacts-Fields/Nimble-Default-Fields)\n\n``` javascript\n\"contacts_meta\": {\n \"fields\": {\n \"first name\": [\n {\n \"group\": \"Basic Info\",\n \"name\": \"first name\",\n \"label\": \"first name\",\n \"modifier\": \"\",\n \"presentation\": {},\n \"id\": \"5049f697a694620a07000043\",\n \"multiples\": false,\n \"read_only\": false\n }\n ],\n \"email\": [\n {\n \"group\": \"Contact Info\",\n \"name\": \"email\",\n \"label\": \"email\",\n \"modifier\": \"other\",\n \"presentation\": {},\n \"id\": \"5049f697a694620a07000065\",\n \"multiples\": true,\n \"read_only\": false\n },\n {\n \"group\": \"Contact Info\",\n \"name\": \"email\",\n \"label\": \"email\",\n \"modifier\": \"personal\",\n \"presentation\": {},\n \"id\": \"5049f697a694620a07000064\",\n \"multiples\": true,\n \"read_only\": false\n }\n ],\n \"lead status\": [\n {\n \"group\": \"Lead Details\",\n \"name\": \"lead status\",\n \"label\": \"lead status\",\n \"modifier\": \"\",\n \"presentation\": {\n \"width\": \"1\",\n \"next_id\": \"5\",\n \"values\": [\n {\n \"id\": \"1\",\n \"value\": \"Open\"\n },\n {\n \"id\": \"2\",\n \"value\": \"Contacted\"\n },\n {\n \"id\": \"3\",\n \"value\": \"Qualified\"\n },\n {\n \"id\": \"4\",\n \"value\": \"Unqualified\"\n }\n ],\n \"type\": \"select-box\"\n },\n \"id\": \"5049f697a694620a0700008d\",\n \"multiples\": false,\n \"read_only\": false\n }\n ]\n },\n \"groups\": {\n \"Basic Info\": {\n \"name\": \"Basic Info\",\n \"order\": [\n \"first name\",\n \"last name\",\n \"middle name\",\n \"company name\",\n \"title\",\n \"source\",\n \"last contacted\"\n ],\n \"is_standard\": true,\n \"label\": \"Basic Info\",\n \"type\": \"both\",\n \"id\": \"5049f696a694620a07000031\"\n }\n }\n}\n```\n\nHere is a description of the response in detail:\n\n**fields**\n\n: Information about the fields in Nimble. Represented by dictionary\n where keys are fields names, and values are lists containing details\n about all possible modifications of this field. If field have no\n modifiers (like `first name` on example above), this list contains\n only one element.\n\n Information stored in dictionaries with following keys:\n\n : - *group* --- unique name of the group containing this field.\n - *label* --- unique name representing the field in\n human-readable form.\n - *modifier* --- name of the field\\'s modifier\n - *id* --- unique id of the field in BSON format\n - *multiples* - indicates whether field could have multiple\n values (under different modifiers).\n - *presentation* - dict with the information which should help\n to display this field on client.\n - *read_only* - if contacts field values is editable by user\n\n**groups**\n\n: \n\n Information about field groups. Represented by dictionary where keys are unique group names and values are dictionaries with more info. Groups info dictionary contains following fields:\n\n : - *id* --- unique id of the group in BSON format.\n - *order* --- list containing names of the fields as they\n appeared in group.\n - *name* --- unique name of the group. (Outdated: as we have\n field name as the key of `groups` dictionary.)\n - *label* --- unique name representing the field in\n human-readable form.\n - *is_standard* - whether this group belongs to standard\n Nimble groups.\n - *type* - type (belonging) of group, could be among `person`,\n `company`, `both`.\n\n\n## Fields metadata\n\nContact\\'s metadata contains information about all basic and custom\nfields created in Nimble for a user. Below is it\\'s typical structure.\nAll default contact fields are [described here](#tag/Contacts-Fields/Nimble-Default-Fields)\n\n``` javascript\n{\n \"tabs\": [\n {\n \"tab_id\": \"string\",\n \"tab_name\": \"string\",\n \"contact_types\": \"person\",\n \"is_standard\": true,\n \"members\": [\n {\n \"type\": \"group\",\n \"name\": \"string\",\n \"group_id\": \"string\",\n \"logo_id\": \"string\",\n \"fields\": [\n {\n \"type\": \"field\",\n \"name\": \"string\",\n \"field_id\": \"string\",\n \"modifier\": \"string\",\n \"multiples\": true,\n \"read_only\": true,\n \"field_type\": {\n \"field_kind\": \"string\",\n \"validation_rule\": {\n \"type\": \"email\"\n }\n },\n \"presentation\": {\n \"number_type\": \"integer\"\n },\n \"available_actions\": \"edit_all\"\n }\n ]\n }\n ],\n \"available_actions\": \"edit_all\"\n }\n ]\n}\n```\n\nHere is a description of the response in detail:\n\n\n### Tabs\n\n- **tab_id** — unique ID of the tab.\n- **tab_name** — name representing the tab in human-readable form.\n- **contact_types** — contact types that could have fields in the tab. Possible values: `person`, `company`.\n- **is_standard** — whether this tab belongs to standard Nimble tabs.\n- **available_actions** — possible actions: `edit_all`, `rearrange_only`, `view_only`.\n- **members** — list of tab members. This could include groups and fields without groups.\n\n### Groups\n\n- **type** — tab member type. It is always \"group\" here.\n- **name** — name representing the group in human-readable form.\n- **group_id** — unique ID of the group.\n- **logo_id** — ID of the logo to display.\n- **is_standard** — whether this group belongs to standard Nimble groups.\n- **fields** — list of fields contained within the group.\n\n### Fields\n\n- **type** — tab member type. It is always \"field\" here.\n- **name** — name representing the field in human-readable form.\n- **field_id** — unique ID of the field.\n- **modifier** — name of the field's modifier.\n- **multiples** — indicates whether the field can have multiple values (under different modifiers).\n- **read_only** — whether the field is available for editing.\n- **field_type** — dictionary describing the field type. More details are [described here](#tag/Contacts-Fields/Nimble-Default-Fields/Nimble-Fields-Type).\n- **presentation** — dictionary describing how the field should be presented in the Nimble client. More details are [described here](#tag/Contacts-Fields/Nimble-Default-Fields/Nimble-Fields-Presentation).\n- **available_actions** — possible actions: `edit_all`, `edit_choices_only`, `view_only`.\n\n---\n\nThe image below shows schema of fields metadata. Blue rectangle - tab,\ngreen rectangle - group, red rectangle - field. As you can see, fields\ncould be a member of a tab or a group. The same metadata schema is used for deals metadata.\n\n\n\n---\n\n# Nimble Default Fields\n\n\n| Field Name | Type | Multiple Field | Modifiers | Notes |\n|--------------------|---------|------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| first name | string | - | N/A | |\n| last name | string | - | N/A | |\n| company name | string | - | N/A | |\n| contact employment | string | + | N/A | All values are represented as a JSON-encoded strings of dictionaries with the following keys: `company_name`, `title`, `start_date`, `end_date`. Where `start_date` and `end_date` are dates indicating the period of employment. These fields are optional; however, at least one of `company_name` or `title` must have a non-null value. This dictionary should be converted to a JSON string, and this string should be used as the field's value. |\n| birthday | string | - | N/A | Format: MM/DD/YYYY or MM/DD |\n| domain | string | - | N/A | The domain field. Example: `nimble.com`. This field satisfies the following conditions:<br>- **Unique** within the team. Only one company record with a particular value is allowed in the whole account.<br>- **Properly formatted**. No protocol or path is allowed; it can have up to a 3rd-level domain.<br>- It can be assigned to **company records only**. |\n| phone | string | + | work, home, mobile, main, home fax, work fax, other | |\n| email | string | + | work, personal, other | |\n| skype id | string | + | N/A | |\n| twitter | string | + | N/A | |\n| facebook | string | + | N/A | |\n| linkedin | string | + | N/A | |\n| google plus | string | + | N/A | |\n| muck rack | string | + | N/A | |\n| threads | string | + | N/A | |\n| instagram | string | + | N/A | |\n| tiktok | string | + | N/A | |\n| youtube | string | + | N/A | |\n| foursquare | string | + | N/A | |\n| URL | string | + | work, personal, blog, other | |\n| address | address | + | work, home, other | |\n| description | string | + | other, twitter, facebook, linkedin, google+, foursquare | |\n| hubspot | string | - | N/A | |\n| annual revenue | string | - | N/A | |\n| # of employees | choice | - | N/A | |\n| rating | choice | - | N/A | |\n| lead status | choice | - | N/A | |\n| lead source | choice | - | N/A | |\n| lead type | choice | - | N/A | |\n\n## Deprecated Fields\n\nThe fields `parent company` and `title` have been deprecated and replaced by the `contact employment` field, which accepts a **JSON-encoded string** to store employment details.\n\nThe `contact employment` field includes the following subfields:\n\n- **company_name** (string): Name of the company.\n- **title** (string): Job title.\n- **start_date** (datetime, optional): Employment start date in MM/YYYY format\n- **end_date** (datetime, optional): Employment end date in MM/YYYY format (must be null or omitted if the employment is ongoing).\n- **is_present** (boolean, optional): Indicates if the contact is currently employed at this company.\n\n### Validation Rules\n\n- **Company Name or Title Required**: At least one of `company_name` or `title` must be provided.\n\n- **Mutual Exclusivity of `end_date` and `is_present`**: If `end_date` is provided, `is_present` cannot be `true`.\n\n- **Date Order**: If both `start_date` and `end_date` are provided, `start_date` must be earlier than `end_date`.\n\n### Examples\n\n\n#### Original value (before encoding)\n\n```javascript\n{\n \"company_name\": \"Example Corp\",\n \"title\": \"Senior Developer\",\n \"start_date\": \"05/2024\"\n}\n```\n\n#### JSON-encoded value\n\nBefore sending the value to the API, it must be encoded as a JSON string:\n\n```javascript\n\"{\\\"company_name\\\":\\\"Example Corp\\\",\\\"title\\\":\\\"Senior Developer\\\",\\\"start_date\\\":\\\"05/2024\\\"}\"\n```\n\n#### Example request body — full contact employment\n\n```javascript\n{\n \"fields\": {\n \"contact employment\": [\n {\n \"value\": \"{\\\"company_name\\\":\\\"Example Corp\\\",\\\"title\\\":\\\"Senior Developer\\\",\\\"start_date\\\":\\\"05/2024\\\"}\"\n }\n ]\n }\n}\n```\n\n#### Example request body — company name only\n\nIf you only need to link a person with a company without additional details:\n\n```javascript\n{\n \"fields\": {\n \"contact employment\": [\n {\n \"value\": \"{\\\"company_name\\\":\\\"Example Corp\\\"}\"\n }\n ]\n }\n}\n```\n\n#### Example request body — current and previous companies\n\nIf you want to add multiple contact employment values:\n\n```javascript\n{\n \"fields\": {\n \"contact employment\": [\n {\n \"value\": \"{\\\"company_name\\\":\\\"Old Corp\\\",\\\"title\\\":\\\"Developer\\\",\\\"start_date\\\":\\\"01/2021\\\",\\\"end_date\\\":\\\"04/2024\\\"}\"\n },\n {\n \"value\": \"{\\\"company_name\\\":\\\"Example Corp\\\",\\\"title\\\":\\\"Senior Developer\\\",\\\"start_date\\\":\\\"05/2024\\\", \\\"is_present\\\": true}\",\n \"is_primary\": true\n }\n ]\n }\n}\n```\n\n\n\n## Nimble Default Field Tabs\n\n| Tab Name | Description | Fields |\n|------------------------|----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Personal Info | Personal contact's details | - first name,<br>- last name,<br>- middle name,<br>- title,<br>- parent company,<br>- birthday<br>- employment |\n| Company Info | Extended information about contact's company | - annual revenue,<br>- company name,<br>- domain,<br>- # of employees |\n| Contact Info | How to reach this contact | - phone,<br>- email,<br>- skype id,<br>- twitter,<br>- facebook,<br>- linkedin,<br>- google+,<br>- foursquare,<br>- address,<br>- description,<br>- URL,<br>- hubspot |\n| Lead Details | Information about contact as lead | - rating,<br>- lead stage |\n| Additional Lead Fields | Legacy fields | - lead status,<br>- lead source,<br>- lead type |\n| Extra Info | Contact's extended information | * Files |\n\n\n## Nimble Fields Type\n\nShow data about field type. You can't change it after creation. It is a dictionary with at least one field - `field_kind`.\n\n- **field_kind** --- represents the type of field in Nimble. It can have one of the following values:\n\n > - **string** --- simple field with one line of text\n > - **long_string** --- field containing multiline text\n > - **choice** --- drop-down list with predefined values, requires additional parameter `values`. Value of the field contains the id of one of the choice values\n > - **number** --- field with integer or decimal number\n > - **datetime** --- string formatted in ISO 8601\n > - **boolean** --- field with true/false value\n > - **address** --- field with address, that allows input of address in Nimble default format\n > - **user** --- field containing id of the Nimble user\n\nExamples:\n\n``` javascript\n\"field_type\": {\n \"field_kind\": \"string\"\n}\n```\n\n``` javascript\n\"field_type\": {\n \"field_kind\": \"choice\",\n \"values\": {\n \"ordering_type\": \"ordinal\",\n \"values\": [{\"id\": \"string\", \"value\": \"string\"}]\n }\n}\n```\n\n### Choice Type\n\nFields, showing as drop-down lists in Nimble. In metadata they have\n`field_type` equal `choice`. Also, their metadata contains field\n`values`, representing drop-down content. This field contains list of\ndictionaries, having two keys:\n\n**id**\n\n: Value, to be stored in field\n\n**value**\n\n: String, corresponding to this value\n\nExample:\n\n``` javascript\n{\n\"read_only\": false,\n\"field_type\": {\n\"values\": {\n \"ordering_type\": \"ordinal\",\n \"values\": [\n {\n \"id\": \"1\",\n \"value\": \"Analyst\"\n },\n {\n \"id\": \"2\",\n \"v
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nimble/refs/heads/main/openapi/nimble-contacts-fields-api-openapi.yml