Search Contacts

Find contacts by email address, custom field values, or other criteria using the search API.

Goal

By the end of this guide you will be able to search for contacts by email (useful for dedup checks), filter by custom field values, and paginate through large result sets.

Prerequisites

An API key with contacts:read scope
Your API base URL (found on the Settings > API Keys page)
A contact structure ID — search operates within a single contact structure. Retrieve yours with GET /api/contact-structure (see Manage Custom Fields)

Scope note: Contact search uses POST but is semantically a read operation. It requires only contacts:read scope (not contacts:write).

Steps

1. Search by email address

This is the most common search pattern, useful for deduplication before creating a contact.

curl -X POST https://api-us-west-2-c1.benchmarkemail.com/api/contact/search \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "page": 1,
    "pageSize": 10,
    "source": ["_id", "key", "fields", "createdAt", "updatedAt"],
    "contactSpecification": {
      "filters": [
        {
          "criterias": [
            {
              "columnToFilter": "KEY",
              "operator": "EQ",
              "values": ["jane.smith@example.com"]
            }
          ]
        }
      ]
    }
  }'

Response (200 OK):

{
  "contacts": [
    {
      "_id": "66f1a6e4698f1bca60424901",
      "key": "jane.smith@example.com",
      "fields": [
        { "_id": "64a1b2c3d4e5f6a7b8c9d100", "value": "Jane" },
        { "_id": "64a1b2c3d4e5f6a7b8c9d101", "value": "Smith" }
      ],
      "createdAt": "2026-03-28T14:30:00.000Z",
      "updatedAt": "2026-03-28T14:30:00.000Z",
      "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1"
    }
  ],
  "totalRecords": 1
}

Dedup pattern: Before creating a contact, search by email using "operator": "EQ". If totalRecords is 0, the email is not in use and you can safely create the contact.

2. Search by email domain

Find all contacts from a specific email domain.

curl -X POST https://api-us-west-2-c1.benchmarkemail.com/api/contact/search \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "page": 1,
    "pageSize": 25,
    "source": ["_id", "key", "fields"],
    "contactSpecification": {
      "filters": [
        {
          "criterias": [
            {
              "columnToFilter": "EMAIL_DOMAIN",
              "operator": "EQ",
              "values": ["example.com"]
            }
          ]
        }
      ]
    }
  }'

3. Search by custom field values

Filter contacts based on custom field values. Use the field’s _id from your contact structure.

curl -X POST https://api-us-west-2-c1.benchmarkemail.com/api/contact/search \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "page": 1,
    "pageSize": 25,
    "source": ["_id", "key", "fields", "tags"],
    "contactSpecification": {
      "filters": [
        {
          "criterias": [
            {
              "columnToFilter": "FIELD_ID",
              "id": "64a1b2c3d4e5f6a7b8c9d102",
              "operator": "EQ",
              "values": ["Enterprise"]
            }
          ]
        }
      ]
    }
  }'

Response (200 OK):

{
  "contacts": [
    {
      "_id": "66f1a6e4698f1bca60424905",
      "key": "alice@enterprise-corp.com",
      "fields": [
        { "_id": "64a1b2c3d4e5f6a7b8c9d100", "value": "Alice" },
        { "_id": "64a1b2c3d4e5f6a7b8c9d101", "value": "Chen" },
        { "_id": "64a1b2c3d4e5f6a7b8c9d102", "value": "Enterprise" }
      ],
      "tags": [
        { "_id": "64a1b2c3d4e5f6a7b8c9d300" }
      ],
      "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1"
    }
  ],
  "totalRecords": 1
}

4. Combine multiple criteria

Use multiple criteria objects to build complex filters. Criteria within the same group are AND-ed; separate groups are OR-ed.

curl -X POST https://api-us-west-2-c1.benchmarkemail.com/api/contact/search \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "page": 1,
    "pageSize": 25,
    "source": ["_id", "key", "fields", "createdAt"],
    "contactSpecification": {
      "filters": [
        {
          "criterias": [
            {
              "columnToFilter": "FIELD_ID",
              "id": "64a1b2c3d4e5f6a7b8c9d102",
              "operator": "EQ",
              "values": ["Enterprise"]
            },
            {
              "columnToFilter": "CREATED_AT",
              "operator": "GT",
              "values": ["2026-01-01T00:00:00.000Z"]
            }
          ]
        }
      ]
    }
  }'

This searches for contacts where the custom field equals “Enterprise” AND the contact was created after January 1, 2026.

5. Search within a specific list

Filter contacts that belong to a specific list.

curl -X POST https://api-us-west-2-c1.benchmarkemail.com/api/contact/search \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "page": 1,
    "pageSize": 25,
    "source": ["_id", "key", "fields"],
    "contactSpecification": {
      "filters": [
        {
          "criterias": [
            {
              "columnToFilter": "LIST_ID",
              "operator": "IN",
              "values": ["66f1a6e4698f1bca60425001"]
            }
          ]
        }
      ]
    }
  }'

