CLclose
advanced_filtering

Search objects with filters

Changed on

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. See the fields of each object type.
    • 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.
post/data/search/

Request

  • Base URL
    https://api.close.com/api/v1
  • URL
    https://api.close.com/api/v1/data/search/
  • Auth
    • HTTP basic
    • or OAuth 2
      Authorization code: https://app.close.com/oauth2/authorize/
      Token URL: https://api.close.com/oauth2/token/

Request body

_fieldsobject

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.

_limitinteger

Number of results per page.

cursorstring nullable

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

include_countsboolean

Whether to include the number of matches in count.

results_limitinteger nullable

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.

Response

Successful response

cursorstring nullable required

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

Changes

  • b93f4716e9bfRevision changes
    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • breaking

      removed the pattern property ^custom\. from the // response property for the status

    • warning

      removed the optional property /////// from the response with the status

    • warning

      removed the optional property /////// from the response with the status

    • warning

      removed the optional property //////// from the response with the status

    • warning

      removed the optional property //////// from the response with the status

    • warning

      removed the optional property ///// from the response with the status

    • warning

      removed the optional property ///// from the response with the status

    • warning

      removed the optional property ///// from the response with the status

    • warning

      removed the optional property ///// from the response with the status

    • warning

      removed the optional property ////// from the response with the status

    • warning

      removed the optional property ////// from the response with the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the // response property for the status

  • 8e360c61058cRevision changes
    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the //// response property for the status

    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the //// response property for the status