Identify user

When a user signs up or updates their profile, send their data to Retain. You must identify a user before tracking events for them.

Call /identify before /track. Events can only be recorded for users that have been identified.

Identify a user

import { Retain } from '@retain-so/sdk';

const retain = new Retain(process.env.RETAIN_WRITE_KEY);

retain.identify({
  userId: 'user_123',
  email: '[email protected]',
  properties: {
    name: 'Jane Doe',
    avatar: 'https://example.com/avatar.jpg',
    // Add anything else about the user here
  },
});

import os
import requests

requests.post(
    'https://api.retain.so/identify',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Basic {os.environ["RETAIN_WRITE_KEY"]}',
    },
    json={
        'userId': 'user_123',
        'email': '[email protected]',
        'properties': {
            'name': 'Jane Doe',
            'avatar': 'https://example.com/avatar.jpg',
            # Add anything else about the user here
        },
    },
)

$payload = json_encode([
    'userId' => 'user_123',
    'email' => '[email protected]',
    'properties' => [
        'name' => 'Jane Doe',
        'avatar' => 'https://example.com/avatar.jpg',
    ],
]);

$ch = curl_init('https://api.retain.so/identify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Basic ' . getenv('RETAIN_WRITE_KEY'),
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
curl_exec($ch);
curl_close($ch);

require 'net/http'
require 'json'

uri = URI('https://api.retain.so/identify')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['Authorization'] = "Basic #{ENV.fetch('RETAIN_WRITE_KEY')}"
req.body = {
  userId: 'user_123',
  email: '[email protected]',
  properties: {
    name: 'Jane Doe',
    avatar: 'https://example.com/avatar.jpg',
    # Add anything else about the user here
  },
}.to_json

Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String json = """
  {
    "userId": "user_123",
    "email": "[email protected]",
    "properties": {
      "name": "Jane Doe",
      "avatar": "https://example.com/avatar.jpg"
    }
  }
  """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.retain.so/identify"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Basic " + System.getenv("RETAIN_WRITE_KEY"))
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

curl -X POST https://api.retain.so/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $RETAIN_WRITE_KEY" \
  -d '{
    "userId": "user_123",
    "email": "[email protected]",
    "properties": {
      "name": "Jane Doe",
      "avatar": "https://example.com/avatar.jpg"
    }
  }'

Identify a user with account

For products with workspaces or teams, you can associate users with an account and mark the account owner:

import { Retain } from '@retain-so/sdk';

const retain = new Retain(process.env.RETAIN_WRITE_KEY);

retain.identify({
  userId: 'user_123',
  email: '[email protected]',
  isAccountOwner: true,
  account: {
    id: 'acct_456',
    name: 'Acme Inc',
    avatar: 'https://example.com/acme-logo.png',
  },
  properties: {
    name: 'Jane Doe',
    avatar: 'https://example.com/avatar.jpg',
  },
});

import os
import requests

requests.post(
    'https://api.retain.so/identify',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Basic {os.environ["RETAIN_WRITE_KEY"]}',
    },
    json={
        'userId': 'user_123',
        'email': '[email protected]',
        'isAccountOwner': True,
        'account': {
            'id': 'acct_456',
            'name': 'Acme Inc',
            'avatar': 'https://example.com/acme-logo.png',
        },
        'properties': {
            'name': 'Jane Doe',
            'avatar': 'https://example.com/avatar.jpg',
        },
    },
)

$payload = json_encode([
    'userId' => 'user_123',
    'email' => '[email protected]',
    'isAccountOwner' => true,
    'account' => [
        'id' => 'acct_456',
        'name' => 'Acme Inc',
        'avatar' => 'https://example.com/acme-logo.png',
    ],
    'properties' => [
        'name' => 'Jane Doe',
        'avatar' => 'https://example.com/avatar.jpg',
    ],
]);

