API Reference / Contacts

GET /contacts/filters/{filter_id}

Show contacts that meet the criteria of a filter

Returns the contacts matching a saved filter, alongside the filter's own definition. Results come back in Action Stream order and are fixed at 25 per page — per_page is accepted but ignored here.

Path parameters

Name Type Description
filter_id req string Filter ID

Responses

200 OK
  • statusintegerint32

    Response code

  • messagestring

    Response message

  • timestampintegerunix-timestamp

    Response time

  • dataobject
    object fields →
    • filterobject

      Allow you to query contacts in your own custom way. These filters can only be created on the website but they can be used through the API.

      object fields →
      • idstringbson-id

        ID of the custom filter

      • namestring

        Name of the custom filter

      • conditionsarray<array<string>>

        Conditions of the custom filter

    • total_countintegerint32

      Total number of items

    • pageintegerint32

      Current page number

    • per_pageintegerint32

      Number of items returned in each page

    • max_pageintegerint32

      The page number of the last page of items

    • contactsarray<object>
      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

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

Related guides