> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Contact

> Search for contacts in Goliath by name, phone, or email.

`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

```bash theme={null}
POST {WEBHOOK_BASE_URL}/{token}/contacts/find
Content-Type: application/json
```

```json theme={null}
{
  "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`. |

<Warning>
  At least one of `full_name`, `phone_number`, or `contact_email` is required. Providing none returns `400`.
</Warning>

***

## 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:

1. Name only
2. Phone only
3. Email only

Results from the first successful fallback are returned.

<Note>
  `match_any` also accepts the string `"true"` (case-insensitive) for integrations that serialize booleans as strings.
</Note>

***

## Response

```json theme={null}
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" }
    ]
  }
]
```

Returns an empty array `[]` 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                                             |