Kochava IdentityLink

Send identity graph data to Kochava IdentityLink server-to-server for cross-device identity resolution and audience linking.

⚠️

This blueprint is currently alpha — schema and behaviour may change before GA.

Prerequisites

Complete these steps in the Kochava dashboard before configuring Signal. IdentityLink is an add-on feature that must be enabled on your Kochava account.

Create a Kochava account

Sign up at kochava.com and log in to the Kochava dashboard. If you already have a Kochava account, log in with your existing credentials.

Enable IdentityLink

Contact your Kochava account manager or submit a request through the Kochava dashboard to enable the IdentityLink feature on your account. This feature is not available by default and requires activation.

Register your app

If you have not already done so, click Add App in the dashboard and register the app you want to link identities for. Note the App GUID from the app’s settings page.

Find your API key

Navigate to Account Settings > API Keys or the app’s Settings > API Credentials. Copy your API Key. This authenticates IdentityLink API calls.

Obtain your Partner ID

Your Kochava account manager will assign a Partner ID for your IdentityLink integration. This ID identifies your organisation within the IdentityLink identity graph. Request it directly from your account manager if you do not have it.

Define identity mapping strategy

Work with your Kochava account manager to define which identity types you will link (e.g. email hashes, device IDs, customer IDs). This determines the fields your blueprint needs to map.

Configuration

Field	Type	Required	Description
`app_guid`	string	Yes	The Kochava App GUID associated with the IdentityLink integration.
`api_key`	secret	Yes	The Kochava API key for authenticating IdentityLink API calls.
`partner_id`	string	Yes	Your Kochava Partner ID assigned for IdentityLink.

Signal Setup

Quick Setup

Navigate to Integrations in the sidebar.
Open the Integration Library tab.
Find Kochava IdentityLink or filter by Attribution.
Click Install, select a variant if available, and fill in the required fields.
Click Install Integration to create the integration with a ready-to-use default blueprint.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/kochava_identitylink/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kochava IdentityLink",
    "variant": "default",
    "config": {
      "app_guid": "koexample-app-guid-1234",
      "api_key": "your_api_key",
      "partner_id": "partner-abc-123"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

The Retail variant maps the following Datafly events to IdentityLink calls:

Datafly Event	IdentityLink Event	Notes
`Product Added`	`add_to_cart`	Carries identity payload alongside cart-stage event
`Order Completed`	`purchase`	Carries identity payload alongside purchase event
Custom events	Passed through	Add the IdentityLink event type in the blueprint event map

Identity

The default blueprint forwards the following identifiers to Kochava IdentityLink:

Source	IdentityLink field
`user_id`	`customer_id`
`context.ip`	`ip_address`
`context.user_agent`	`user_agent`

IdentityLink works by linking multiple identifier types for the same user. Pass hashed email and device identifiers as event properties so Kochava can extend the identity graph.

Default consent category: advertising.

IdentityLink works by associating multiple identifiers for the same user. Ensure your events include at least two different identifier types (e.g. hashed email + device ID) for effective cross-device linking.

Verify it’s working

In the Signal Management UI, open your Kochava IdentityLink integration and watch the Live Events stream as you trigger events that include at least two identifier types (e.g. hashed email + device ID).
Contact your Kochava account manager to confirm the identity link was received and processed.
Confirm 200 responses in Signal’s Live Events log.
Verify cross-device audience reports in the Kochava dashboard reflect the linked identities.

Troubleshooting

Symptom	Cause	Resolution
`401 Unauthorized`	Invalid API key	Verify `api_key` in Kochava Account Settings and update Signal.
`400 Bad Request`	Missing required identifiers	Ensure the event payload includes at least one valid identifier type.
Identity links not appearing	IdentityLink not enabled	Confirm IdentityLink is active on your account with your Kochava account manager.
Wrong partner	Incorrect `partner_id`	Verify the Partner ID with your Kochava account manager.
Partial linking	Single identifier only	Include multiple identifier types per event for cross-device resolution.

Visit Kochava IdentityLink documentation for full API reference and credential setup instructions.

Blueprint

The Kochava IdentityLink blueprint version is 0.1.0 (alpha). It ships with a Retail variant covering add_to_cart and purchase events used as carriers for identity linkage.