API Reference / Contacts

POST /contacts

Create a contact

Creates a contact. Provide last_name or company_name — one of the two is required. owner_id defaults to the calling user and status_id to lead. company_name links the contact to an existing company (matched case-insensitively) or creates one; company_id is ignored on create. Optional next_action_name (max 140 characters) creates the contact's first next action, with next_action_date set to asap, waiting or a YYYY-MM-DD date.

Request body

  • titlestring

    The title of the contact

    enum: Mr · Mrs · Ms

  • first_namestring

    First name of the contact

  • last_namestring

    Last name of the contact

  • job_titlestring

    Job title of the contact

  • starredboolean

    Is the contact starred?

  • company_idstringbson-id

    ID of the company, to which the contact belongs

  • company_namestring

    Name of the company, to whom the contact belongs

  • urlsarray<object>

    URLs associated with the contact

    array item fields →
    • typestring

      The type of URL

      enum: website · blog · twitter · linkedin · xing · facebook · google_plus · other

    • valuestring

      The URL associated with the contact

  • phonesarray<object>

    Phone numbers associated with the contact

    array item fields →
    • typestring

      The type of phone number

      enum: work · mobile · home · direct · fax · company · other

    • valuestring

      The phone number associated with the contact

  • emailsarray<object>

    Email addresses associated with the contact

    array item fields →
    • typestring

      The type of email address

      enum: work · home · other

    • valuestring

      The email address associated with the contact

  • address_listarray<object>

    An array of contact addresses.

    array item fields →
    • addressstring

      Street address.

    • citystring

      City.

    • statestring

      State, province or region.

    • zip_codestring

      Postal or ZIP code.

    • country_codestring

      ISO 3166 country code, upper-case.

    • typestring

      Type of the address

      enum: work · home · billing · delivery · other

  • status_idstringbson-id

    ID of the status of the contact

  • tagsarray<string>

    Tags on the contact — free-form strings from the account's tag list.

  • lead_source_idstring

    ID of the lead source

  • backgroundstring

    Background infomation about the contact

  • owner_idstringbson-id

    ID of the user, to whom the contact belongs. Defaults to the logged API user's ID.

  • custom_fieldsarray<object>

    Extra user-configurable data fields for Contacts. Only editable by admins.

    array item fields →
    • custom_fieldobject
      object fields →
      • idstringbson-id

        ID of the custom field

    • valuestring

      Value for the custom field

Responses

