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).
openapi: 3.0.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
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
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nimble/refs/heads/main/openapi/nimble-contacts-fields-api-openapi.yml