Count contacts matching a set of criteria

POST

/api/v3/contacts/segments/criteria/count

curl --request POST \
  --url 'https://api.tryletterhead.com/api/v3/contacts/segments/criteria/count?api=true' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "criteria": { "matchMode": "all", "conditions": [ { "type": "geoRadius", "latitude": 40.7128, "longitude": -74.006, "distanceMiles": 50 } ], "suppressionSegmentIds": [] } }'

• Production

Returns how many contacts a set of criteria would reach, without saving it as a segment — the same criteria shape Create a segment accepts. Useful for checking a distance, a threshold, or any other condition against a real number before deciding whether to save it.

This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.

Response

200 OK with an empty items array. The match count is returned in the response envelope’s total, not in items.

Authorizations

• bearerAuth

Parameters

Query Parameters

api

required

boolean

Required. Set to true.

Request Body ^required

Media type application/json

object

criteria

required

The criteria to evaluate. Not persisted.

object

matchMode

required

all (AND the conditions) or any (OR the conditions).

string

conditions

required

At least one condition — same shapes as Create a segment’s criteria.conditions[].

Array<object>

object

type

required

The condition’s discriminator — one of the type values documented on Create a segment’s criteria.conditions[] (e.g. customField, tag, subscription, text, geoRadius, …). The remaining properties on each condition vary by this value; see that operation for the full per-type shapes.

string

suppressionSegmentIds

IDs of other segments (same company) whose members are excluded from the count.

Array<integer>

channel

Count only contacts subscribed to the given channel identifier (slug). Omit for the full company audience.

string

Example

{
  "criteria": {
    "matchMode": "all",
    "conditions": [
      {
        "type": "geoRadius",
        "latitude": 40.7128,
        "longitude": -74.006,
        "distanceMiles": 50
      }
    ],
    "suppressionSegmentIds": []
  }
}

Responses

200

200 OK

Media type application/json

object

items

Array

message

string

total

integer

Example

{
  "items": [],
  "message": "Criteria count retrieved.",
  "total": 4213
}