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

<ParamField path="id" type="integer" required>
  The unique identifier of the contact to retrieve
</ParamField>

## Query Parameters

<ParamField query="include_comet_tokens" type="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`.
</ParamField>

<ParamField query="include_events" type="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`.
</ParamField>

<ParamField query="hide_direct_touchpoints" type="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`.
</ParamField>

<ParamField query="use_custom_field_labels" type="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`.
</ParamField>

<ParamField query="include_browsing_session_data" type="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`.
</ParamField>

## Response

### Success Response

Returns the contact object directly (not wrapped in a `data` property).

<ResponseField name="id" type="integer">
  The unique identifier of the contact
</ResponseField>

<ResponseField name="emails" type="array">
  Array of email addresses associated with this contact. Maximum 25 most recent. Ordered by most recent first.
</ResponseField>

<ResponseField name="phones" type="array">
  Array of phone numbers associated with this contact. Maximum 25 most recent. Ordered by most recent first.
</ResponseField>

<ResponseField name="names" type="array">
  Array of names associated with this contact. Maximum 25 most recent. Ordered by most recent first.
</ResponseField>

<ResponseField name="locations" type="array">
  Array of locations associated with this contact. Maximum 25 most recent. Ordered by most recent first.
</ResponseField>

<ResponseField name="comet_tokens" type="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.
</ResponseField>

<ResponseField name="events" type="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.
</ResponseField>

<ResponseField name="custom_fields" type="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.
</ResponseField>

<ResponseField name="browsing_session_hits" type="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`.
</ResponseField>

### Error Response

<ResponseField name="message" type="string">
  Error description explaining what went wrong
</ResponseField>

## Example Requests

<CodeGroup>
  ```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)
  ```
</CodeGroup>

## 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](/introduction/rate-limiting) |

## Notes

* **Rate Limit**: This endpoint has a limit of **30 requests per minute** per Space. See [Rate Limiting](/introduction/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.