Skip to main content
GET
/
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": [
    {}
  ],
  "events": [
    {}
  ],
  "custom_fields": {},
  "browsing_session_hits": [
    {}
  ],
  "message": "<string>"
}

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.

​
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.
​
include_events
boolean
default:"0"
When set to 1, includes the contact’s full event journey — all conversions and touchpoints sorted by most recent first. Each event includes type (conversion or touchpoint), timestamps, URLs, and for touchpoints the full ad hierarchy (ad, ad set, campaign, account). Accepts 1 or 0.
​
hide_direct_touchpoints
boolean
default:"1"
When set to 1 (default), direct touchpoints are excluded from the events list. Set to 0 to include them. Only applies when include_events=1. Accepts 1 or 0.
​
use_custom_field_labels
boolean
default:"0"
When set to 1, custom field keys in the custom_fields object will use the user-defined labels (e.g. "Customer Age") instead of the raw column names (e.g. "profile_field_1"). Fields without a configured label will keep their raw column name. Accepts 1 or 0.
​
include_browsing_session_data
boolean
default:"0"
When set to 1, includes up to the last 1000 raw browsing session hits (page views) for 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.
​
events
array
Array of the contact’s conversions and touchpoints, sorted by most recent first. Only included when include_events=1 is specified. Each object has a type field (conversion or touchpoint) and type-specific fields — see Notes for details.
​
custom_fields
object
Object containing all 30 custom fields. Fields 1-15 are text (string|null), 16-25 are numeric (number|null), 26-30 are date (string|null). Always included in the response.
​
browsing_session_hits
array
Array of raw browsing session hits (page views) for this contact, ordered by most recent first. Capped at 1000 hits. Only included when include_browsing_session_data=1 is specified. Each hit includes event_url (full URL — host, path, and query string combined), referrer_host, source, country, device_type, browser, os, event_name, and event_time_utc.

​
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.
  • Custom Fields: The response always includes a custom_fields object with all 30 custom fields. Fields 1-15 are text, 16-25 are numeric, 26-30 are date. Fields that have not been set will be null.
  • Custom Field Labels: Use use_custom_field_labels=1 to replace raw column names (profile_field_1) with user-defined labels (e.g. Customer Age) in the custom_fields object. Fields without a configured label will retain their raw column name.
  • Events: Use include_events=1 to retrieve the contact’s full event journey. Events are sorted by most recent first and include both conversions and touchpoints:
    • Conversion fields: type ("conversion"), id, event_name, amount, event_time_utc, event_url, order_id, order_name, channel ("browser" or "server"), and integration (only for server-side events, e.g. "Shopify", "Stripe")
    • Touchpoint fields: type ("touchpoint"), event_time_utc, source, touchpoint_url, referrer_url, ad_id, ad_name, adset_id, adset_name, campaign_id, campaign_name, account_id, account_name
    • Ad hierarchy fields (ad_id, ad_name, etc.) are resolved from the attributed ad and will be null for touchpoints without ad data (e.g. organic or direct).
    • Direct touchpoints are hidden by default. Use hide_direct_touchpoints=0 to include them.
  • Browsing Session Hits: Use include_browsing_session_data=1 to retrieve up to the last 1000 raw browsing hits for the contact, ordered most recent first. Each hit contains event_url (the full URL — host, path, and query string combined), referrer_host, source, country, device_type, browser, os, event_name, and event_time_utc. This is raw hit data, not grouped into sessions — group client-side if needed.