Search contacts by rules

Return the contacts matching a segment rule tree — the same rule DSL used for dynamic lists, blast audiences, and flow rules. Rule trees use camelCase keys (fieldDefinitionId, listId, timeWindow), unlike the rest of the API. Trees may nest at most 5 levels deep and contain at most 100 nodes; email_step conditions are rejected here (they are only legal inside flow condition steps). Results can be additionally narrowed with search and are paginated. Items do not include custom_fields — fetch a single contact for those.

POST /v1/contacts/search

Search contacts by rules

cURL

curl --request POST \
  --url https://api.tented.ai/v1/contacts/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rules": {
    "conditions": [
      "<unknown>"
    ],
    "kind": "group",
    "operator": "and"
  },
  "page": 1,
  "limit": 25,
  "search": "<string>",
  "sort": "updated_at",
  "order": "desc"
}
'

200

{
  "items": [
    {
      "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "display_name": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "email_domain": "<string>",
      "company": "<string>",
      "job_title": "<string>",
      "address": "<string>",
      "address2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "zip_code": "<string>",
      "original_source": "<string>",
      "original_source_detail": "<string>",
      "lead_status": "<string>",
      "lifecycle_stage": "<string>",
      "tented_score": 123,
      "unsubscribed": true,
      "marketing_email_subscribed": true,
      "marketing_sms_subscribed": true,
      "marketing_email_invalid": true,
      "marketing_sms_invalid": true,
      "last_activity_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "totalPages": 123
  }
}

Authorizations

Authorization · string · header · required

Workspace API key, e.g. Authorization: Bearer tented_.... Create keys in Workspace Settings → API Keys.

Body

application/json

rules · object · required

Segment rule tree evaluated against the contact base, e.g. {"kind": "group", "operator": "and", "conditions": [{"kind": "condition", "source": "contact", "field": "state", "operator": "equals", "value": "CA"}]}.

Show child attributes

page · integer · default: 1

Page number, starting at 1.

Required range: x >= 1

limit · integer · default: 25

Results per page (1–100).

Required range: 1 <= x <= 100

search · string

Case-insensitive substring match against display name, email, phone, company, first name, and last name, applied on top of rules.

Maximum string length: 255

sort · enum<string> · default: updated_at

Sort key.

Available options: created_at, updated_at, last_activity_at, display_name, first_name, last_name, normalized_email, original_source

order · enum<string> · default: desc

Sort direction.

Available options: asc, desc

Response

200

application/json

A page of matching contacts.

items · object[] · required

Contacts in this page, with every standard contact field (without custom_fields).

Show child attributes

pagination · object · required

Offset pagination metadata.

Show child attributes