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": {}
}
'

import requests

url = "https://app.cometly.com/public-api/v1/contacts"

payload = {
    "emails": ["<string>"],
    "phones": ["<string>"],
    "names": ["<string>"],
    "locations": ["<string>"],
    "custom_fields": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    emails: ['<string>'],
    phones: ['<string>'],
    names: ['<string>'],
    locations: ['<string>'],
    custom_fields: {}
  })
};

fetch('https://app.cometly.com/public-api/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.cometly.com/public-api/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'emails' => [
        '<string>'
    ],
    'phones' => [
        '<string>'
    ],
    'names' => [
        '<string>'
    ],
    'locations' => [
        '<string>'
    ],
    'custom_fields' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.cometly.com/public-api/v1/contacts"

	payload := strings.NewReader("{\n  \"emails\": [\n    \"<string>\"\n  ],\n  \"phones\": [\n    \"<string>\"\n  ],\n  \"names\": [\n    \"<string>\"\n  ],\n  \"locations\": [\n    \"<string>\"\n  ],\n  \"custom_fields\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.cometly.com/public-api/v1/contacts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"emails\": [\n    \"<string>\"\n  ],\n  \"phones\": [\n    \"<string>\"\n  ],\n  \"names\": [\n    \"<string>\"\n  ],\n  \"locations\": [\n    \"<string>\"\n  ],\n  \"custom_fields\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.cometly.com/public-api/v1/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"emails\": [\n    \"<string>\"\n  ],\n  \"phones\": [\n    \"<string>\"\n  ],\n  \"names\": [\n    \"<string>\"\n  ],\n  \"locations\": [\n    \"<string>\"\n  ],\n  \"custom_fields\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": 123,
  "emails": [
    {}
  ],
  "phones": [
    {}
  ],
  "names": [
    {}
  ],
  "locations": [
    {}
  ],
  "custom_fields": {},
  "message": "<string>"
}

POST

public-api

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": {}
}
'

import requests

url = "https://app.cometly.com/public-api/v1/contacts"

payload = {
    "emails": ["<string>"],
    "phones": ["<string>"],
    "names": ["<string>"],
    "locations": ["<string>"],
    "custom_fields": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    emails: ['<string>'],
    phones: ['<string>'],
    names: ['<string>'],
    locations: ['<string>'],
    custom_fields: {}
  })
};

fetch('https://app.cometly.com/public-api/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.cometly.com/public-api/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'emails' => [
        '<string>'
    ],
    'phones' => [
        '<string>'
    ],
    'names' => [
        '<string>'
    ],
    'locations' => [
        '<string>'
    ],
    'custom_fields' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.cometly.com/public-api/v1/contacts"

	payload := strings.NewReader("{\n  \"emails\": [\n    \"<string>\"\n  ],\n  \"phones\": [\n    \"<string>\"\n  ],\n  \"names\": [\n    \"<string>\"\n  ],\n  \"locations\": [\n    \"<string>\"\n  ],\n  \"custom_fields\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.cometly.com/public-api/v1/contacts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"emails\": [\n    \"<string>\"\n  ],\n  \"phones\": [\n    \"<string>\"\n  ],\n  \"names\": [\n    \"<string>\"\n  ],\n  \"locations\": [\n    \"<string>\"\n  ],\n  \"custom_fields\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.cometly.com/public-api/v1/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"emails\": [\n    \"<string>\"\n  ],\n  \"phones\": [\n    \"<string>\"\n  ],\n  \"names\": [\n    \"<string>\"\n  ],\n  \"locations\": [\n    \"<string>\"\n  ],\n  \"custom_fields\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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

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

string[]

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

string[]

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

string[]

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

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.

integer

The unique identifier of the newly created contact

array

Array of email addresses that were provided

array

Array of phone numbers that were provided

array

Array of names that were provided

array

Array of locations that were provided

object

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

Error Response

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

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
$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'];
?>

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

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.

⌘I

Getting Started

Events

Contacts

Companies

Create Contact

Overview

Request Body

Response

Success Response

Error Response

Example Requests

Status Codes

Notes

​Overview

​Request Body

​Response

​Success Response

​Error Response

​Example Requests

​Status Codes

​Notes

Overview

Request Body

Response

Success Response

Error Response

Example Requests

Status Codes

Notes