Search Contacts

Search for contacts using flexible MongoDB-style filter conditions.

Use Cases:

• Find contacts matching specific criteria
• Build custom contact reports
• Test segment conditions before creating segments
• Filter contacts for targeted operations
• Query contacts by custom property values

Behavior:

• Uses MongoDB query syntax for powerful filtering
• Returns paginated results with cursor-based pagination
• Supports complex nested conditions ($and, $or, $not)
• Can filter on any contact property (default or custom)
• Maximum 100 contacts per request
• Results are sorted by createdAt (newest first)

Required Scope: read:contacts

Supported Operators:

• Comparison: $eq, $ne, $gt, $gte, $lt, $lte
• Arrays: $in, $nin
• Logical: $and, $or, $not
• Existence: $exists (check if property is set)
• Text: $regex (pattern matching)

Example Queries:

Find US contacts with high value:

{
  "$and": [
    { "country": { "$eq": "US" } },
    { "lifetime_value": { "$gte": 1000 } }
  ]
}

Find engaged subscribers:

{
  "$and": [
    { "subscribed": { "$eq": true } },
    { "last_opened_at": { "$gte": "2024-01-01" } }
  ]
}

Find contacts missing a property:

{
  "company": { "$exists": false }
}

Best Practices:

• Test complex conditions here before creating segments
• Use indexed properties for better performance
• Keep conditions simple when possible
• Combine with pagination for large result sets