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

# Create Contact

> Create a new contact with arrays of emails, phones, names, and locations

## Overview

This endpoint allows you to create a new contact in Cometly. You can provide multiple emails, phone numbers, names, and locations for a single contact. The first item in each array will be set as the primary value for that field in the contact's profile.

## Request Body

<ParamField body="emails" type="string[]" required placeholder="['john@example.com']">
  Array of email addresses for this contact. At least one email is required. Each email must be a valid email address.
  Example: `["john@example.com", "john.doe@example.com"]`
</ParamField>

<ParamField body="phones" type="string[]" placeholder="['+1234567890']">
  Array of phone numbers for this contact. Optional.
  Example: `["+1234567890", "+0987654321"]`
</ParamField>

<ParamField body="names" type="string[]" placeholder="['John Doe']">
  Array of names for this contact. Optional.
  Example: `["John Doe", "Johnny"]`
</ParamField>

<ParamField body="locations" type="string[]" placeholder="['New York, NY']">
  Array of locations for this contact. Optional.
  Example: `["New York, NY", "Los Angeles, CA"]`
</ParamField>

<ParamField body="custom_fields" type="object">
  Object of custom profile field values keyed by field slug (`profile_field_1` through `profile_field_30`). Optional.
  Fields 1-15 accept text, 16-25 accept numbers, 26-30 accept dates.
  Example: `{"profile_field_1": "Enterprise", "profile_field_16": "500"}`
</ParamField>

## Response

### Success Response

Returns the created contact with all provided data in the ContactDetail format.

<ResponseField name="id" type="integer">
  The unique identifier of the newly created contact
</ResponseField>

<ResponseField name="emails" type="array">
  Array of email addresses that were provided
</ResponseField>

<ResponseField name="phones" type="array">
  Array of phone numbers that were provided
</ResponseField>

<ResponseField name="names" type="array">
  Array of names that were provided
</ResponseField>

<ResponseField name="locations" type="array">
  Array of locations that were provided
</ResponseField>

<ResponseField name="custom_fields" type="object">
  Object containing the custom profile fields that were provided. Only included if custom fields were passed in the request.
</ResponseField>

### Error Response

<ResponseField name="message" type="string">
  Error description explaining what went wrong
</ResponseField>

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.cometly.com/public-api/v1/contacts" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "emails": ["john@example.com", "john.doe@example.com"],
      "phones": ["+1234567890", "+0987654321"],
      "names": ["John Doe", "Johnny"],
      "locations": ["New York, NY", "Los Angeles, CA"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.cometly.com/public-api/v1/contacts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      emails: ['john@example.com', 'john.doe@example.com'],
      phones: ['+1234567890', '+0987654321'],
      names: ['John Doe', 'Johnny'],
      locations: ['New York, NY', 'Los Angeles, CA']
    })
  });

  const data = await response.json();
  console.log('Created contact ID:', data.id);
  ```

  ```php PHP theme={null}
  <?php
  $url = 'https://app.cometly.com/public-api/v1/contacts';
  $headers = [
      'Authorization: Bearer YOUR_API_KEY',
      'Accept: application/json',
      'Content-Type: application/json'
  ];

  $data = [
      'emails' => ['john@example.com', 'john.doe@example.com'],
      'phones' => ['+1234567890', '+0987654321'],
      'names' => ['John Doe', 'Johnny'],
      'locations' => ['New York, NY', 'Los Angeles, CA']
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  $result = json_decode($response, true);
  curl_close($ch);

  echo 'Created contact ID: ' . $result['id'];
  ?>
  ```

  ```python Python theme={null}
  import requests

  url = 'https://app.cometly.com/public-api/v1/contacts'
  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json',
      'Content-Type': 'application/json'
  }

  data = {
      'emails': ['john@example.com', 'john.doe@example.com'],
      'phones': ['+1234567890', '+0987654321'],
      'names': ['John Doe', 'Johnny'],
      'locations': ['New York, NY', 'Los Angeles, CA']
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(f"Created contact ID: {result['id']}")
  ```
</CodeGroup>

## Status Codes

| Status Code | Description                                                                               |
| ----------- | ----------------------------------------------------------------------------------------- |
| 201         | Contact successfully created                                                              |
| 401         | Missing or invalid API key                                                                |
| 403         | API key doesn't have permission or subscription is inactive                               |
| 422         | Invalid parameters provided (check error message for details)                             |
| 429         | Too many requests - rate limit exceeded. See [Rate Limiting](/introduction/rate-limiting) |

## Notes

* **Rate Limit**: This endpoint has a limit of **60 requests per minute** per Space. See [Rate Limiting](/introduction/rate-limiting) for details.
* **Required Field**: At least one email address is required. All other fields are optional.
* **Multiple Values**: You can provide multiple emails, phones, names, and locations for a single contact.
* **Primary Data**: The first item in each array becomes the primary value stored in the contact's profile.
* **All Data Stored**: All items from each array are stored in their respective tables (emails, phones, names, locations) and can be retrieved via GET /contacts/{id}.
* **Transaction Safety**: Contact creation is wrapped in a database transaction to ensure data consistency.
* **Custom Fields**: You can optionally pass a `custom_fields` object with keys `profile_field_1` through `profile_field_30`. Fields 1-15 are text (max 10,240 chars), 16-25 are numeric, 26-30 are dates. Invalid keys are rejected with a 422 error.