Identify events

cURL

curl --request POST \
  --url https://api.unifyintent.com/analytics/v1/identify \
  --header 'Content-Type: application/json' \
  --header 'Origin: <origin>' \
  --header 'X-Write-Key: <api-key>' \
  --data '
{
  "type": "identify",
  "visitorId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "context": {
    "library": {
      "name": "<string>",
      "version": "<string>"
    },
    "ip": "127.0.0.1",
    "locale": "<string>",
    "userAgent": "<string>",
    "userAgentData": {
      "brands": [
        {
          "brand": "<string>",
          "version": "<string>"
        }
      ],
      "mobile": true,
      "platform": "<string>"
    },
    "utm": {
      "source": "<string>",
      "medium": "<string>",
      "campaign": "<string>",
      "term": "<string>",
      "content": "<string>"
    }
  },
  "sessionId": "<string>",
  "sentAt": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.unifyintent.com/analytics/v1/identify"

payload = {
    "type": "identify",
    "visitorId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "context": {
        "library": {
            "name": "<string>",
            "version": "<string>"
        },
        "ip": "127.0.0.1",
        "locale": "<string>",
        "userAgent": "<string>",
        "userAgentData": {
            "brands": [
                {
                    "brand": "<string>",
                    "version": "<string>"
                }
            ],
            "mobile": True,
            "platform": "<string>"
        },
        "utm": {
            "source": "<string>",
            "medium": "<string>",
            "campaign": "<string>",
            "term": "<string>",
            "content": "<string>"
        }
    },
    "sessionId": "<string>",
    "sentAt": "2023-11-07T05:31:56Z"
}
headers = {
    "Origin": "<origin>",
    "X-Write-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Origin: '<origin>',
    'X-Write-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'identify',
    visitorId: '<string>',
    timestamp: '2023-11-07T05:31:56Z',
    context: {
      library: {name: '<string>', version: '<string>'},
      ip: '127.0.0.1',
      locale: '<string>',
      userAgent: '<string>',
      userAgentData: {
        brands: [{brand: '<string>', version: '<string>'}],
        mobile: true,
        platform: '<string>'
      },
      utm: {
        source: '<string>',
        medium: '<string>',
        campaign: '<string>',
        term: '<string>',
        content: '<string>'
      }
    },
    sessionId: '<string>',
    sentAt: '2023-11-07T05:31:56Z'
  })
};