6. Paginate through results

For large result sets, increment the page parameter to retrieve subsequent pages. Pages are 1-indexed.

# Page 1 (first 50 results)
curl -X POST https://api-us-west-2-c1.benchmarkemail.com/api/contact/search \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "page": 1,
    "pageSize": 50,
    "source": ["_id", "key"],
    "contactSpecification": {
      "filters": [
        {
          "criterias": [
            {
              "columnToFilter": "CONTACT_STATUS",
              "operator": "EQ",
              "values": ["active"]
            }
          ]
        }
      ]
    },
    "sortField": [
      {
        "column": "CREATED_AT",
        "order": "desc"
      }
    ]
  }'

Response (200 OK):

{
  "contacts": [
    { "_id": "66f1a6e4698f1bca60424950", "key": "newest@example.com" },
    { "_id": "66f1a6e4698f1bca60424949", "key": "second@example.com" }
  ],
  "totalRecords": 3847
}

Use totalRecords to calculate the total number of pages: Math.ceil(totalRecords / pageSize). Then loop through pages 1 to N.

Request body reference

Field	Required	Description
`contactStructureId`	Yes	The contact structure to search within
`page`	Yes	Page number (1-indexed)
`pageSize`	Yes	Results per page
`source`	Yes	Fields to include in results: `_id`, `key`, `fields`, `tags`, `lists`, `contactStatus`, `contactSubStatus`, `createdAt`, `updatedAt`
`contactSpecification`	Yes	Object with a `filters` array of filter groups (see operators below)
`sortField`	No	Array of sort criteria
`showFieldIds`	No	Limit which field IDs appear in `fields` array

Available filter operators

Operator	Description	Example use
`EQ`	Equals	Exact email match
`NEQ`	Not equals	Exclude a specific value
`SW`	Starts with	Email prefix search
`CONTAINS`	Contains substring	Partial name match
`GT`	Greater than	Created after a date
`LT`	Less than	Created before a date
`BETWEEN`	Between two values	Date range
`NOT_BETWEEN`	Not between two values	Exclude a date range
`IS_EMPTY`	Field is empty	Find contacts with missing data
`NOT_EMPTY`	Field is not empty	Find contacts with data present
`IN`	In a set of values	Match any of several list IDs
`NIN`	Not in a set	Exclude specific values

Available filter columns

Column	Description
`KEY`	Email address
`EMAIL_DOMAIN`	Email domain (e.g., `example.com`)
`FIELD_ID`	Custom field value (requires `id` parameter with the field’s `_id`)
`TAG_ID`	Tag assignment
`LIST_ID`	List membership
`CONTACT_STATUS`	Primary status (`active`, `inactive`, etc.)
`CONTACT_SUB_STATUS`	Secondary status
`CREATED_AT`	Creation timestamp
`UPDATED_AT`	Last update timestamp

Common Errors

Status	Error	Cause	Fix
`401`	`UnauthorizedError`	Invalid or inactive API key	Verify your key in Settings > API Keys
`403`	`ForbiddenError`	Key lacks `contacts:read` scope	Search requires `contacts:read` scope
`400`	`ValidationError`	Missing required fields or invalid filter operator	Ensure `contactStructureId`, `page`, `pageSize`, `source`, and `contactSpecification` are all present
`429`	`TooManyRequestsError`	Rate limit exceeded	Wait for the `Retry-After` period. See Rate Limits

Next Steps

Manage Contacts — create, update, or delete the contacts you find
Manage Lists — organize contacts into lists
Manage Custom Fields — understand your contact structure’s field IDs
Migration from Legacy — use search for dedup during bulk import

Get Started

Scenarios

Search contacts

Search Contacts

Goal

Prerequisites

Steps

1. Search by email address

2. Search by email domain

3. Search by custom field values

4. Combine multiple criteria

5. Search within a specific list

6. Paginate through results

Request body reference

Available filter operators

Available filter columns

Common Errors

Next Steps

Get Started

Scenarios

​Search Contacts

​Goal

​Prerequisites

​Steps

​1. Search by email address

​2. Search by email domain

​3. Search by custom field values

​4. Combine multiple criteria

​5. Search within a specific list

​6. Paginate through results

​Request body reference

​Available filter operators

​Available filter columns

​Common Errors

​Next Steps

Search Contacts

Goal

Prerequisites

Steps

1. Search by email address

2. Search by email domain

3. Search by custom field values

4. Combine multiple criteria

5. Search within a specific list

6. Paginate through results

Request body reference

Available filter operators

Available filter columns

Common Errors

Next Steps