$ch = curl_init('https://api.retain.so/identify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Basic ' . getenv('RETAIN_WRITE_KEY'),
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
curl_exec($ch);
curl_close($ch);

require 'net/http'
require 'json'

uri = URI('https://api.retain.so/identify')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['Authorization'] = "Basic #{ENV.fetch('RETAIN_WRITE_KEY')}"
req.body = {
  userId: 'user_123',
  email: '[email protected]',
  isAccountOwner: true,
  account: {
    id: 'acct_456',
    name: 'Acme Inc',
    avatar: 'https://example.com/acme-logo.png',
  },
  properties: {
    name: 'Jane Doe',
    avatar: 'https://example.com/avatar.jpg',
  },
}.to_json

Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String json = """
  {
    "userId": "user_123",
    "email": "[email protected]",
    "isAccountOwner": true,
    "account": {
      "id": "acct_456",
      "name": "Acme Inc",
      "avatar": "https://example.com/acme-logo.png"
    },
    "properties": {
      "name": "Jane Doe",
      "avatar": "https://example.com/avatar.jpg"
    }
  }
  """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.retain.so/identify"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Basic " + System.getenv("RETAIN_WRITE_KEY"))
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

curl -X POST https://api.retain.so/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $RETAIN_WRITE_KEY" \
  -d '{
    "userId": "user_123",
    "email": "[email protected]",
    "isAccountOwner": true,
    "account": {
      "id": "acct_456",
      "name": "Acme Inc",
      "avatar": "https://example.com/acme-logo.png"
    },
    "properties": {
      "name": "Jane Doe",
      "avatar": "https://example.com/avatar.jpg"
    }
  }'

See POST /identify in the API Reference for more details.

Reserved traits

Everything you send in properties is stored as a trait on the customer. A few keys are reserved and power specific features in the dashboard:

Key	Type	What it powers
`name`	string	Display name shown across the dashboard
`avatar`	string (URL)	Customer avatar shown across the dashboard
`plan`	string	Retention cohorts split by pricing plan (e.g. `starter`, `pro`)
`acquisitionChannel`	string	Retention cohorts split by where the customer came from (e.g. `organic`, `referral`)
`companySize`	string	Retention cohorts split by company size bucket (e.g. `1-10`, `11-50`)
`segment`	string	Retention cohorts split by the company’s ICP segment (e.g. `agency`, `creator`)

The segment trait is the segment your customer belongs to in your ICP. It is not the behavioral segment Retain calculates for each account (Curious, Loyal, Zombie, and friends). Those are computed from usage, not sent by you.

Any other key is stored as a custom trait. Custom traits with a small set of values (20 or fewer) also show up as cohort grouping options in the Metrics page.

Traits are merged, not replaced

Each identify call does a shallow merge: keys you send overwrite the same keys, keys you omit are preserved. You can send plan on signup and acquisitionChannel later without losing anything. Send null for a key to clear it.

Split retention cohorts by trait

Send the cohort traits and the Metrics page lets you split the retention chart by any of them. That is how you find out which plan, channel, or segment quietly churns the most:

retain.identify({
  userId: 'user_123',
  email: '[email protected]',
  properties: {
    plan: 'starter',
    acquisitionChannel: 'organic',
    companySize: '11-50',
    segment: 'agency',
  },
});

curl -X POST https://api.retain.so/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $RETAIN_WRITE_KEY" \
  -d '{
    "userId": "user_123",
    "email": "[email protected]",
    "properties": {
      "plan": "starter",
      "acquisitionChannel": "organic",
      "companySize": "11-50",
      "segment": "agency"
    }
  }'

Next steps

Track

Record events for identified users.

Introduction

Quickstart

Integrations

Identify a user

Identify a user with account

Reserved traits

Traits are merged, not replaced

Split retention cohorts by trait

Next steps

Track

​Identify a user

​Identify a user with account

​Reserved traits

​Traits are merged, not replaced

​Split retention cohorts by trait

​Next steps

Track

Identify a user

Identify a user with account

Reserved traits

Traits are merged, not replaced

Split retention cohorts by trait

Next steps