> ## 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.

# Get Contact

> Retrieve details of a specific contact by its ID

## 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** `string`

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

```bash cURL theme={null}
# 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"
```

```javascript JavaScript theme={null}
const contactId = 12345;

// Basic request
const response = await fetch(`https://app.cometly.com/public-api/v1/contacts/${contactId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

// Include comet tokens
const responseWithTokens = await fetch(`https://app.cometly.com/public-api/v1/contacts/${contactId}?include_comet_tokens=1`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

const dataWithTokens = await responseWithTokens.json();
```

```php PHP theme={null}
<?php
$contactId = 12345;
$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Accept: application/json',
    'Content-Type: application/json'
];

// Basic request
$url = 'https://app.cometly.com/public-api/v1/contacts/' . $contactId;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

// Include comet tokens
$urlWithTokens = 'https://app.cometly.com/public-api/v1/contacts/' . $contactId . '?include_comet_tokens=1';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $urlWithTokens);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$responseWithTokens = curl_exec($ch);
curl_close($ch);
?>
```

```python Python theme={null}
import requests

contact_id = 12345
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

# Basic request
url = f'https://app.cometly.com/public-api/v1/contacts/{contact_id}'
response = requests.get(url, headers=headers)

# Include comet tokens
url_with_tokens = f'https://app.cometly.com/public-api/v1/contacts/{contact_id}'
params = {'include_comet_tokens': 1}
response_with_tokens = requests.get(url_with_tokens, headers=headers, params=params)
```

## Status Codes

| Status Code | Description |
| - | - |
| 200 | Contact successfully retrieved |
| 401 | Missing or invalid API key |
| 403 | API key doesn't have permission or subscription is inactive |
| 404 | Contact not found |
| 422 | Invalid contact ID provided |
| 429 | Too many requests - rate limit exceeded. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) |

## Notes

* **Rate Limit**: This endpoint has a limit of **30 requests per minute** per Space. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.