fetch('https://api.unifyintent.com/analytics/v1/identify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unifyintent.com/analytics/v1/identify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'identify',
    'visitorId' => '<string>',
    'timestamp' => '2023-11-07T05:31:56Z',
    'context' => [
        'library' => [
                'name' => '<string>',
                'version' => '<string>'
        ],
        'ip' => '127.0.0.1',
        'locale' => '<string>',
        'userAgent' => '<string>',
        'userAgentData' => [
                'brands' => [
                                [
                                                                'brand' => '<string>',
                                                                'version' => '<string>'
                                ]
                ],
                'mobile' => true,
                'platform' => '<string>'
        ],
        'utm' => [
                'source' => '<string>',
                'medium' => '<string>',
                'campaign' => '<string>',
                'term' => '<string>',
                'content' => '<string>'
        ]
    ],
    'sessionId' => '<string>',
    'sentAt' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Origin: <origin>",
    "X-Write-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unifyintent.com/analytics/v1/identify"

	payload := strings.NewReader("{\n  \"type\": \"identify\",\n  \"visitorId\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"context\": {\n    \"library\": {\n      \"name\": \"<string>\",\n      \"version\": \"<string>\"\n    },\n    \"ip\": \"127.0.0.1\",\n    \"locale\": \"<string>\",\n    \"userAgent\": \"<string>\",\n    \"userAgentData\": {\n      \"brands\": [\n        {\n          \"brand\": \"<string>\",\n          \"version\": \"<string>\"\n        }\n      ],\n      \"mobile\": true,\n      \"platform\": \"<string>\"\n    },\n    \"utm\": {\n      \"source\": \"<string>\",\n      \"medium\": \"<string>\",\n      \"campaign\": \"<string>\",\n      \"term\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  },\n  \"sessionId\": \"<string>\",\n  \"sentAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Origin", "<origin>")
	req.Header.Add("X-Write-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unifyintent.com/analytics/v1/identify")
  .header("Origin", "<origin>")
  .header("X-Write-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"identify\",\n  \"visitorId\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"context\": {\n    \"library\": {\n      \"name\": \"<string>\",\n      \"version\": \"<string>\"\n    },\n    \"ip\": \"127.0.0.1\",\n    \"locale\": \"<string>\",\n    \"userAgent\": \"<string>\",\n    \"userAgentData\": {\n      \"brands\": [\n        {\n          \"brand\": \"<string>\",\n          \"version\": \"<string>\"\n        }\n      ],\n      \"mobile\": true,\n      \"platform\": \"<string>\"\n    },\n    \"utm\": {\n      \"source\": \"<string>\",\n      \"medium\": \"<string>\",\n      \"campaign\": \"<string>\",\n      \"term\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  },\n  \"sessionId\": \"<string>\",\n  \"sentAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unifyintent.com/analytics/v1/identify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Origin"] = '<origin>'
request["X-Write-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"identify\",\n  \"visitorId\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"context\": {\n    \"library\": {\n      \"name\": \"<string>\",\n      \"version\": \"<string>\"\n    },\n    \"ip\": \"127.0.0.1\",\n    \"locale\": \"<string>\",\n    \"userAgent\": \"<string>\",\n    \"userAgentData\": {\n      \"brands\": [\n        {\n          \"brand\": \"<string>\",\n          \"version\": \"<string>\"\n        }\n      ],\n      \"mobile\": true,\n      \"platform\": \"<string>\"\n    },\n    \"utm\": {\n      \"source\": \"<string>\",\n      \"medium\": \"<string>\",\n      \"campaign\": \"<string>\",\n      \"term\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  },\n  \"sessionId\": \"<string>\",\n  \"sentAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

POST

identify

cURL

curl --request POST \
  --url https://api.unifyintent.com/analytics/v1/identify \
  --header 'Content-Type: application/json' \
  --header 'Origin: <origin>' \
  --header 'X-Write-Key: <api-key>' \
  --data '
{
  "type": "identify",
  "visitorId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "context": {
    "library": {
      "name": "<string>",
      "version": "<string>"
    },
    "ip": "127.0.0.1",
    "locale": "<string>",
    "userAgent": "<string>",
    "userAgentData": {
      "brands": [
        {
          "brand": "<string>",
          "version": "<string>"
        }
      ],
      "mobile": true,
      "platform": "<string>"
    },
    "utm": {
      "source": "<string>",
      "medium": "<string>",
      "campaign": "<string>",
      "term": "<string>",
      "content": "<string>"
    }
  },
  "sessionId": "<string>",
  "sentAt": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.unifyintent.com/analytics/v1/identify"

payload = {
    "type": "identify",
    "visitorId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "context": {
        "library": {
            "name": "<string>",
            "version": "<string>"
        },
        "ip": "127.0.0.1",
        "locale": "<string>",
        "userAgent": "<string>",
        "userAgentData": {
            "brands": [
                {
                    "brand": "<string>",
                    "version": "<string>"
                }
            ],
            "mobile": True,
            "platform": "<string>"
        },
        "utm": {
            "source": "<string>",
            "medium": "<string>",
            "campaign": "<string>",
            "term": "<string>",
            "content": "<string>"
        }
    },
    "sessionId": "<string>",
    "sentAt": "2023-11-07T05:31:56Z"
}
headers = {
    "Origin": "<origin>",
    "X-Write-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Origin: '<origin>',
    'X-Write-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'identify',
    visitorId: '<string>',
    timestamp: '2023-11-07T05:31:56Z',
    context: {
      library: {name: '<string>', version: '<string>'},
      ip: '127.0.0.1',
      locale: '<string>',
      userAgent: '<string>',
      userAgentData: {
        brands: [{brand: '<string>', version: '<string>'}],
        mobile: true,
        platform: '<string>'
      },
      utm: {
        source: '<string>',
        medium: '<string>',
        campaign: '<string>',
        term: '<string>',
        content: '<string>'
      }
    },
    sessionId: '<string>',
    sentAt: '2023-11-07T05:31:56Z'
  })
};

