Filtering contacts

The contacts endpoints accept a structured where object that lets you filter your network by almost any attribute — tags, groups, company, activity dates, custom fields, and more. This page documents every key the where DSL accepts, the value shapes each one takes, and how conditions combine.

Which endpoints use where

How where works

where is a flat object. Every top-level key is combined with logical AND — a contact must satisfy all of them to be returned. To express OR, use the _or key.

{
  "where": {
    "has_company": "acme",
    "is_starred": true
  }
}

Returns starred contacts whose company contains "acme".

Value-shape conventions

Most keys accept more than one value shape. The shape you pass changes what the key means:

All dates are ISO 8601 datetimes, e.g. "2026-01-31T00:00:00Z". All ids are UUIDs.

Filter keys

Identity & flags

Names & text profile fields

Text fields accept a bare string (fuzzy contains), an explicit { contains } / { eq } matcher, or a boolean presence check. has_name additionally accepts a string array for an exact multi-value match.

Each text field has a negated twin that excludes contacts whose value contains the given string(s):

Contact info & birthday presence

Social handles

Bare strings match the social slug exactly; booleans check presence.

Tags

has_tags_all is how you express "tagged A and B". Each inner array is an OR group; the outer array ANDs the groups together:

{ "has_tags_all": [ ["tagA"], ["tagB", "tagC"] ] }

Has tag A and (tag B or tag C).

Groups

Source, priority & cadence

Activity & date ranges

Each of these accepts a { gte, lte } ISO datetime range (supply at least one bound). The has_last_seen_at, has_interaction, has_next_reminder, and has_linkedin_last_message_at keys also accept a boolean presence check.

Geographic distance

Custom fields

custom_fields filters by your user-defined fields without inflating the schema with one key per field. It takes an array of clauses (at least one); each clause is { field_id, operator, value? } and all clauses AND together.

{
  "custom_fields": [
    { "field_id": "…", "operator": "eq", "value": "VIP" },
    { "field_id": "…", "operator": "present" }
  ]
}

field_id is the id of the custom field — fetch it from the custom fields endpoints.

Compound OR

By default every top-level key is ANDed. Use _or when you genuinely need (A AND B) OR (C AND D). It takes an array of filter sets (at least one), and a contact matches if it satisfies any branch. Each branch is a full filter set, but _or cannot nest inside a branch — one level deep only. Deeper logic can always be flattened to distributive form: (A OR B) AND C becomes _or: [ {A, C}, {B, C} ].

{
  "where": {
    "_or": [
      { "is_starred": true },
      { "has_tags": ["…tag-id…"] }
    ]
  }
}

Starred or tagged with the given tag.

Examples

All examples authenticate with an API key as a Bearer token. See Authentication for where to find your key. The base URL is https://api.prod.getdex.com.

Tag AND-composition

Contacts that have (tag A or tag B) and tag C:

curl https://api.prod.getdex.com/v1/contacts/filter \
  --request POST \
  --header 'Authorization: Bearer dex_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "where": {
      "has_tags_all": [
        ["11111111-1111-1111-1111-111111111111", "22222222-2222-2222-2222-222222222222"],
        ["33333333-3333-3333-3333-333333333333"]
      ]
    },
    "take": 100
  }'

Company + last-seen date range

Contacts at a company matching "acme" whom you last interacted with in H1 2026:

curl https://api.prod.getdex.com/v1/contacts/filter \
  --request POST \
  --header 'Authorization: Bearer dex_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "where": {
      "has_company": { "contains": "acme" },
      "has_last_seen_at": {
        "gte": "2026-01-01T00:00:00Z",
        "lte": "2026-06-30T23:59:59Z"
      }
    }
  }'

Custom-field filter

Contacts whose "Tier" custom field equals "VIP" and whose "Renewal" date is on or after Jan 1 2026:

curl https://api.prod.getdex.com/v1/contacts/filter \
  --request POST \
  --header 'Authorization: Bearer dex_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "where": {
      "custom_fields": [
        { "field_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "operator": "eq", "value": "VIP" },
        { "field_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "operator": "gte", "value": "2026-01-01T00:00:00Z" }
      ]
    }
  }'

Compound OR

Contacts that are starred or are in a given group and have an email on file:

curl https://api.prod.getdex.com/v1/contacts/filter \
  --request POST \
  --header 'Authorization: Bearer dex_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "where": {
      "_or": [
        { "is_starred": true },
        {
          "has_groups": ["44444444-4444-4444-4444-444444444444"],
          "has_email": true
        }
      ]
    }
  }'

Response

The filter and list endpoints return the standard envelope with a data.items array, a data.count, and a data.nextCursor for pagination:

{
  "error": false,
  "data": {
    "items": [ { "id": "…", "full_name": "…" } ],
    "count": 1,
    "nextCursor": null
  }
}

For the full response shape and all available fields, see the endpoint reference: Filter contacts (v1) · List contacts (v2).