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

# Create a Contact — Shilo API Reference

> Create a new contact in Shilo with name, email, phone, and your external contact ID for cross-system linking. Requires a write-enabled API key.

Use this endpoint to add a new contact to your Shilo organization. You must supply `external_contact_id`, `name`, `first_name`, and `last_name`. The `external_contact_id` links the Shilo contact record back to your CRM or data source. All other fields are optional and can be populated now or updated later. This endpoint requires a **write-enabled** API key — read-only keys will receive a `403` response.

## Endpoint

```text theme={null}
POST https://api.shilo.ai/api/v1/contacts
```

## Authentication

Include your write-enabled API key in the request header:

```text theme={null}
x-api-key: YOUR_API_KEY
```

## Request Body

<ParamField body="external_contact_id" type="string" required>
  Your system's unique identifier for this contact. Used to correlate the Shilo record with your CRM or external data source.
</ParamField>

<ParamField body="name" type="string" required>
  Full display name of the contact (e.g. `"Jamie Customer"`).
</ParamField>

<ParamField body="first_name" type="string" required>
  Contact's first name.
</ParamField>

<ParamField body="last_name" type="string" required>
  Contact's last name.
</ParamField>

<ParamField body="phone" type="string">
  Primary phone number for the contact. Any standard formatting is accepted.
</ParamField>

<ParamField body="emails" type="string[]">
  One or more email addresses to associate with this contact.
</ParamField>

<ParamField body="stage" type="string">
  Human-readable label for the contact's current pipeline stage (e.g. `"Negotiation"`).
</ParamField>

<ParamField body="stage_id" type="string">
  Your system's ID for the pipeline stage. Useful for programmatic stage filtering later.
</ParamField>

<ParamField body="source" type="string">
  Human-readable label for the contact's lead source (e.g. `"Zillow"`).
</ParamField>

<ParamField body="source_id" type="string">
  Your system's ID for the lead source.
</ParamField>

<ParamField body="tags" type="string[]">
  An array of tag labels to apply to the contact for segmentation and filtering.
</ParamField>

## Response

A successful request returns HTTP `201` with the newly created Contact object.

### Response Fields

<ResponseField name="id" type="string">
  The Shilo-assigned UUID for the newly created contact.
</ResponseField>

<ResponseField name="external_contact_id" type="string">
  The external ID you supplied at creation.
</ResponseField>

<ResponseField name="name" type="string">
  Full display name of the contact.
</ResponseField>

<ResponseField name="first_name" type="string">
  Contact's first name.
</ResponseField>

<ResponseField name="last_name" type="string">
  Contact's last name.
</ResponseField>

<ResponseField name="phone" type="string">
  Primary phone number.
</ResponseField>

<ResponseField name="emails" type="array of strings">
  Email addresses associated with the contact.
</ResponseField>

<ResponseField name="stage" type="string">
  Pipeline stage label.
</ResponseField>

<ResponseField name="stage_id" type="string">
  Pipeline stage ID from your system.
</ResponseField>

<ResponseField name="source" type="string">
  Lead source label.
</ResponseField>

<ResponseField name="source_id" type="string">
  Lead source ID from your system.
</ResponseField>

<ResponseField name="tags" type="array of strings">
  Tags applied to the contact.
</ResponseField>

<ResponseField name="created_date" type="string">
  ISO-8601 timestamp indicating when this contact was created in Shilo.
</ResponseField>

### Example Response

```json theme={null}
{
  "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "external_contact_id": "4534",
  "name": "Jamie Customer",
  "first_name": "Jamie",
  "last_name": "Customer",
  "phone": "(555) 555-9999",
  "emails": ["jamie@example.com"],
  "stage": "Negotiation",
  "stage_id": "stage-99",
  "source": "Zillow",
  "source_id": "src-7",
  "tags": ["hot-lead", "q4"],
  "created_date": "2024-09-01T10:00:00Z"
}
```

## Error Codes

| Status | Meaning                                                         |
| ------ | --------------------------------------------------------------- |
| `400`  | Invalid request body — check required fields and value formats. |
| `403`  | Your API key is read-only. A write-enabled key is required.     |

## Example Request

```bash theme={null}
curl -X POST "https://api.shilo.ai/api/v1/contacts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_contact_id": "4534",
    "name": "Jamie Customer",
    "first_name": "Jamie",
    "last_name": "Customer",
    "phone": "(555) 555-9999",
    "emails": ["jamie@example.com"],
    "stage": "Negotiation",
    "stage_id": "stage-99",
    "source": "Zillow",
    "source_id": "src-7",
    "tags": ["hot-lead", "q4"]
  }'
```