Skip to main content
GET
https://app.cometly.com
/
public-api
/
v1
/
contacts
/
{id}
Get Contact
curl --request GET \
  --url https://app.cometly.com/public-api/v1/contacts/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": 123,
  "emails": [
    {}
  ],
  "phones": [
    {}
  ],
  "names": [
    {}
  ],
  "locations": [
    {}
  ],
  "comet_tokens": [
    {}
  ],
  "message": "<string>"
}

​
Overview

This endpoint allows you to retrieve the details of a contact from Cometly. The response includes all associated emails, phones, names, and locations for the contact, including data from merged profiles.

​
Path Parameters

​
id
integer
required
The unique identifier of the contact to retrieve

​
Query Parameters

​
include_comet_tokens
boolean
default:"0"
When set to 1, includes the last 5 comet tokens associated with this contact, ordered by most recent first. Accepts 1 or 0.

​
Response

​
Success Response

Returns the contact object directly (not wrapped in a data property).
​
id
integer
The unique identifier of the contact
​
emails
array
Array of email addresses associated with this contact. Maximum 25 most recent. Ordered by most recent first.
​
phones
array
Array of phone numbers associated with this contact. Maximum 25 most recent. Ordered by most recent first.
​
names
array
Array of names associated with this contact. Maximum 25 most recent. Ordered by most recent first.
​
locations
array
Array of locations associated with this contact. Maximum 25 most recent. Ordered by most recent first.
​
comet_tokens
array
Array of comet tokens associated with this contact. Maximum 5 most recent. Ordered by most recent first. Only included when include_comet_tokens=true is specified.

​
Error Response

​
message
string
Error description explaining what went wrong

​
Example Requests

# Basic request
curl https://app.cometly.com/public-api/v1/contacts/12345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

# Include comet tokens
curl https://app.cometly.com/public-api/v1/contacts/12345?include_comet_tokens=1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

​
Status Codes

Status CodeDescription
200Contact successfully retrieved
401Missing or invalid API key
403API key doesn’t have permission or subscription is inactive
404Contact not found
422Invalid contact ID provided
429Too many requests - rate limit exceeded. See Rate Limiting

​
Notes

  • Rate Limit: This endpoint has a limit of 30 requests per minute per Space. See Rate Limiting for details.
  • Profile Merging: If a contact has been merged with another contact, requesting the old contact ID will automatically return the current (merged) contact with all associated data from both profiles.
  • Array Limits: Each array field (emails, phones, names, locations) returns a maximum of 25 most recent items to optimize performance.
  • All arrays are ordered by most recent first (descending created_at).
  • Empty arrays are returned if no data exists for a particular field.
  • Comet Tokens: Use the include_comet_tokens=1 query parameter to retrieve the last 5 comet tokens for the contact. This parameter is optional and defaults to 0.