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

# Create Contact

> Create or update a contact from structured data — no AI extraction.

`POST …/contacts/create`

Use this endpoint when your data is already clean and structured. No AI extraction is performed — fields are mapped directly to the contact record.

This endpoint is **asynchronous**. It enqueues the work and returns immediately.

Also accessible at `POST …/contacts` (same behavior).

***

## Request

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

```json theme={null}
{
  "full_name": "John Doe",
  "phone_number": "5550000001",
  "contact_email": "john.doe@example.com",
  "contact_address": "123 Main St, Springfield, USA 00000",
  "tags": ["motivated-seller"],
  "source": "Airtable Import",
  "contributors": ["Sarah Smith"]
}
```

***

## Body fields

| Field             | Type      | Required | Description                                       |
| ----------------- | --------- | -------- | ------------------------------------------------- |
| `full_name`       | string    | No\*     | Contact's full name                               |
| `phone_number`    | string    | No\*     | Contact's phone number                            |
| `contact_email`   | string    | No\*     | Contact's email address                           |
| `contact_address` | string    | No       | Contact's address — linked to a property if found |
| `note`            | string    | No       | Creates a note on the contact                     |
| `tags`            | string\[] | No       | Applied to the contact after creation             |
| `source`          | string    | No       | Defaults to `Webhook` if omitted                  |
| `contributors`    | string\[] | No       | Full names of org users to assign as contributors |

<Warning>
  At least one of `full_name`, `phone_number`, or `contact_email` is required. If none are provided the request is accepted (`200`) but no contact is created. Validation happens in the async worker, not at the HTTP layer.
</Warning>

<Note>
  `first_name` and `last_name` are supported but deprecated. Use `full_name` instead.
</Note>

***

## Deduplication

Goliath deduplicates contacts on ingest using one of two strategies:

* **Name + phone or email** — when a name is present alongside a phone or email
* **Phone or email only** — when no name is provided

If a match is found, the existing contact is updated rather than a new one being created.

***

## Responses

**New event**

```json theme={null}
200 OK

{
  "success": true,
  "acknowledged": true,
  "eventId": "a1b2c3d4-0000-0000-0000-000000000000"
}
```

**Duplicate event**

```json theme={null}
200 OK

{
  "success": true,
  "acknowledged": true
}
```

<Note>
  A `200` response means the request was accepted and queued — not that the contact exists yet. Duplicate events return `200` without an `eventId`.
</Note>