Search Customers

Search your customers by core fields and custom 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/customers/search`

Request Body

All fields are optional. An empty body matches all (active) customers.

Field	Type	Required	Description
`filters`	array	No	Filter conditions, combined with AND. Maximum 10. Omit or leave empty to match all customers.
`properties`	string[]	No	Custom 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 custom property codename, or one of the core fields: `name`, `is_churned`, `fitscore`, `engagementscore`, `engagementscore_difference`, `churn_risk`, `last_seen`, `owner`, `tags`.
`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. By default only active customers are returned. To include or target churned customers, add an is_churned filter (EQ with value true returns churned customers only, EQ with value false returns active customers only).

Filtering by owner and tags

Filter owner by the email of the owning user and tags by tag title. Both support the operators EQ, NEQ, IN, NIN, KNOWN and UNKNOWN only.

Field	Value to pass	Examples
`owner`	User email address(es)	`{ "propertyName": "owner", "operator": "EQ", "value": "jane@acme.com" }`
`tags`	Tag title(s)	`{ "propertyName": "tags", "operator": "IN", "values": ["VIP", "Trial"] }`

For tags, an IN (or EQ) filter matches customers that have any of the listed tags. Use KNOWN/UNKNOWN to match customers that have any owner/tag or none at all. Emails and tag titles are matched case-insensitively; values that don't match any user or tag simply return no results (IN/EQ) or all results (NIN/NEQ).

Example Request

curl -X POST "https://api.customerscore.io/api/v1/customers/search" \
  -H "Content-Type: application/json" \
  -H "customerscore-key: your-generated-key" \
  -d '{
    "filters": [
      { "propertyName": "fitscore", "operator": "GTE", "value": "75" },
      { "propertyName": "plan", "operator": "IN", "values": ["enterprise", "pro"] }
    ],
    "properties": ["mrr", "plan"],
    "limit": 100
  }'

Response Body

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

Customer Object

Field	Type	Nullable	Description
`id`	string	No	Customer external ID (the identifier from your system).
`customerscore_id`	number	No	Internal CustomerScore ID of the customer record.
`name`	string	Yes	Customer name.
`fitscore`	number	Yes	Fit score.
`engagementscore`	number	Yes	Engagement (health) score.
`churn_risk`	number	Yes	Churn risk score.
`is_churned`	boolean	Yes	Whether the customer is churned.
`last_seen`	string	Yes	Latest scoring date (`YYYY-MM-DD`).
`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`).
`owner`	string	Yes	Email of the user who owns this customer. `null` when unassigned.
`tags`	string[]	No	Titles of the tags assigned to this customer. Empty array when none.
`properties`	object	No	Custom property values keyed by codename.
`createdAt`	string	Yes	When the customer record was created (ISO 8601).
`updatedAt`	string	Yes	When the customer record was last updated (ISO 8601).

Example Response

{
  "results": [
    {
      "id": "12345",
      "customerscore_id": 98765,
      "name": "Acme Corporation",
      "fitscore": 82,
      "engagementscore": 67,
      "churn_risk": 18,
      "is_churned": false,
      "last_seen": "2024-06-15",
      "engagementscore_difference": 3,
      "engagementscore_trend": {
        "2024-06-14": 64,
        "2024-06-15": 67
      },
      "owner": "jane@acme.com",
      "tags": ["VIP", "Trial"],
      "properties": {
        "mrr": 1500,
        "plan": "enterprise"
      },
      "createdAt": "2024-01-10T08:30:00.000Z",
      "updatedAt": "2024-06-15T09:00:00.000Z"
    }
  ],
  "paging": {
    "next": {
      "after": 1234
    }
  }
}

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 customers returned
400	Bad request (e.g. unknown property codename, invalid operator)
401	Unauthorized - Missing `customerscore-key` in the header
403	Forbidden - Invalid key
405	Method Not Allowed - Only POST method is allowed

Delete Customer Get Customer