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

**emails** `string[]` *required*

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"]`

**phones** `string[]`

Array of phone numbers for this contact. Optional.
Example: `["+1234567890", "+0987654321"]`

**names** `string[]`

Array of names for this contact. Optional.
Example: `["John Doe", "Johnny"]`

**locations** `string[]`

Array of locations for this contact. Optional.
Example: `["New York, NY", "Los Angeles, CA"]`

**custom\_fields** `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"}`

## Response

### Success Response

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

**id** `string`

The unique identifier of the newly created contact

**emails** `array`

Array of email addresses that were provided

**phones** `array`

Array of phone numbers that were provided

**names** `array`

Array of names that were provided

**locations** `array`

Array of locations that were provided

**custom\_fields** `object`

Object containing the custom profile fields that were provided. Only included if custom fields were passed in the request.

### Error Response

**message** `string`

Error description explaining what went wrong

## Example Requests

```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']}")
```

## 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](https://docs.cometly.com/introduction/rate-limiting.md) |

## Notes

* **Rate Limit**: This endpoint has a limit of **60 requests per minute** per Space. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.