Skip to main content
POST
https://app.cometly.com
/
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>"
  ]
}
'
{
  "id": 123,
  "emails": [
    {}
  ],
  "phones": [
    {}
  ],
  "names": [
    {}
  ],
  "locations": [
    {}
  ],
  "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: ["[email protected]", "[email protected]"]
​
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"]

​
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

​
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": ["[email protected]", "[email protected]"],
    "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.