> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Collection Endpoint

> Reference for the HTTPS-based data collection endpoint used to ingest identifiers and custom data into Narrative

The Narrative data collection endpoint is an HTTPS-based integration point that enables partners to send identifiers and arbitrary data to Narrative by passing key-value pairs as query parameters. Data sent to this endpoint is ingested into a Narrative dataset.

## Overview

The data collection endpoint supports two primary use cases:

* **Cookie syncing:** Share browser-based identifiers between domains to create a shared understanding of user identity across separate cookie namespaces.
* **Custom data collection:** Send arbitrary key-value pairs alongside identifiers, which are ingested into a Narrative dataset for downstream use.

Both use cases work through the same endpoint and share the same base parameters.

## Endpoint

```
//io.narrative.io/?
```

## Query parameters

### Required parameters

| Parameter   | Required | Description                                                                                                                                    |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyId` | Yes      | Unique ID assigned to the partner by Narrative                                                                                                 |
| `id`        | Yes      | Type and value of the identifier, formatted as `partner_id_type:partner_id_value`. The `partner_id_type` is assigned to partners by Narrative. |

### Optional parameters

| Parameter | Required | Description                                                                                                 |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `red`     | No       | URL-encoded redirect URL. If provided, Narrative redirects back to this URL with the Narrative ID appended. |

### Custom parameters

Any additional query parameters beyond `companyId`, `id`, and `red` are ingested as custom key-value pairs into the partner's Narrative dataset. This allows partners to enrich each request with arbitrary metadata without requiring changes to the endpoint schema.

Custom parameter values are ingested as strings. Use descriptive, consistent key names across requests.

## Macros

When using the redirect parameter, you can include macros that Narrative replaces with actual values:

| Macro                   | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| `${narrative.id.value}` | Replaced with the Narrative cookie identifier on redirect |

## Examples

### Basic cookie sync

A partner called BrandA wants to sync their customer identifier with Narrative.

**Given:**

* Company ID: `789`
* Customer ID: `123456789`
* Partner ID type (assigned by Narrative): `brandA_id`

**Template:**

```
//io.narrative.io/?companyId=XXX&id=partner_id_type:[[partner_id_value]]
```

**Implemented:**

```
//io.narrative.io/?companyId=789&id=brandA_id:123456789
```

### Cookie sync with redirect

To receive the Narrative identifier back, include a URL-encoded redirect URL with the macro:

```
//io.narrative.io/?companyId=789&id=brandA_id:123456789&red=https%3A%2F%2Fexample.com%2F%3Fnarrative_id%3D%24%7Bnarrative.id.value%7D
```

When decoded, the redirect URL is:

```
https://example.com/?narrative_id=${narrative.id.value}
```

Narrative replaces `${narrative.id.value}` with the actual Narrative cookie identifier before redirecting.

### Custom data collection

Partners can include additional query parameters to send custom data alongside the identifier. These key-value pairs are ingested into the partner's Narrative dataset.

**Given:**

* Company ID: `789`
* Customer ID: `123456789`
* Partner ID type: `brandA_id`
* Custom data: page category, campaign ID

**Implemented:**

```
//io.narrative.io/?companyId=789&id=brandA_id:123456789&page_category=electronics&campaign_id=summer2025
```

In this example, `page_category` and `campaign_id` are ingested as custom attributes in the partner's dataset alongside the standard identifier data.

## Related content

<CardGroup cols={2}>
  <Card title="Glossary" icon="book-bookmark" href="/reference/glossary">
    Definitions for cookie syncing, data collection, and other terms
  </Card>
</CardGroup>