Nutshell Contacts (People) API

openapi: 3.0.0
info:
  title: Nutshell Contacts (People) API
  description: The most powerful API in the world
  version: 2.0.0
  contact:
    name: Nutshell Developers
    url: https://developers.nutshell.com
servers:
- url: https://app.nutshell.com/rest
  description: Nutshell REST API
tags:
- name: Contacts (People)
paths:
  /contacts/{id}:
    get:
      tags:
      - Contacts (People)
      summary: Get a contact
      description: Returns a single contact based on the provided ID.
      operationId: 8a291bf9a1a7e4a7fd1ca0cabfdaa8a7
      parameters:
      - name: id
        in: path
        description: Contact ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
      security:
      - basicAuth: []
    delete:
      tags:
      - Contacts (People)
      summary: Delete a contact
      description: Deletes a contact from Nutshell. Can be recovered by posting to /contacts/{id}/undelete
      operationId: 2b3d155b2889d34aa67235e67aa91d3f
      parameters:
      - name: id
        in: path
        description: Contact ID
        required: true
        schema:
          type: array
          items:
            type: string
      responses:
        '204':
          description: No Content
      security:
      - basicAuth: []
    patch:
      tags:
      - Contacts (People)
      summary: Update a contact
      description: 'Update a contact by id. <br><br> op is the operation to be performed, and path specifies
        what resource to patch. <br><br> Use the path contacts/0/fieldName to update fields that are user-entered
        for this resource, i.e. name, description, etc. <br> <br> Use the path contacts/0/links/fieldName
        to update this contact''s links to other resources within Nutshell, i.e. accounts, owner, territory,
        emAudiences, etc. When performing an ''add'', include a /- at the end of the path, i.e. contacts/0/links/fieldName/-
        .  <br><br> When using the remove operation, include the id at the end of the path (i.e. contacts/0/links/accounts/1-accounts)
        - no need to include a value. <br><br> Value can alternatively be a list of objects, which can
        be used with the replace operation and the path contacts/0/urls, contacts/0/addresses, contacts/0/phones,
        contacts/0/phones, contacts/0/links/emAudiences, or contacts/0/links/accounts to replace the existing
        list with a list of new objects. For certain replace operations like accounts and emAudiences,
        provide an array of strings as the value. <br><br> Visit <a href=''https://developers.nutshell.com/reference/get_contacts-id-3''>the
        contact docs</a> for more detail on the structure of these objects. '
      operationId: cb995ae09d7e0e99e91b122bcc9358ed
      parameters:
      - name: id
        in: path
        description: Ids are of the form 'n-contacts', where n is an integer.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/patchInput'
      responses:
        '204':
          description: No Content
      security:
      - basicAuth: []
  /contacts/{id}/customfields:
    get:
      tags:
      - Contacts (People)
      summary: Get contact custom fields
      description: Returns a list of custom fields for a contact.
      operationId: 66abde512928a58ff9e3d7fac51a236e
      parameters:
      - name: id
        in: path
        description: Contact ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Custom Fields
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomField'
      security:
      - basicAuth: []
  /contacts/customfields/attributes:
    get:
      tags:
      - Contacts (People)
      summary: Get applicable custom fields
      description: Get a list of all custom fields that can be applied to any contact.
      operationId: 6f66fdf709475681e4e16528980ec105
      responses:
        '200':
          description: Custom Fields
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomField'
      security:
      - basicAuth: []
  /contacts/customfield:
    post:
      tags:
      - Contacts (People)
      summary: Create a custom field
      description: Creates a custom field to use for contacts.
      operationId: e156619e0c6caae9203e0c505a33bcad
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldCreateInput'
      responses:
        '200':
          description: OK
      security:
      - basicAuth: []
  /contacts:
    get:
      tags:
      - Contacts (People)
      summary: Get a list of contacts
      description: Returns a number of contacts which is filterable based on their basic information.
      operationId: cde301caba6b033521a71e6bed772a58
      parameters:
      - name: email
        in: query
        description: Returns contacts with the provided email address.
        schema:
          type: string
      - name: q
        in: query
        description: Returns contacts with a piece of information similar to the provided string, such
          as name, email, location, etc.
        schema:
          type: string
      - name: sort
        in: query
        description: What criteria to order the returned list of results.
        schema:
          type: string
          enum:
          - accountType
          - -accountType
          - accounts
          - -accounts
          - createdTime
          - -createdTime
          - email
          - -email
          - industry
          - -industry
          - lastContactedTime
          - -lastContactedTime
          - name
          - -name
          - owner
          - -owner
          - phone
          - -phone
          - postalCode
          - -postalCode
          - territory
          - -territory
      - name: filter
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          description: Filter the returned contacts based on various criteria. Use /rest/contacts/list/fields
            to get a full list of valid filter keys.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FilterInput'
      - name: page[page]
        in: query
        description: The page of results to return. Indexing is 0-based.
        required: false
        schema:
          type: integer
      - name: page[limit]
        in: query
        description: How many results to return per page
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
      security:
      - basicAuth: []
    post:
      tags:
      - Contacts (People)
      summary: Create a contact
      description: Create a new contact, also known as a person, in Nutshell. Only one contact may be
        created at a time.
      operationId: 376a09558c05d3d4d273459f15a57326
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/contactPostInput'
      responses:
        '200':
          description: Contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
      security:
      - basicAuth: []
  /contacts/{id}/undelete:
    post:
      tags:
      - Contacts (People)
      summary: Undelete a contact
      operationId: c56447f926210f833c484e8ba7486e8c
      parameters:
      - name: id
        in: path
        description: Contact ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
      security:
      - basicAuth: []
  /contacts/list:
    get:
      tags:
      - Contacts (People)
      summary: Get list items for all contacts
      description: Get a list of all contacts and associated data in your Nutshell Instance, in a list
        item format. List items have additional fields attached to them for filtering purposes. Contacts
        are people that you do business with, and are referred to as 'People' in the Nutshell UI.
      operationId: 7416ffd79a200377cb6276e02b1f5ddb
      parameters:
      - name: filter
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          description: Filter the returned contacts based on various criteria. Use /rest/contacts/list/fields
            to get a full list of valid filter keys.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FilterInput'
      - name: q
        in: query
        description: Used to search all related info on an entity. Returns all entities that are similar
          to the query term.
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: Sort the returned list by a chosen field. Use a '-' before the field name to sort
          in descending order.
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - -accountType
            - -accounts
            - -createdTime
            - -industry
            - -lastContactedTime
            - -owner
            - -phone
            - -postalCode
            - -territory
            - accountType
            - accounts
            - createdTime
            - industry
            - lastContactedTime
            - owner
            - phone
            - postalCode
            - territory
      responses:
        '200':
          description: contacts list
          content:
            application/json:
              schema:
                properties:
                  meta:
                    allOf:
                    - properties:
                        count:
                          description: The number of returned contacts
                          type: integer
                          format: int32
                      type: object
                    - properties:
                        total:
                          description: The total number of contacts in your Nutshell instance
                          type: integer
                          format: int32
                      type: object
                    - $ref: '#/components/schemas/meta'
                  listItems:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/ListItemContact'
                      - $ref: '#/components/schemas/HtmlLinkable'
                      - $ref: '#/components/schemas/Avatarable'
                type: object
      security:
      - basicAuth: []
  /contacts/list/fields:
    get:
      tags:
      - Contacts (People)
      summary: Get the fields for a contact
      description: Get the list of fields that can possibly be associated with contacts, along with whether
        they are valid for filtering sorting.
      operationId: a2e78cb11ef577ef33e5c162da51ab51
      responses:
        '200':
          description: Contact fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldsResponse'
      security:
      - basicAuth: []