fetch('https://api.unifyintent.com/analytics/v1/identify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unifyintent.com/analytics/v1/identify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'identify',
    'visitorId' => '<string>',
    'timestamp' => '2023-11-07T05:31:56Z',
    'context' => [
        'library' => [
                'name' => '<string>',
                'version' => '<string>'
        ],
        'ip' => '127.0.0.1',
        'locale' => '<string>',
        'userAgent' => '<string>',
        'userAgentData' => [
                'brands' => [
                                [
                                                                'brand' => '<string>',
                                                                'version' => '<string>'
                                ]
                ],
                'mobile' => true,
                'platform' => '<string>'
        ],
        'utm' => [
                'source' => '<string>',
                'medium' => '<string>',
                'campaign' => '<string>',
                'term' => '<string>',
                'content' => '<string>'
        ]
    ],
    'sessionId' => '<string>',
    'sentAt' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Origin: <origin>",
    "X-Write-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unifyintent.com/analytics/v1/identify"

	payload := strings.NewReader("{\n  \"type\": \"identify\",\n  \"visitorId\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"context\": {\n    \"library\": {\n      \"name\": \"<string>\",\n      \"version\": \"<string>\"\n    },\n    \"ip\": \"127.0.0.1\",\n    \"locale\": \"<string>\",\n    \"userAgent\": \"<string>\",\n    \"userAgentData\": {\n      \"brands\": [\n        {\n          \"brand\": \"<string>\",\n          \"version\": \"<string>\"\n        }\n      ],\n      \"mobile\": true,\n      \"platform\": \"<string>\"\n    },\n    \"utm\": {\n      \"source\": \"<string>\",\n      \"medium\": \"<string>\",\n      \"campaign\": \"<string>\",\n      \"term\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  },\n  \"sessionId\": \"<string>\",\n  \"sentAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Origin", "<origin>")
	req.Header.Add("X-Write-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unifyintent.com/analytics/v1/identify")
  .header("Origin", "<origin>")
  .header("X-Write-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"identify\",\n  \"visitorId\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"context\": {\n    \"library\": {\n      \"name\": \"<string>\",\n      \"version\": \"<string>\"\n    },\n    \"ip\": \"127.0.0.1\",\n    \"locale\": \"<string>\",\n    \"userAgent\": \"<string>\",\n    \"userAgentData\": {\n      \"brands\": [\n        {\n          \"brand\": \"<string>\",\n          \"version\": \"<string>\"\n        }\n      ],\n      \"mobile\": true,\n      \"platform\": \"<string>\"\n    },\n    \"utm\": {\n      \"source\": \"<string>\",\n      \"medium\": \"<string>\",\n      \"campaign\": \"<string>\",\n      \"term\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  },\n  \"sessionId\": \"<string>\",\n  \"sentAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unifyintent.com/analytics/v1/identify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Origin"] = '<origin>'
request["X-Write-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"identify\",\n  \"visitorId\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"context\": {\n    \"library\": {\n      \"name\": \"<string>\",\n      \"version\": \"<string>\"\n    },\n    \"ip\": \"127.0.0.1\",\n    \"locale\": \"<string>\",\n    \"userAgent\": \"<string>\",\n    \"userAgentData\": {\n      \"brands\": [\n        {\n          \"brand\": \"<string>\",\n          \"version\": \"<string>\"\n        }\n      ],\n      \"mobile\": true,\n      \"platform\": \"<string>\"\n    },\n    \"utm\": {\n      \"source\": \"<string>\",\n      \"medium\": \"<string>\",\n      \"campaign\": \"<string>\",\n      \"term\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  },\n  \"sessionId\": \"<string>\",\n  \"sentAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

Overview

Associate a visitor with a known person when they sign in, submit a form, or provide their email address. Use the same visitorId in that visitor’s page and custom events so their activity can be associated with their identity.

Examples

Identify a trial user

Set UNIFY_WRITE_KEY to the event source’s write key and use an allowed origin in the Origin header. Replace the example visitor ID and timestamp with those from the actual event. See Analytics authentication for setup.

curl --request POST \
  --url "https://api.unifyintent.com/analytics/v1/identify" \
  --header "X-Write-Key: $UNIFY_WRITE_KEY" \
  --header "Origin: https://app.your-company.example" \
  --header "Content-Type: application/json" \
  --data '{
  "type": "identify",
  "visitorId": "visitor-trial-1042",
  "sessionId": "session-trial-1042-1",
  "timestamp": "2026-10-06T15:00:00Z",
  "context": {},
  "person": {
    "email": "alex@northstar.example",
    "first_name": "Alex",
    "last_name": "Morgan"
  },
  "company": {
    "domain": "northstar.example",
    "name": "Northstar Labs"
  }
}'

Use person and company to provide record attributes. For additional attributes, use their API names and values that match their types in Unify.

Authorizations

X-Write-Key

string

header

required

Use the event source’s write key. Requests also require an allowed Origin header.

Headers

Origin

string<uri>

required

Website or application origin allowed for the event source. Required for browser and server-side requests.

Body

application/json

An identify event is used to send information about a visitor.

type

enum<string>

required

The type of analytics event being sent.

Available options:

identify

visitorId

string

required

Unique identifier for the visitor that triggered this event.

timestamp

string<date-time>

required

Timestamp of the event (in UTC).

context

object

required

Contextual information about the client behind the event.

Show child attributes

sessionId

string

Unique identifier for the session in which this event occurred.

sentAt

string<date-time>

Timestamp at which the request was sent (in UTC). May differ from the event timestamp if sending was delayed.

traits

object

deprecated

Traits for the identify request payload.

Show child attributes

company

object

Information about the company associated with the visitor.

Show child attributes

person

object

Information about the person associated with the visitor.

Show child attributes

Response

The request has succeeded.

⌘I

Unify platform

MCP

Developer guides

API reference

SDKs

Identify events

Overview

Examples

Authorizations

Headers

Body

Response

​Overview

​Examples

Authorizations

Headers

Body

Response

Overview

Examples