Search Contacts

Search your contacts by core fields, the company they belong to and custom contact property codenames, with pagination and property selection.

For interactive API documentation, see the Swagger reference (opens in a new tab).

Endpoint

Method	URL
POST	`https://api.customerscore.io/api/v1/contacts/search`

Request Body

All fields are optional. An empty body matches all contacts.

Field	Type	Required	Description
`filters`	array	No	Filter conditions, combined with AND. Maximum 10. Omit or leave empty to match all contacts.
`properties`	string[]	No	Contact property codenames to include in the `properties` object. Omit to return all. Core fields are always returned regardless.
`limit`	integer	No	Maximum number of records per page. Default `100`, minimum `1`, maximum `1000`.
`after`	integer	No	Pagination cursor. Pass the `paging.next.after` value from the previous response to fetch the next page.

Filter Object

Each item in filters describes a single condition.

Field	Type	Required	Description
`propertyName`	string	Yes	A contact property codename (see Contact attributes (opens in a new tab) and Contact metrics (opens in a new tab)), or one of the core fields: `name`, `engagementscore`, `engagementscore_difference`, `last_seen`, `tags`, `customer_external_id`.
`operator`	string	Yes	Comparison operator — see the table below.
`value`	string	No	Single value for the comparison. Not used for `KNOWN`/`UNKNOWN`, or when `values` is provided.
`values`	string[]	No	List of values for the `IN` / `NIN` operators.

Operators

Operator	Meaning	Value
`EQ`	Equal to	`value`
`NEQ`	Not equal to	`value`
`LT`	Less than	`value`
`LTE`	Less than or equal to	`value`
`GT`	Greater than	`value`
`GTE`	Greater than or equal to	`value`
`LIKE`	Contains	`value`
`NLIKE`	Does not contain	`value`
`IN`	Is one of	`values` (array)
`NIN`	Is none of	`values` (array)
`GTD`	More than N days ago (date offset)	`value` (number of days)
`LTD`	Less than N days ago (date offset)	`value` (number of days)
`KNOWN`	Has a value (not empty)	none
`UNKNOWN`	Has no value (empty)	none

All filters are combined with AND. All contacts are returned, including contacts of churned customers. The customer-only fields fitscore, churn_risk, upsell_score, is_churned and owner cannot be used to filter contacts.

Filtering by customer and tags

Filter customer_external_id by the external ID of the customer the contact belongs to, and tags by tag title.

Field	Value to pass	Operators	Example
`customer_external_id`	Customer external ID(s)	`EQ`, `NEQ`, `IN`, `NIN`	`{ "propertyName": "customer_external_id", "operator": "EQ", "value": "12345" }`
`tags`	Tag title(s)	`EQ`, `NEQ`, `IN`, `NIN`, `KNOWN`, `UNKNOWN`	`{ "propertyName": "tags", "operator": "IN", "values": ["Champion", "Decision maker"] }`

Customer external IDs are matched exactly (case-sensitive); tag titles are matched case-insensitively. For tags, an IN (or EQ) filter matches contacts that have any of the listed tags. Values that don't match any customer or tag simply return no results (IN/EQ) or all results (NIN/NEQ).

Example Request

curl -X POST "https://api.customerscore.io/api/v1/contacts/search" \
  -H "Content-Type: application/json" \
  -H "customerscore-key: your-generated-key" \
  -d '{
    "filters": [
      { "propertyName": "customer_external_id", "operator": "EQ", "value": "12345" },
      { "propertyName": "engagementscore", "operator": "GTE", "value": "50" }
    ],
    "properties": ["job_title", "email"],
    "limit": 100
  }'

Response Body

Field	Type	Description
`results`	array	Matching contacts, ordered by id ascending. See the contact object below.
`paging`	object	Present only when more pages are available. Contains `next.after` cursor.

Contact Object

Field	Type	Nullable	Description
`id`	string	No	Contact external ID (the identifier from your system).
`customerscore_id`	number	No	Internal CustomerScore ID of the contact record.
`name`	string	Yes	Contact name.
`engagementscore`	number	Yes	Engagement (health) score.
`engagementscore_difference`	number	Yes	Engagement score change since the previous scoring record.
`engagementscore_trend`	object	Yes	Engagement score history (last 15 records within 1 year), keyed by scoring date (`YYYY-MM-DD`).
`last_seen`	string	Yes	Latest scoring date (`YYYY-MM-DD`).
`tags`	string[]	No	Titles of the tags assigned to this contact. Empty array when none.
`customer_external_id`	string	Yes	External ID of the customer the contact belongs to.
`customer_customerscore_id`	number	Yes	Internal CustomerScore ID of the customer the contact belongs to.
`properties`	object	No	Custom contact property values keyed by codename.
`createdAt`	string	Yes	When the contact record was created (ISO 8601).
`updatedAt`	string	Yes	When the contact record was last updated (ISO 8601).

Example Response

{
  "results": [
    {
      "id": "contact-001",
      "customerscore_id": 45678,
      "name": "John Doe",
      "engagementscore": 72,
      "engagementscore_difference": 4,
      "engagementscore_trend": {
        "2024-06-14": 68,
        "2024-06-15": 72
      },
      "last_seen": "2024-06-15",
      "tags": ["Champion"],
      "customer_external_id": "12345",
      "customer_customerscore_id": 98765,
      "properties": {
        "job_title": "CTO",
        "email": "[email protected]"
      },
      "createdAt": "2024-01-10T08:30:00.000Z",
      "updatedAt": "2024-06-15T09:00:00.000Z"
    }
  ],
  "paging": {
    "next": {
      "after": 45678
    }
  }
}

Pagination. Results are returned in pages ordered by an internal cursor. When a paging.next.after value is present, more results are available — pass it as after in your next request. Keep requesting until the response no longer contains a paging object.

Response Codes

Code	Description
200	Matching contacts returned
400	Bad request (e.g. unknown property codename, invalid operator, customer-only filter field)
401	Unauthorized - Missing `customerscore-key` in the header
403	Forbidden - Invalid key
405	Method Not Allowed - Only POST method is allowed

Delete Contact Get Contact