Skip to main content
POST
/
public-api
/
v1
/
contacts
Create Contact
curl --request POST \
  --url https://app.cometly.com/public-api/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "emails": [
    "<string>"
  ],
  "phones": [
    "<string>"
  ],
  "names": [
    "<string>"
  ],
  "locations": [
    "<string>"
  ],
  "custom_fields": {}
}
'
{
  "id": 123,
  "emails": [
    {}
  ],
  "phones": [
    {}
  ],
  "names": [
    {}
  ],
  "locations": [
    {}
  ],
  "custom_fields": {},
  "message": "<string>"
}

​
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
integer
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

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

​
Status Codes

Status CodeDescription
201Contact successfully created
401Missing or invalid API key
403API key doesn’t have permission or subscription is inactive
422Invalid parameters provided (check error message for details)
429Too many requests - rate limit exceeded. See Rate Limiting

​
Notes

  • Rate Limit: This endpoint has a limit of 60 requests per minute per Space. See 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/.
  • 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.