POST …/contacts/find
Synchronously search for contacts within your organization. Returns a list of matching contacts with their contact details and contributors.
This endpoint is synchronous — results are returned inline in the response.
Request
POST {WEBHOOK_BASE_URL}/{token}/contacts/find
Content-Type: application/json
{
"full_name": "John Doe",
"phone_number": "5550000001",
"contact_email": "john.doe@example.com",
"match_any": false
}
Body fields
| Field | Type | Required | Description |
|---|
full_name | string | No* | Contact name to search |
phone_number | string | No* | Phone number to search |
contact_email | string | No* | Email address to search |
match_any | boolean | No | If true, falls back to individual field searches when no strict match is found. Defaults to false. |
At least one of full_name, phone_number, or contact_email is required. Providing none returns 400.
Matching logic
By default, Goliath uses strict matching — all provided fields must match the same contact.
If match_any: true is set and strict matching returns no results, Goliath falls back to searching each field individually:
- Name only
- Phone only
- Email only
Results from the first successful fallback are returned.
match_any also accepts the string "true" (case-insensitive) for integrations that serialize booleans as strings.
Response
200 OK
[
{
"id": "a1b2c3d4-0000-0000-0000-000000000000",
"name": "John Doe",
"phones": ["5550000001"],
"emails": ["john.doe@example.com"],
"addresses": ["123 Main St, Springfield, USA 00000"],
"contributors": [
{ "id": "user-uuid", "name": "Sarah Smith" }
],
"tags": [
{ "text": "Motivated Seller", "value": "motivated-seller" }
]
}
]
[] if no contacts match.
Error responses
| Status | Cause |
|---|
400 | None of full_name, phone_number, or contact_email were provided |
401 | Invalid or inactive token |
