Projections

Default projections

By default, search API only returns id and version fields of first 50 matched documents. per_page parameter can be used to limit the number of results returned.

Fetch contacts

POST /v3/contacts/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [{
      "data": {
        "per_page": 2
      }
  }]
}

Content-Type: application/json; charset=UTF-8

{
  "items": [
    {
      "successful": true,
      "items": [
        {
          "data": {
            "id": 123,
            "version": 2
          },
          "meta": {
            "type": "contact"
          }
        },
        {
          "data": {
            "id": 456,
            "version": 5
          },
          "meta": {
            "type": "contact"
          }
        }
      ],
      "meta": {
        "count": 2,
        "http_status": "200 OK",
        "links": {
          "next_page": "nextPageToken="
        },
        "total_count": 11480,
        "type": "collection"
      }
    }
  ]
}

---

Explicit projections

If you wish to fetch other fields as well, you need to explicitly request them using projections. Projections are requested by providing array of attribute names. If listed attributes exist, they will be returned for each item in response (otherwise error will be returned).

Fetch contacts

POST /v3/contacts/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "data": {
        "query": {
          "projection": [
            {
              "name": "display_name"
            },
            {
              "name": "owner"
            }
          ]
        }
      },
      "per_page": 2
    }
  ]
}

Content-Type: application/json; charset=UTF-8

{
    "items": [
        {
            "successful": true,
            "items": [
                {
                    "data": {
                        "owner": {
                            "name": "John Doe",
                            "id": 99999
                        },
                        "id": 123,
                        "display_name": "Aarika Dejoseph",
                        "version": 1
                    },
                    "meta": {
                        "type": "contact"
                    }
                },
                {
                    "data": {
                        "owner": {
                            "name": "Jane Doe",
                            "id": 888888
                        },
                        "id": 6479997,
                        "display_name": "Aarika Maulsby",
                        "version": 3
                    },
                    "meta": {
                        "type": "contact"
                    }
                }
            ],
            "meta": {
                "count": 2,
                "http_status": "200 OK",
                "links": {
                    "next_page": "nextPageToken=="
                },
                "total_count": 11480,
                "type": "collection"
            }
        }
    ]
}

---

Custom Fields projections

Custom fields in projections behaves exactly as describe in the section above. If the requested custom fields exist, they will be returned for each item in response, otherwise they will be ignored. Before you proceed you need a list of unique identifiers of the custom fields that you're going to request. Notice that you can't simply get all the custom fields by querying "custom_fields" attribute - the query will result with an error. All the currently exposed indices support custom fields.

See the table below for the syntax:

Syntax	Index	Example	Notes
custom_fields.{customFieldId}	leads	custom_fields.1
custom_fields.{customFieldId}	deals	custom_fields.1
custom_fields.contact:{customFieldId}	contacts	custom_fields.contact:1	Where customFieldId is a unique identifier of a contact's custom field
custom_fields.sales_account:{customFieldId}	contacts	custom_fields.sales_account:1	Where customFieldId is a unique identifier of a sales account's custom field

Fetch leads

together with a string custom field named "SKU" with an id 1

POST /v3/contacts/leads

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "data": {
        "query": {
          "projection": [
            {
              "name": "custom_fields.1"
            }
          ]
        }
      },
      "per_page": 2
    }
  ]
}

Content-Type: application/json; charset=UTF-8

{
    "items": [
        {
            "successful": true,
            "items": [
                {
                    "data": {
                        "id": 123,
                        "version": 1,
                        "custom_fields.1": "902211946-1"
                    },
                    "meta": {
                        "type": "contact"
                    }
                },
                {
                    "data": {
                        "id": 6479997,
                        "version": 3,
                        "custom_fields.1": "902211946-2"
                    },
                    "meta": {
                        "type": "contact"
                    }
                }
            ],
            "meta": {
                "count": 2,
                "http_status": "200 OK",
                "links": {
                    "next_page": "nextPageToken=="
                },
                "total_count": 11480,
                "type": "collection"
            }
        }
    ]
}