Search Contacts

Search and filter contacts in your workspace with optional field filters, tag filters, status filter, sorting, and pagination.

---

Endpoint

POST https://api.campaignlark.com/v1/contacts/search

---

Request Body

Field	Type	Required	Description
fields	array	optional	Array of field filter objects. See Field Filter Object below.
tags	array of integers	optional	Filter contacts that have all of the specified tag IDs.
status	string	optional	Filter by email subscription status. One of SUBSCRIBED, UNSUBSCRIBED, UNCONFIRMED, CLEANED, COMPLAINED.
sms_status	string	optional	Filter by SMS subscription status. One of SUBSCRIBED, UNSUBSCRIBED, CLEANED, BLOCKED. If omitted, no SMS status filtering is applied. Filtering by SUBSCRIBED also includes contacts with no stored SMS status.
page	integer	optional	Page number (1-indexed). Defaults to 1.
limit	integer	optional	Results per page. Min 10, max 250.
sort_by	string	optional	Field to sort by. One of created_at, updated_at. Defaults to created_at.
sort_order	string	optional	Sort direction. One of asc, desc. Defaults to asc.

The status and sms_status filters are independent. When both are provided, contacts must match both filters.

Field Filter Object

Field	Type	Required	Description
merge_tag	string	required	The merge tag of the field to filter on (e.g. email_address, first_name).
operator	string	required	Filter operator. See Filter Operators below.
value	any	optional	The value to compare against. Not required for existence operators.

Filter Operators

Operator	Description
EQUALS	Field value equals the given value.
NOT_EQUALS	Field value does not equal the given value.
CONTAINS	Field value contains the given string.
NOT_CONTAINS	Field value does not contain the given string.
EXISTS	Field has a value set.
GREATER_THAN	Field value is greater than the given value.
LESS_THAN	Field value is less than the given value.

---

Sample Request

POST https://api.campaignlark.com/v1/contacts/search
Content-Type: application/json

{
  "fields": [
    {
      "merge_tag": "first_name",
      "operator": "CONTAINS",
      "value": "John"
    }
  ],
  "tags": [1, 3],
  "status": "SUBSCRIBED",
  "sms_status": "SUBSCRIBED",
  "page": 1,
  "limit": 50,
  "sort_by": "created_at",
  "sort_order": "desc"
}

---

Response

Success — 200 OK

{
  "data": {
    "contacts": [
      {
        "id": "69d5fd68c03518e49bb0f9cb",
        "fields": {
          "country": "US",
          "email_address": "jane.doe@example.com",
          "first_name": "Jane",
          "last_name": "Doe",
          "phone_number": null
        },
        "tags": [
          {
            "id": 1,
            "name": "newsletter"
          }
        ],
        "status": "SUBSCRIBED",
        "sms_status": "SUBSCRIBED",
        "score": 0,
        "created_at": "2025-03-15T10:30:00Z",
        "updated_at": "2025-03-15T10:30:00Z"
      },
      {
        "id": "69d5f8d7c03518e49bb0f9c6",
        "fields": {
          "country": "CA",
          "email_address": "john.smith@example.com",
          "first_name": "John",
          "last_name": "Smith",
          "phone_number": null
        },
        "tags": [
          {
            "id": 1,
            "name": "newsletter"
          }
        ],
        "status": "SUBSCRIBED",
        "sms_status": "SUBSCRIBED",
        "score": 0,
        "created_at": "2025-03-14T08:15:00Z",
        "updated_at": "2025-03-14T08:15:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total_pages": 3,
      "total_count": 142
    }
  }
}

Contact responses include sms_status. If no SMS status is stored, sms_status is reported as SUBSCRIBED.