201 Created
  • statusintegerint32

    Response code

  • messagestring

    Response message

  • timestampintegerunix-timestamp

    Response time

  • dataobject
    object fields →
    • contactobject

      Information about the people you are actively trying to sell to, and related sub-resources like Actions, Deals, Notes, Calls and Meetings.

      object fields →
      • idstringbson-id

        ID of the contact

      • titlestring

        The title of the contact

        enum: Mr · Mrs · Ms

      • first_namestring

        First name of the contact

      • last_namestring

        Last name of the contact

      • job_titlestring

        Job title of the contact

      • starredboolean

        Is the contact starred?

      • photo_urlstring

        URL of the contact's photo

      • company_idstringbson-id

        ID of the company, to which the contact belongs

      • company_namestring

        Name of the company, to whom the contact belongs

      • urlsarray<object>

        URLs associated with the contact

        array item fields →
        • typestring

          The type of URL

          enum: website · blog · twitter · linkedin · xing · facebook · google_plus · other

        • valuestring

          The URL associated with the contact

      • phonesarray<object>

        Phone numbers associated with the contact

        array item fields →
        • typestring

          The type of phone number

          enum: work · mobile · home · direct · fax · company · other

        • valuestring

          The phone number associated with the contact

      • emailsarray<object>

        Email addresses associated with the contact

        array item fields →
        • typestring

          The type of email address

          enum: work · home · other

        • valuestring

          The email address associated with the contact

      • address_listarray<object>

        An array of contact addresses.

        array item fields →
        • addressstring

          Street address.

        • citystring

          City.

        • statestring

          State, province or region.

        • zip_codestring

          Postal or ZIP code.

        • country_codestring

          ISO 3166 country code, upper-case.

        • typestring

          Type of the address

          enum: work · home · billing · delivery · other

      • statusstring

        Status of the contact

      • status_idstringbson-id

        ID of the status of the contact

      • tagsarray<string>

        Tags on the contact — free-form strings from the account's tag list.

      • lead_source_idstring

        ID of the lead source of the contact

      • lead_sourcestring

        Display name of the lead source of the contact

      • backgroundstring

        Background infomation about the contact

      • owner_idstringbson-id

        ID of the user, to whom the contact belongs. Defaults to the logged API user's ID.

      • custom_fieldsarray<object>

        Custom field values on the contact, as custom field and value pairs.

        array item fields →
        • custom_fieldobject

          Extra user-configurable data fields for Contacts. Only editable by admins.

          object fields →
          • idstringbson-id

            ID of the custom field

          • namestringrequired

            Name of the custom field

          • typestringrequired

            Type of the custom field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a contact doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).

            enum: anniversary · date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider

          • positionintegerint32

            The position of the custom field in the list

          • choicesarray<string>

            A list of possible choices (for fields of type `multiple_choice` or `select_box`)

        • valuestring

          Value for the custom field

      • letterstring

        The first letter of the contacts last name

      • pending_dealboolean

        Does the contact have one or more pending deals?

      • total_pendingsnumber

        The total value of all pending deals for the contact

      • total_deals_countintegerint32

        Number of deals associated with the contact

      • company_sizeintegerint32

        Number of contacts within the contact's company

      • sales_closed_forarray<string>

        A list of user IDs, for whom the sales cycle is closed

      • closed_salesarray<object>

        A list of closed sales objects

        array item fields →
        • user_idstringbson-id

          ID of the user, for whom the sales cycle is closed

        • closed_atintegerunix-timestamp

          Time that the sales cycle was closed

        • commentstring

          An optional message detailing why the sales cycle was closed

      • google_contacts_dataobject

        The google contacts data associated with this contact

        object fields →
        • account_emailstring

          Google contacts email

        • idstring

          Google contact id

        • saved_atintegerunix-timestamp

          Time the contact was saved to google

      • created_atstringdate-time

        Creation time of the contact

      • modified_atstringdate-time

        Last modification time of the contact

    • next_actionsarray<object>
      array item fields →
      • idstringbson-id

        ID of the action

      • assignee_idstringbson-idrequired

        ID of the user, to whom the action is assigned. Defaults to the logged API user's ID.

      • contact_idstringbson-idrequired

        ID of the contact, with whom the action is associated

      • textstringrequired

        The main text/description of the action

      • statusstring

        Status of the action

        enum: asap · date · date_time · waiting · queued · queued_with_date · done

      • datestringdate

        Due date for the action (status must be one of `date`, `date_time` or `queued_with_date`). Defaults to today's date.

      • exact_timeintegerunix-timestamp

        The UNIX Epoch time in seconds the action is due (status must be `date_time`)

      • positionintegerint32

        The position of the action (in the list of queued actions)

      • doneboolean

        Has the action been marked as complete?

      • done_atstringdate

        The date the action was completed (only returned, if action complete)

      • created_atstringdate-time

        Creation time of the action

      • modified_atstringdate-time

        Last modification time of the action

    • next_actionobject

      Completable tasks related to Contacts. ASAP first, then dated actions ordered by due date (overdue first), followed by waiting for (blocked) and finally queued actions (without any date).

      object fields →
      • idstringbson-id

        ID of the action

      • assignee_idstringbson-idrequired

        ID of the user, to whom the action is assigned. Defaults to the logged API user's ID.

      • contact_idstringbson-idrequired

        ID of the contact, with whom the action is associated

      • textstringrequired

        The main text/description of the action

      • statusstring

        Status of the action

        enum: asap · date · date_time · waiting · queued · queued_with_date · done

      • datestringdate

        Due date for the action (status must be one of `date`, `date_time` or `queued_with_date`). Defaults to today's date.

      • exact_timeintegerunix-timestamp

        The UNIX Epoch time in seconds the action is due (status must be `date_time`)

      • positionintegerint32

        The position of the action (in the list of queued actions)

      • doneboolean

        Has the action been marked as complete?

      • done_atstringdate

        The date the action was completed (only returned, if action complete)

      • created_atstringdate-time

        Creation time of the action

      • modified_atstringdate-time

        Last modification time of the action

    • queued_actionsarray<object>
      array item fields →
      • idstringbson-id

        ID of the action

      • assignee_idstringbson-idrequired

        ID of the user, to whom the action is assigned. Defaults to the logged API user's ID.

      • contact_idstringbson-idrequired

        ID of the contact, with whom the action is associated

      • textstringrequired

        The main text/description of the action

      • statusstring

        Status of the action

        enum: asap · date · date_time · waiting · queued · queued_with_date · done

      • datestringdate

        Due date for the action (status must be one of `date`, `date_time` or `queued_with_date`). Defaults to today's date.

      • exact_timeintegerunix-timestamp

        The UNIX Epoch time in seconds the action is due (status must be `date_time`)

      • positionintegerint32

        The position of the action (in the list of queued actions)

      • doneboolean

        Has the action been marked as complete?

      • done_atstringdate

        The date the action was completed (only returned, if action complete)

      • created_atstringdate-time

        Creation time of the action

      • modified_atstringdate-time

        Last modification time of the action

    • next_action_conflictsarray<any>
    • companyobject

      Referred to as 'organizations' in the web application. Companies are logical collections of Contacts and related sub-resources e.g. Deals, Actions and some basic info on the org. e.g. postal address, website. A Company may not be created directly or exist without a Contact.

      object fields →
      • idstringbson-id

        ID of the company

      • imagestring

        Base64 encoded binary image

      • namestringrequired

        Name of the company

      • descriptionstring

        Description of the company

      • phonestring

        Phone number of the company

      • photo_urlstring

        URL to company logo

      • urlstring

        URL of the company

      • addressobject

        The company's postal address.

        object fields →
        • addressstring

          Property name/number and street name

        • citystring

          Name of the city

        • statestring

          Name of the state

        • zip_codestring

          Zip code

        • country_codestring

          ISO-3166 country code

      • company_fieldsarray<object>

        Custom field values on the company.

        array item fields →
        • company_fieldobject

          Extra user-configurable data fields for Companies. Only editable by admins.

          object fields →
          • idstringbson-id

            ID of the company field

          • namestringrequired

            Name of the company field

          • typestringrequired

            Type of the company field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a company doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).

            enum: date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider

          • positionintegerint32

            The position of the company field in the list

          • choicesarray<string>

            A list of possible choices (for fields of type `multiple_choice` or `select_box`)

        • valuestring

          Value for the company field

      • syncing_statusboolean

        Should all contacts in this company share the same status?

      • synced_status_idstringbson-id

        ID of the status, that all contacts within this company are synced to

      • syncing_tagsboolean

        Should all contacts in this company share the same tags?

      • synced_tagsarray<string>

        Tags that all contacts within this company share

      • contacts_countintegerint32

        Number of contacts in this company

      • won_deals_countintegerint32

        Number of deals closed with contacts in this company

      • total_won_amountnumber

        The total value of the won deals with contacts in this company

      • pending_deals_countintegerint32

        Number of the pending deals with contacts in this company

      • total_pending_amountnumber

        The total value of the pending deals with contacts in this company

      • contactsarray<object>

        List of contacts in the comapny

        array item fields →
        • contactobject

          Information about the people you are actively trying to sell to, and related sub-resources like Actions, Deals, Notes, Calls and Meetings.

          object fields →
          • idstringbson-id

            ID of the contact

          • titlestring

            The title of the contact

            enum: Mr · Mrs · Ms

          • first_namestring

            First name of the contact

          • last_namestring

            Last name of the contact

          • job_titlestring

            Job title of the contact

          • starredboolean

            Is the contact starred?

          • photo_urlstring

            URL of the contact's photo

          • company_idstringbson-id

            ID of the company, to which the contact belongs

          • company_namestring

            Name of the company, to whom the contact belongs

          • urlsarray<object>

            URLs associated with the contact

            array item fields →
            • typestring

              The type of URL

              enum: website · blog · twitter · linkedin · xing · facebook · google_plus · other

            • valuestring

              The URL associated with the contact

          • phonesarray<object>

            Phone numbers associated with the contact

            array item fields →
            • typestring

              The type of phone number

              enum: work · mobile · home · direct · fax · company · other

            • valuestring

              The phone number associated with the contact

          • emailsarray<object>

            Email addresses associated with the contact

            array item fields →
            • typestring

              The type of email address

              enum: work · home · other

            • valuestring

              The email address associated with the contact

          • address_listarray<object>

            An array of contact addresses.

            array item fields →
            • addressstring

              Street address.

            • citystring

              City.

            • statestring

              State, province or region.

            • zip_codestring

              Postal or ZIP code.

            • country_codestring

              ISO 3166 country code, upper-case.

            • typestring

              Type of the address

              enum: work · home · billing · delivery · other

          • statusstring

            Status of the contact

          • status_idstringbson-id

            ID of the status of the contact

          • tagsarray<string>

            Tags on the contact — free-form strings from the account's tag list.

          • lead_source_idstring

            ID of the lead source of the contact

          • lead_sourcestring

            Display name of the lead source of the contact

          • backgroundstring

            Background infomation about the contact

          • owner_idstringbson-id

            ID of the user, to whom the contact belongs. Defaults to the logged API user's ID.

          • custom_fieldsarray<object>

            Custom field values on the contact, as custom field and value pairs.

            array item fields →
            • custom_fieldobject

              Extra user-configurable data fields for Contacts. Only editable by admins.

              object fields →
              • idstringbson-id

                ID of the custom field

              • namestringrequired

                Name of the custom field

              • typestringrequired

                Type of the custom field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a contact doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).

                enum: anniversary · date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider

              • positionintegerint32

                The position of the custom field in the list

              • choicesarray<string>

                A list of possible choices (for fields of type `multiple_choice` or `select_box`)

            • valuestring

              Value for the custom field

          • letterstring

            The first letter of the contacts last name

          • pending_dealboolean

            Does the contact have one or more pending deals?

          • total_pendingsnumber

            The total value of all pending deals for the contact

          • total_deals_countintegerint32

            Number of deals associated with the contact

          • company_sizeintegerint32

            Number of contacts within the contact's company

          • sales_closed_forarray<string>

            A list of user IDs, for whom the sales cycle is closed

          • closed_salesarray<object>

            A list of closed sales objects

            array item fields →
            • user_idstringbson-id

              ID of the user, for whom the sales cycle is closed

            • closed_atintegerunix-timestamp

              Time that the sales cycle was closed

            • commentstring

              An optional message detailing why the sales cycle was closed

          • google_contacts_dataobject

            The google contacts data associated with this contact

            object fields →
            • account_emailstring

              Google contacts email

            • idstring

              Google contact id

            • saved_atintegerunix-timestamp

              Time the contact was saved to google

          • created_atstringdate-time

            Creation time of the contact

          • modified_atstringdate-time

            Last modification time of the contact

        • next_actionsarray<object>
          array item fields →
          • idstringbson-id

            ID of the action

          • assignee_idstringbson-idrequired

            ID of the user, to whom the action is assigned. Defaults to the logged API user's ID.

          • contact_idstringbson-idrequired

            ID of the contact, with whom the action is associated

          • textstringrequired

            The main text/description of the action

          • statusstring

            Status of the action

            enum: asap · date · date_time · waiting · queued · queued_with_date · done

          • datestringdate

            Due date for the action (status must be one of `date`, `date_time` or `queued_with_date`). Defaults to today's date.

          • exact_timeintegerunix-timestamp

            The UNIX Epoch time in seconds the action is due (status must be `date_time`)

          • positionintegerint32

            The position of the action (in the list of queued actions)

          • doneboolean

            Has the action been marked as complete?

          • done_atstringdate

            The date the action was completed (only returned, if action complete)

          • created_atstringdate-time

            Creation time of the action

          • modified_atstringdate-time

            Last modification time of the action

        • next_actionobject

          Completable tasks related to Contacts. ASAP first, then dated actions ordered by due date (overdue first), followed by waiting for (blocked) and finally queued actions (without any date).

          object fields →
          • idstringbson-id

            ID of the action

          • assignee_idstringbson-idrequired

            ID of the user, to whom the action is assigned. Defaults to the logged API user's ID.

          • contact_idstringbson-idrequired

            ID of the contact, with whom the action is associated

          • textstringrequired

            The main text/description of the action

          • statusstring

            Status of the action

            enum: asap · date · date_time · waiting · queued · queued_with_date · done

          • datestringdate

            Due date for the action (status must be one of `date`, `date_time` or `queued_with_date`). Defaults to today's date.

          • exact_timeintegerunix-timestamp

            The UNIX Epoch time in seconds the action is due (status must be `date_time`)

          • positionintegerint32

            The position of the action (in the list of queued actions)

          • doneboolean

            Has the action been marked as complete?

          • done_atstringdate

            The date the action was completed (only returned, if action complete)

          • created_atstringdate-time

            Creation time of the action

          • modified_atstringdate-time

            Last modification time of the action

        • queued_actionsarray<object>
          array item fields →
          • idstringbson-id

            ID of the action

          • assignee_idstringbson-idrequired

            ID of the user, to whom the action is assigned. Defaults to the logged API user's ID.

          • contact_idstringbson-idrequired

            ID of the contact, with whom the action is associated

          • textstringrequired

            The main text/description of the action

          • statusstring

            Status of the action

            enum: asap · date · date_time · waiting · queued · queued_with_date · done

          • datestringdate

            Due date for the action (status must be one of `date`, `date_time` or `queued_with_date`). Defaults to today's date.

          • exact_timeintegerunix-timestamp

            The UNIX Epoch time in seconds the action is due (status must be `date_time`)

          • positionintegerint32

            The position of the action (in the list of queued actions)

          • doneboolean

            Has the action been marked as complete?

          • done_atstringdate

            The date the action was completed (only returned, if action complete)

          • created_atstringdate-time

            Creation time of the action

          • modified_atstringdate-time

            Last modification time of the action

        • next_action_conflictsarray<any>
      • pending_dealsarray<object>

        Pending deals across the company's contacts.

        array item fields →
        • dealobject

          Represent (potential) financial transactions with your contacts. Deals include information like amount, deal stage, closed date or expected close date. Deals support file attachments.

          object fields →
          • idstringbson-id

            ID of the deal

          • contact_idstringbson-idrequired

            ID of the contact, to whom the deal belongs

          • owner_idstringbson-idrequired

            ID of the user, to whom the deal belongs. Defaults to the logged API user's ID.

          • pipeline_idstringbson-id

            ID of a pipeline the deal belongs to

          • sales_pipeline_idstringbson-id

            ID of a sales pipeline the deal belongs to

          • namestringrequired

            Name of the deal

          • textstring

            Extra notes related to the deal (supports `[b]bold[/b]` and `[i]italic[/i]` formatting)

          • stageintegerint32

            A numerical representation of the progress of a pending deal (number ranging from 0 to 100 exclusive)

          • statusstring

            Status of the deal

            enum: pending · won · lost

          • expected_close_datestringdate

            The date the deal is expected to close (status should be `pending`). Defaults to today's date.

          • close_datestringdate

            The date the deal actually closed (status should be `won` or `lost`). Defaults to today's date.

          • datestringdate

            Creation date of the deal. Defaults to today's date.

          • amountnumberfloat

            The monitary value of the deal (per month, if multi-month deal)

          • monthsintegerint32

            Number of months the deal is to be paid for (1 for regular deals, 2+ for multi-month)

          • costnumberfloat

            The monitary cost of the deal

          • marginnumberfloat

            Profit margin for the deal (`amount` minus `cost`)

          • total_amountnumberfloat

            Product of amount and months (will only differ from `amount` field, if multi-month deal)

          • total_costnumberfloat

            Product of cost and months (will only differ from `cost` field, if multi-month deal)

          • commission_basestring

            Base used to calculate the commission of the deal

            enum: amount · margin

          • commission_typestring

            Type of commission for the deal

            enum: none · percentage · absolute

          • commissionnumberfloat

            Commission payable for the deal

          • commission_percentagenumberfloat

            Commission percentage for the deal

          • reason_lost_idstringbson-id

            ID of the reason lost

          • deal_fieldsarray<object>

            Custom field values on the deal.

            array item fields →
            • deal_fieldobject

              Extra user-configurable data fields for Deals. Only editable by admins.

              object fields →
              • idstringbson-id

                ID of the deal field

              • namestringrequired

                Name of the deal field

              • typestringrequired

                Type of the deal field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a deal doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).

                enum: date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider

              • positionintegerint32

                The position of the deal field in the list

              • choicesarray<string>

                A list of possible choices (for fields of type `multiple_choice` or `select_box`)

            • valuestring

              Value for the deal field

          • has_deal_itemsboolean

            Does the deal have deal items?

          • deal_itemsarray<object>

            Line items on the deal — each with a name, quantity, price, cost and amount.

            array item fields →
            • idstringbson-id

              ID of the deal item

            • namestringrequired

              Name of the deal item

            • descriptionstringrequired

              Description text of the deal item

            • costnumberfloatrequired

              Cost of the deal item

            • pricenumberfloatrequired

              Price of the deal item

            • amountnumberfloat

              Amount of the deal items

            • qtyintegerint32required

              Quantity of deal items

            • deal_idstringbson-id

              ID of the parent deal

            • predefined_item_idstringbson-id

              ID of the predefined item used for deal item creation (can be empty)

            • positionintegerint32

              Position of the predefined item in the items list

            • created_atstringdate-time

              Creation time of the deal item

            • modified_atstringdate-time

              Last modification time of the deal item

          • authorstring

            Shortened name of the creator of the deal. Defaults to the logged API user.

          • has_related_notesboolean

            Does the deal have related notes?

          • attachmentsarray<object>

            Files attached to the deal.

            array item fields →
            • idstringbson-id

              ID of the attachment

            • filenamestringrequired

              Name of the attachment file

            • custom_filenamestring

              Custom name of the attachment file

            • pinnedboolean

              Show if the attachment is pinned to its owner contact

            • pinned_atstring

              Shows pinned at timestamp. Is null if pinned == false

            • sizeintegerint32required

              Size of the attachment file (in bytes)

            • storage_providerstring

              Name of the storage provider (where the attachment file is stored)

              enum: amazon · google_drive · dropbox · evernote

            • urlstring

              External URL of the attachment file

            • url_expires_atstringdate-time

              The time the attachment URL expires

            • thumbnailobject

              An image preview of the attachment file (if one exists)

              object fields →
              • urlstring

                External URL of the attachment's thumbnail

          • contact_infoobject

            Information about the contact, to whom the deal belongs (read only).

            object fields →
            • contact_namestring

              Name of the contact associated with the deal

            • companystring

              Name of the company associated with the deal

          • ownerobject

            Information about the deal owner (read only).

            object fields →
            • idstring

              ID of the deal owner

            • namestring

              Name of the deal owner

            • emailstring

              Email address of the deal owner

          • previous_pipeline_stagesobject

            Returns the last stage in which the deal was for each pipeline (pipeline_id => stage) This field is returned only when 'include_history=true' param is supplied in query string

          • created_atstringdate-time

            Creation time of the deal

          • modified_atstringdate-time

            Last modification time of the deal

          • linked_contactsarray<object>

            Short form of contacts linked to the deal. Always returned with the deal payload (on both `GET /deals` and `GET /deals/{deal_id}`). For full contact objects use `fields=contacts(all)` on `GET /deals`.

            array item fields →
            • idstringbson-id

              ID of the linked contact

            • contact_namestring

              Full display name of the linked contact

            • companystring

              Display name of the company the contact belongs to (empty string if none)

            • photo_urlstring

              URL of the contact's profile picture (empty string if none)

      • created_atstringdate-time

        Creation time of the company

      • modified_atstringdate-time

        Last modification time of the company

  • lead_sourcesarray<object>
    array item fields →
    • idstring

      ID of the lead source

    • textstringrequired

      Description of the lead source

    • countsintegerint32

      Number of contacts the (logged API) user owns, with the lead source

    • total_countintegerint32

      Number of contacts the entire team owns, with the lead source

    • action_stream_countintegerint32

      Number of contacts the (logged API) user has actions with, who also have the lead source

    • team_countsarray<object>

      Number of contacts, with the lead source (for each team member)

      array item fields →
      • user_idstringbson-id

        ID of the user

      • countsintegerint32

        Number of contacts the team member owns, with the lead source

  • statusesarray<object>
    array item fields →
    • statusobject

      Values which help qualify where contacts are in the sales pipeline. The list of Statuses is already populated but it may be updated if needed, to better fit your organization.

      object fields →
      • idstringbson-id

        ID of the status

      • statusstring

        Type of the status

        enum: lead · prospect · customer · inactive · general · custom1 · custom2 · customX

      • textstringrequired

        Display text of the status

      • descriptionstring

        Longer description of what the status is for

      • colorstringhex-colorrequired

        The color of the status (six character hex value)

        enum: 666666 · 3399ff · cc0000 · f96600 · 000000 · ff00ff · 009900

      • countsintegerint32

        Number of contacts the (logged API) user owns, with the status

      • total_countintegerint32

        Number of contacts the entire team owns, with the status

      • action_stream_countintegerint32

        Number of contacts the (logged API) user has actions with, who also have the status

      • team_countsarray<object>

        Number of contacts, with the status (for each team member)

        array item fields →
        • user_idstringbson-id

          ID of the user

        • countsintegerint32

          Number of contacts the team member owns, with the status

  • tagsobject
    object fields →
    • tagsarray<object>
      array item fields →
      • namestring

        Name of the tag

      • countsintegerint32

        Number of contacts the (logged API) user owns, with the tag

      • total_countintegerint32

        Number of contacts the entire team owns, with the tag

      • action_stream_countintegerint32

        Number of contacts the (logged API) user has actions with, who also have the tag

    • system_tagsarray<object>
      array item fields →
      • namestring

        Name of the tag

      • countsintegerint32

        Number of contacts the (logged API) user owns, with the tag

      • total_countintegerint32

        Number of contacts the entire team owns, with the tag

      • action_stream_countintegerint32

        Number of contacts the (logged API) user has actions with, who also have the tag

  • contacts_countobject

    Counters showing the number of contacts per letter. The `all` object represents the entire account, while the `users` array contains the same breakdown but per user.

    object fields →
    • allarray<object>

      Counters for the entire account

      array item fields →
      • 1integerint32

        Contacts who's name begins with a non-alphabetic character

      • aintegerint32

        Contacts who's name begins with A

      • bintegerint32

        Contacts who's name begins with B

      • cintegerint32

        Contacts who's name begins with C

      • dintegerint32

        Contacts who's name begins with D

      • eintegerint32

        Contacts who's name begins with E

      • fintegerint32

        Contacts who's name begins with F

      • gintegerint32

        Contacts who's name begins with G

      • hintegerint32

        Contacts who's name begins with H

      • iintegerint32

        Contacts who's name begins with I

      • jintegerint32

        Contacts who's name begins with J

      • kintegerint32

        Contacts who's name begins with K

      • lintegerint32

        Contacts who's name begins with L

      • mintegerint32

        Contacts who's name begins with M

      • nintegerint32

        Contacts who's name begins with N

      • ointegerint32

        Contacts who's name begins with O

      • pintegerint32

        Contacts who's name begins with P

      • qintegerint32

        Contacts who's name begins with Q

      • rintegerint32

        Contacts who's name begins with R

      • sintegerint32

        Contacts who's name begins with S

      • tintegerint32

        Contacts who's name begins with T

      • uintegerint32

        Contacts who's name begins with U

      • vintegerint32

        Contacts who's name begins with V

      • wintegerint32

        Contacts who's name begins with W

      • xintegerint32

        Contacts who's name begins with X

      • yintegerint32

        Contacts who's name begins with Y

      • zintegerint32

        Contacts who's name begins with Z

      • total_countintegerint32
    • usersarray<object>

      Counters per user

      array item fields →
      • 1integerint32

        Contacts who's name begins with a non-alphabetic character

      • aintegerint32

        Contacts who's name begins with A

      • bintegerint32

        Contacts who's name begins with B

      • cintegerint32

        Contacts who's name begins with C

      • dintegerint32

        Contacts who's name begins with D

      • eintegerint32

        Contacts who's name begins with E

      • fintegerint32

        Contacts who's name begins with F

      • gintegerint32

        Contacts who's name begins with G

      • hintegerint32

        Contacts who's name begins with H

      • iintegerint32

        Contacts who's name begins with I

      • jintegerint32

        Contacts who's name begins with J

      • kintegerint32

        Contacts who's name begins with K

      • lintegerint32

        Contacts who's name begins with L

      • mintegerint32

        Contacts who's name begins with M

      • nintegerint32

        Contacts who's name begins with N

      • ointegerint32

        Contacts who's name begins with O

      • pintegerint32

        Contacts who's name begins with P

      • qintegerint32

        Contacts who's name begins with Q

      • rintegerint32

        Contacts who's name begins with R

      • sintegerint32

        Contacts who's name begins with S

      • tintegerint32

        Contacts who's name begins with T

      • uintegerint32

        Contacts who's name begins with U

      • vintegerint32

        Contacts who's name begins with V

      • wintegerint32

        Contacts who's name begins with W

      • xintegerint32

        Contacts who's name begins with X

      • yintegerint32

        Contacts who's name begins with Y

      • zintegerint32

        Contacts who's name begins with Z

      • total_countintegerint32
      • user_idstringbson-id

        ID of the user

  • team_streamobject

    Counters showing the number of entries in the action stream. The `all` object represents the entire account, while the `users` array contains the same breakdown but per user.

    object fields →
    • allintegerint32

      Counters for the entire account (`team_stream`/`action_stream?team=true`)

    • usersarray<object>

      Counters broken down per user (`team_stream?user_id={ID}`)

      array item fields →
      • user_idstringbson-id

        ID of the user

      • countsintegerint32

        The number of entries in the action steam for the user

Standard error responses: 400 · 401 · 403 · 404 · 409 · 500 — shared across the API. See Errors.

Related guides