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

# Create Contact

> Create a new CRM contact

## Headers

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY`
</ParamField>

<ParamField header="X-Project-ID" type="string">
  Your project UUID. Not required if the API key already encodes the project.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
  Full name of the contact
</ParamField>

<ParamField body="email" type="string" required>
  Email address — must be unique within the project
</ParamField>

<ParamField body="phone" type="string">Phone number</ParamField>
<ParamField body="mobile" type="string">Mobile number</ParamField>
<ParamField body="company" type="string">Company or organisation name</ParamField>

<ParamField body="status" type="string" default="new">
  `new` · `active` · `inactive` · `archived`
</ParamField>

<ParamField body="notes" type="string">Internal notes visible only to your team</ParamField>
<ParamField body="first_name" type="string">First name (stored separately from `name`)</ParamField>
<ParamField body="last_name" type="string">Last name</ParamField>
<ParamField body="address_line_1" type="string">Street address line 1</ParamField>
<ParamField body="address_line_2" type="string">Street address line 2</ParamField>
<ParamField body="city" type="string">City</ParamField>
<ParamField body="state" type="string">State or province</ParamField>
<ParamField body="zip" type="string">Postal / ZIP code</ParamField>
<ParamField body="country" type="string">Country</ParamField>

<ParamField body="custom_fields" type="object">
  Arbitrary key-value pairs (e.g. `{ "plan": "pro", "source": "webinar" }`)
</ParamField>

<ParamField body="tags" type="string[]">
  Tag names to attach on creation. Tags are created automatically if they don't exist.
</ParamField>

<ParamField body="external_id" type="string">
  Your own identifier for this contact (e.g. a user ID from your database)
</ParamField>

## Response

Returns the created contact object.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.usegately.com/api/v1/contacts" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "X-Project-ID: YOUR_PROJECT_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Jane Smith",
      "email": "jane@example.com",
      "company": "Acme Corp",
      "status": "active",
      "tags": ["VIP", "Newsletter"],
      "custom_fields": { "plan": "pro" }
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://api.usegately.com/api/v1/contacts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'X-Project-ID': 'YOUR_PROJECT_ID',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Jane Smith',
      email: 'jane@example.com',
      company: 'Acme Corp',
      status: 'active',
      tags: ['VIP', 'Newsletter'],
      custom_fields: { plan: 'pro' },
    }),
  })
  const contact = await res.json()
  ```

  ```typescript SDK theme={null}
  import { GatelyContacts } from '@gately/sdk'

  const crm = new GatelyContacts({ projectId: 'YOUR_PROJECT_ID' })

  const contact = await crm.create({
    name: 'Jane Smith',
    email: 'jane@example.com',
    company: 'Acme Corp',
    status: 'active',
    tags: ['VIP', 'Newsletter'],
    custom_fields: { plan: 'pro', source: 'webinar' },
  })
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "project_id": "proj-uuid-here",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "company": "Acme Corp",
    "status": "active",
    "custom_fields": { "plan": "pro", "source": "webinar" },
    "unsubscribed": false,
    "created_at": "2025-06-01T10:00:00.000Z",
    "updated_at": "2025-06-01T10:00:00.000Z"
  }
  ```

  ```json Duplicate email theme={null}
  {
    "error": "A contact with this email already exists"
  }
  ```
</ResponseExample>