Search Contacts
POST
/v1/contacts/search
customPropertyFilters targets one property by propertyDefinitionId; the property's type (Text/Number/Select/Date) is looked up server-side and determines which value column the comparison runs against. Multiple entries are combined with AND.| Operator | Code | Behavior |
|---|---|---|
| Equals | 1 | exact match |
| NotEquals | 2 | exact mismatch |
| GreaterThan | 3 | numeric/date comparison |
| LessThan | 4 | numeric/date comparison |
| GreaterThanOrEqual | 5 | numeric/date comparison |
| LessThanOrEqual | 6 | numeric/date comparison |
| Contains | 7 | substring match — text properties only |
| IsEmpty | 8 | property has no value set |
| IsNotEmpty | 9 | property has a value set |
conversationAssigneeIds returns contacts with at least one conversation assigned to one of the given users. includeUnassignedConversations: true additionally includes contacts with at least one unassigned conversation. These two are combined with OR, not exclusively — you can't currently ask for "assigned to X and nothing else."Request
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.voxa.sa/v1/contacts/search' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Ahmed",
"customPropertyFilters": [
{
"propertyDefinitionId": "3a21f2...............",
"operator": 1,
"value": "Gold"
}
],
"skipCount": 0,
"maxResultCount": 50,
"sorting": "Name ASC"
}'Response Response Example
{
"totalCount": 1,
"items": [
{
"workspaceId": "d307b8...............",
"name": "أحمد نصحي | هاتف",
"phoneNumber": "+201063.........",
"contactType": 1,
"email": null,
"company": null,
"position": null,
"customFields": {},
"notes": [],
"customProperties": [
{
"propertyDefinitionId": "3a21f2...............",
"propertyName": "جديد",
"propertyType": 1,
"textValue": "YES",
"numberValue": null,
"dateValue": null,
"selectValue": null
},
{
"propertyDefinitionId": "3a1dbe...............",
"propertyName": "مرحلة العميل",
"propertyType": 3,
"textValue": null,
"numberValue": null,
"dateValue": null,
"selectValue": "Churn"
}
],
"lastModificationTime": "2026-06-19T13:24:53.811749",
"lastModifierId": "3a1dc2...............",
"creationTime": "2025-12-09T15:19:56.945397",
"creatorId": null,
"id": "3a1e15..............."
}
]
}Modified at 2026-06-19 14:04:15