components:
  schemas:
    Avatarable:
      properties:
        avatarUrl:
          description: The URL of the entity's avatar image.
          type: string
          example: https://app.nutshell.com/avatars/contacts/1006/{path}
        initials:
          description: The initials of the entity, used as a fallback for the avatar image.
          type: string
          example: AF
      type: object
    Contact:
      type: object
      allOf:
      - $ref: '#/components/schemas/Peep'
      - $ref: '#/components/schemas/Avatarable'
      - $ref: '#/components/schemas/HtmlLinkable'
      - properties:
          jobTitle:
            description: The person's role at their company.
            example: CEO
          firstName:
            description: The person's given name.
            example: Andy
          lastName:
            description: The person's family name.
            example: Fowler
          href:
            description: The URL to fetch this contact.
            type: string
            example: https://app.nutshell.com/rest/contacts/3-contacts
        type: object
    ContactResponse:
      description: A full response object for a contact-related endpoint.
      properties:
        links:
          description: Where to get related entities.
          type: object
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/FullContact'
      type: object
    CustomField:
      properties:
        id:
          description: The API ID of this entity, formatted {integer}-{entityType}
          type: string
          example: 3-contacts
      type: object
    CustomFieldCreateInput:
      properties:
        name:
          description: The name of the custom fields
        type:
          description: Email, location, phone, and URL are only applicable to leads.
        choices:
          description: For enums only. The possible values for the custom field.
        isMultiple:
          description: For enums only. Whether the custom field can have multiple values
        id:
          description: The API ID of this entity, formatted {integer}-{entityType}
          type: string
          example: 3-contacts
        title:
          type: string
          example: Custom Field Title
      type: object
    CustomFieldInput:
      description: The key-value pair for the custom field.
      properties:
        id:
          description: The API ID of this entity, formatted {integer}-{entityType}
          type: string
          example: 3-contacts
      type: string
    FieldsResponse:
      description: Response object for entity fields endpoint
      properties:
        properties:
          properties:
            exampleProperty:
              properties:
                type:
                  description: The type of the property
                  type: string
                  example: string
                title:
                  description: The display title of the property
                  type: string
                  example: Example Property
                description:
                  description: The description of the property
                  type: string
                  example: This is an example property
                isFilterable:
                  description: Whether the property can be used in filters
                  type: boolean
                  example: true
                isDisplayable:
                  description: Whether the property can be displayed
                  type: boolean
                  example: true
                isSortable:
                  description: Whether the property can be used for sorting
                  type: boolean
                  example: true
                isGoalable:
                  description: Whether the property can be used as a condition in automation goals
                  type: boolean
                  example: false
                isAddable:
                  description: Whether the property can be set when creating or editing a lead
                  type: boolean
                  example: true
                isBoardable:
                  description: Whether the property can be displayed on lead cards/boards
                  type: boolean
                  example: true
                isRequireable:
                  description: Whether the property can be marked as required in forms
                  type: boolean
                  example: false
                isAndable:
                  description: Whether multiple filter values can be combined with AND/OR logic (allows
                    'any' vs 'all' selection)
                  type: boolean
                  example: false
                isNullable:
                  description: Whether the property can have a null/empty value
                  type: boolean
                  example: true
                relationships:
                  description: For relationship-type properties, array of related entity types (e.g.,
                    ['users', 'teams'])
                  type: array
                  items:
                    type: string
                  example:
                  - users
                  - teams
                enum:
                  description: For enum-type properties, array of possible values
                  type: array
                  items:
                    type: string
                  example:
                  - Option1
                  - Option2
                format:
                  description: Value format specification (e.g., 'uri', 'relative' for date-time)
                  type: string
                  example: uri
              type: object
          type: object
      type: object
    FilterInput:
      description: The key-value pair for the filter, ex. filter[tags]=1-tags
      type: string
    FullContact:
      description: An individual contact with all fields.
      allOf:
      - $ref: '#/components/schemas/Contact'
      - $ref: '#/components/schemas/HtmlLinkable'
      - $ref: '#/components/schemas/Avatarable'
      - properties:
          links:
            description: The entity IDs of related entities.
            type: object
        type: object
    HtmlLinkable:
      description: 'Adds an htmlUrl string attribute that represents a URL of an HTML representation of
        the

        response model.'
      properties:
        htmlUrl:
          description: The link to the entity within the app.
          type: string
          example: https://app.nutshell.com/lead/1006
        htmlUrlPath:
          description: The path to the entity within the app.
          type: string
          example: /lead/1006
      type: object
    ListItem:
      type: object
      allOf:
      - $ref: '#/components/schemas/HtmlLinkable'
      - $ref: '#/components/schemas/Avatarable'
      - properties:
          id:
            description: The API ID of this entity, formatted {integer}-{entityType}
            type: string
            example: 3-contacts
          primaryName:
            type: string
          primaryInfo:
            type: string
          relatedName:
            type: string
          relatedInfo:
            type: string
          relatedType:
            type: string
          relatedUrl:
            type: string
          relatedUrlPath:
            type: string
          primaryContact:
            type: string
          primaryAccount:
            type: string
          latlon:
            type: string
          mapUrl:
            type: string
          isDeleted:
            type: boolean
          fields:
            description: Various additional fields for the list item. View the example response for more
              details.
            type: array
            items:
              type: object
        type: object
    ListItemContact:
      type: object
      allOf:
      - $ref: '#/components/schemas/ListItem'
      - properties:
          description:
            type: string
        type: object
    Peep:
      properties:
        id:
          description: The API ID of this entity, formatted {integer}-{entityType}
          type: string
          example: 3-contacts
        name:
          description: The entity's full name.
          type: string
          example: Andy Nutshell
        description:
          description: A brief explanation of this entity which appears under their name.
          type: string
          example: CEO / cofounder @ Nutshell. Building growth software, wrangling beagles 🐶
        createdTime:
          description: Unix timestamp
          type: integer
          format: int64
        deletedTime:
          description: Unix timestamp
          type: integer
          format: int64
        emails:
          $ref: '#/components/schemas/emails'
        addresses:
          $ref: '#/components/schemas/addresses'
        phones:
          $ref: '#/components/schemas/phones'
        urls:
          $ref: '#/components/schemas/urls'
      type: object
    addresses:
      description: All addresses associated with an entity.
      type: array
      items:
        properties:
          isPrimary:
            description: Should this address be used if there are multiple
            type: boolean
            example: true
          name:
            description: A label for the address, e.g. 'work', 'home', 'shipping'.
            type: string
            example: address
          value:
            description: The geographic coordinates for the address.
            properties:
              location:
                properties:
                  longitude:
                    type: number
                    example: -83.732124
                  latitude:
                    type: number
                    example: 42.279594
                type: object
            type: object
          locationAccuracy:
            description: How specific the address is. 8 is an exact street address, 1 is only a country.
            type: string
            example: '8'
          address_1:
            description: Primary street address
            type: string
            example: 206 E Huron St
          address_2:
            description: Secondary street address, such as a suite or apartment number
            type: string
            example: Suite 200
          address_3:
            type: string
          city:
            description: City or town
            type: string
            example: Ann Arbor
          state:
            description: State or province
            type: string
            example: MI
          postalCode:
            description: ZIP or postal code
            type: string
            example: '48103'
          country:
            description: Country code
            type: string
            example: US
          timezone:
            type: string
        type: object
    contactPostInput:
      description: The fields to be updated
      properties:
        contacts:
          type: array
          items:
            properties:
              name:
                description: The new full name of the contact.
                type: string
              description:
                description: The new description of the contact, which appears under their name.
                type: string
              phones:
                $ref: '#/components/schemas/phones'
              emails:
                $ref: '#/components/schemas/emails'
              urls:
                $ref: '#/components/schemas/urls'
              addresses:
                $ref: '#/components/schemas/addresses'
              customFields:
                description: Custom fields to add to the Contact.
                type: object
                example:
                  Favorite Number: '12'
                additionalProperties:
                  $ref: '#/components/schemas/CustomFieldInput'
              links:
                description: Enter API IDs to link to the contact.
                properties:
                  accounts:
                    description: Enter an array of API IDs for each account to associate with the contact.
                      Including an empty array will clear all associated accounts.
                    type: array
                    items:
                      type: string
                  territory:
                    description: Enter an API ID for the territory to associate with the contact.
                    type: string
                  owner:
                    description: Enter an API ID for the owner to associate with the contact.
                    type: string
                  tags:
                    description: Enter an array of API IDs for each tag to associate with the contact.
                    type: array
                    items:
                      type: string
                  emAudiences:
                    description: Enter an array of API IDs ({id}-emAudiences) for each audience to associate
                      with the contact.
                    type: array
                    items:
                      type: string
                type: object
            type: object
      type: object
    emails:
      description: All email addresses associated with an entity.
      type: array
      items:
        properties:
          isPrimary:
            description: If entity has multiple email addresses, which should be used as the primary point
              of contact.
            type: boolean
            example: true
          name:
            description: A label for the email address, e.g. 'work', 'personal', 'support'.
            type: string
            example: personal
          value:
            description: The email address itself.
            type: string
            example: andy@nutshell.com
        type: object
    meta:
      description: Information about the Nutshell instance making the request
      properties:
        instanceId:
          description: The Nutshell instance ID
          type: string
          example: '12345'
        siteId:
          description: Site ID for WebFX customers
          type: string
      type: object
    patchInput:
      type: array
      items:
        properties:
          op:
            description: The operation to perform
            type: string
            enum:
            - add
            - remove
            - replace
            - move
            - copy
            example: add
          path:
            description: The path to the attribute to patch. Can be used to update custom fields as well,
              such as using /leads/0/{customFieldName}
            type: string
            example: /leads/0/links/accounts/337-accounts
          value:
            description: The value to set, can be various types, please refer to our guide on JSON Patch
              for more information
            type: string
            example: 337-accounts
        type: object
    phones:
      type: array
      items:
        properties:
          isOptedOut:
            description: If this number has opted out of receiving SMS messages
            type: boolean
            example: true
          isPrimary:
            description: Should this phone number be used if there are multiple
            type: boolean
            example: true
          name:
            description: A label for the phone number, e.g. 'work', 'home', 'mobile'.
            type: string
            example: phone
          value:
            properties:
              countryCode:
                description: Phone number prefix for calling individuals in other countries
                type: string
                example: '1'
              number:
                description: The unformatted phone number with only digits
                type: string
                example: '7341234567'
              extension:
                description: An additional code to reach a specific person or department which share a
                  number
                type: string
                example: '123'
              numberFormatted:
                description: The phone number formatted for human readability
                type: string
                example: 734-123-4567
              E164:
                description: The phone number formatted for international use; a common programatic standard
                  for working with phone numbers
                type: string
                example: '+17341234567'
              countryCodeAndNumber:
                description: The phone number formatted for human readability with the country code
                type: string
                example: +1 734-123-4567
            type: object
        type: object
    urls:
      type: array
      items:
        properties:
          isPrimary:
            description: Should this URL be used if there are multiple
            type: boolean
            example: true
          name:
            description: A label for the URL, e.g. 'LinkedIn', 'Facebook', 'personal website'.
            type: string
            example: LinkedIn
          value:
            description: The URL itself
            type: string
            example: https://www.linkedin.com
        type: object
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic