Skip to main content
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

ParameterRequiredDescription
companyIdYesUnique ID assigned to the partner by Narrative
idYesType 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

ParameterRequiredDescription
redNoURL-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:
MacroDescription
${narrative.id.value}Replaced with the Narrative cookie identifier on redirect

​
Examples

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

Glossary

Definitions for cookie syncing, data collection, and other terms