POST /api/v2/custom_objects/{custom_object_key}/records/search

Returns an array of custom object records that meet the search and filter criteria.

Filters can contain either an individual comparison object or an array of comparison objects within logical namespaces.

A filter is a JSON object that has the following properties:

Name	Type	Required	Description
ATTRIBUTE	object	no	A comparison object specifying an attribute value condition to be met for records to match. Examples are marked below.
$and	array	no	Array of conjunctive filter objects (logical AND)
$or	array	no	Array of conjunctive filter objects (logical OR)

Examples

{
  "filter": {
    "custom_object_fields.field_key": { "$eq": "value" } // ATTRIBUTE
  }
}

// $or
{
  "filter": {
    "$or": [
      { "custom_object_fields.field_key": { "$eq": "value" } }, // ATTRIBUTE
      { "external_id": { "$eq": "Record123" } } // ATTRIBUTE
    ]
  }
}

Comparison Object

A comparison object defines a condition a record must meet to be considered a match. The condition is based on an attribute value or object type.

A comparison object is a JSON object that has the following properties:

Name	Type	Required	Description
FIELD_KEY	string	yes	When filtering on a custom field, they must be namedspaced with `custom_object_fields.`. ex. `custom_object_fields.field_key` When filtering on a standard field, no namespace is required. The following fields are considered standard: `created_at`, `updated_at`, `created_by_user`, `updated_by_user`, `name`, `external_id`
OPERATOR	string	yes	Supported operators vary by the value's data type
VALUE	string, array	yes	The value you're filtering for

Pagination

Cursor pagination only.
Returns the records sorted by relevancy with page limits. Without a sort parameter, only the first 10,000 records are returned. With a sort parameter, all records are returned.

Allowed For

Agents
End users (when an admin configures the custom object to be accessible to end users)

Servers

https://{subdomain}.{domain}.com

Path parameters

Name	Type	Required	Description
`custom_object_key`	String	Yes	The key of a custom object

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Query parameters

Name	Type	Required	Description
`query`	String	No	The query parameter is used to search text-based fields for records that match specific query terms. The query can be multiple words or numbers. Every record that matches the beginning of any word or number in the query string is returned. Fuzzy search is supported for the following text-based field types: Text fields, Multi Line Text fields, and RegExp fields. For example, you might want to search for records related to Tesla vehicles: `query=Tesla`. In this example the API would return every record for the given custom object where any of the supported text fields contain the word 'Tesla'. You can include multiple words or numbers in your search. For example: `query=Tesla Honda 2020`. This search phrase would be URL encoded as `query=Tesla%20Honda%202020` and return every record for the custom object for which any of the supported text fields contained 'Tesla', 'Honda', or '2020'.
`sort`	String	No	One of `name`, `created_at`, `updated_at`, `-name`, `-created_at`, or `-updated_at`. The `-` denotes the sort will be descending. Defaults to sorting by relevance.
`pageafter`	String	No	A pagination cursor that tells the endpoint which page to start on. It should be a `meta.after_cursor` value from a previous request. Note: `page[before]` and `page[after]` can't be used together in the same request.
`pagebefore`	String	No	A pagination cursor that tells the endpoint which page to start on. It should be a `meta.before_cursor` value from a previous request. Note: `page[before]` and `page[after]` can't be used together in the same request.
`pagesize`	Integer	No	Specifies how many records should be returned in the response. You can specify up to 100 records per page.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.