Skip to navigation
advanced_filtering

Search objects with filters

View as Markdown

Find Leads, Contacts, Opportunities, Activities, Tasks and other objects matching any combination of filters. This is the API behind the filters on the Leads, Contacts and Opportunities pages in Close, and the query language used by Smart Views (s_query) and bulk actions.

Searching doesn’t change any data.

Building a query

A query is a tree of objects, each with a type:

  1. Start with an and query.
  2. Add an object_type query for the type of objects you want, e.g. {"type": "object_type", "object_type": "lead"}.
  3. Add a field_condition query for each filter. It combines a field with a condition:
    • Built-in fields are regular_fields. Their object_type must be the type you’re searching for, e.g. title on contact.
    • Custom fields are referenced by ID as custom_fields. List them with the custom field endpoints, e.g. GET /custom_field/lead/.
    • The condition depends on the field’s type: text for text, term for choices and fixed values, reference for IDs (statuses, users, …), number_range for numbers, moment_range for dates. See FieldCondition.
  4. To filter by related objects, use has_related. For example, Leads with a Contact whose title contains “CEO”, or Contacts whose Lead is in a status.

Use or for alternatives and set negate: true on any query to exclude what it matches.

You can also build a filter on the Leads, Contacts or Opportunities page in Close and copy its JSON with Copy Filters in the page’s menu.

Dates

Relative dates are resolved when the search runs. For example, “in the last 30 days” is a moment_range condition starting at an offset moment of 30 days in the past. Dates without a timezone use the timezone from the X-TZ-Name header (an IANA name like America/New_York), or UTC.

Results

Results only contain each object’s id and __object_type unless you list the fields you want in _fields, e.g. {"lead": ["id", "display_name"]}. Field names are the same as in the object type’s own endpoint.

Pagination and limits

  • Each page has up to _limit results (at most 200). Pass the response’s cursor to get the next page. The last page has a null cursor. Cursors expire after 30 seconds.
  • Pagination stops after 10,000 results. To go through more, split the search, e.g. by date_created ranges.
  • Sort by a field that rarely changes, like date_created, while paginating.
  • results_limit caps the total number of results. Set it to 0 with include_counts: true to only count matches.
  • The request body can be at most 50 KB. Overly complex queries are rejected.

Authentication

AuthorizationBasic
Use your API key as the username and leave the password empty.
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
_fieldsmap from strings to lists of stringsOptionalDefaults to {}

Fields to return for each object type. The field names are the same as in the object type’s own endpoint, e.g. {"lead": ["id", "display_name"]}. Custom fields use custom.cf_abc123. Without it, results only contain id and __object_type.

_limitintegerOptional1-200Defaults to 10
Number of results per page.
cursorstring or nullOptional

The cursor from the previous page’s response. Cursors expire after 30 seconds.

include_countsbooleanOptionalDefaults to false

Whether to include the number of matches in count.

queryobjectOptional

The query objects must match. Start with an and query that contains an object_type query for the type of objects to return.

results_limitinteger or nullOptional

Maximum number of results across all pages, e.g. to act only on the first 100 matches. Use 0 with include_counts to only count matches.

sortlist of objectsOptionalDefaults to []

Fields to sort results by. When paginating, sort by a field that rarely changes, like date_created, so no results are skipped.

Response

Successful response
cursorstring or null

Pass it as cursor to get the next page. null on the last page.

datalist of objects
The matching objects on this page.
countobjectOptional

Number of matches. Only included with include_counts.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error