Associate an anonymous visitor with a logged-in user

Links a visitorId to a userId and (optionally) attaches traits. A side effect back-fills the userId onto all prior events/visits for that visitor, so pre-login attribution is stitched to the identified user.

This is a dedicated endpoint — NOT a Segment-style /api/v1/t with type:"identify"; the ingest endpoint has no type field.

Trait rules (server-side sanitizeTraits): reserved keys email/phone/name/locale/timezone are lifted to encrypted top-level user columns (send null to clear); other keys go to a JSON column. Keys whose name contains dangerous substrings (password, pwd, idcard, passport, ssn, bankcard, cvv, token, secret, private_key, api_key, …) are dropped and echoed in dropped_keys. Payload must be ≤ 8 KiB and nested ≤ 2 levels — over → 400. Audit logs record key counts only, never values.

Note: to receive event-triggered email, a user must be identified with a non-empty traits.email; otherwise trigger consumers skip them.

Auth: X-API-Key (also ?_ak / ?key), no extra scope gate.

Authorizations

ApiKeyAuth

Request Body^required

application/json

Visitor→user association payload.

object

visitorId

required

Anonymous visitor ID (alias visitor_id). Required, non-empty.

string

userId

required

Logged-in user ID (alias user_id). Required, non-empty.

string

traits

Optional user traits. Reserved keys email/phone/name/timezone/locale are lifted to encrypted columns (null clears). Dangerous keys are dropped and echoed in dropped_keys. ≤ 8 KiB, nested ≤ 2 levels.

object

key

additional properties

any

Example

1
{
2
  "visitorId": "vid_abc123",
3
  "userId": "uid_456",
4
  "traits": {
5
    "email": "user@example.com",
6
    "name": "张三",
7
    "plan": "pro"
8
  }
9
}

Responses

202

Identity recorded. dropped_keys lists any trait keys filtered out.

application/json

object

required

boolean

dropped_keys

required

Array<string>

400

Invalid JSON, missing visitorId/userId, or a traits validation failure (size / depth / shape).

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Examples

1
{
2
  "error": "visitorId 和 userId 不能为空"
3
}

1
{
2
  "error": "无效的 JSON 格式"
3
}

1
{
2
  "error": "traits payload exceeds 8 KiB limit"
3
}

401

Missing or invalid API key.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example^generated

1
{
2
  "error": "example",
3
  "retryAfter": 1,
4
  "message": "example",
5
  "affectedIndices": [
6
    1
7
  ]
8
}

500

Internal error while persisting the identity (no PII leaked).

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example

1
{
2
  "error": "identify failed"
3
}

POST

/api/v1/identify

1
curl --request POST \
2
  --url https://api.retidal.com/api/v1/identify \
3
  --header 'Content-Type: application/json' \
4
  --header 'X-API-Key: <YOUR_API_KEY>' \
5
  --data '{
6
  "visitorId": "vid_abc123",
7
  "userId": "uid_456",
8
  "traits": {
9
    "email": "user@example.com",
10
    "name": "张三",
11
    "plan": "pro"
12
  }
13
}'

1
const url = 'https://api.retidal.com/api/v1/identify';
2
const options = {
3
  method: 'POST',
4
  headers: {'X-API-Key': '<YOUR_API_KEY>', 'Content-Type': 'application/json'},
5
  body: '{"visitorId":"vid_abc123","userId":"uid_456","traits":{"email":"user@example.com","name":"张三","plan":"pro"}}'
6
};
7

8
try {
9
  const response = await fetch(url, options);
10
  const data = await response.json();
11
  console.log(data);
12
} catch (error) {
13
  console.error(error);
14
}

1
import requests
2

3
url = "https://api.retidal.com/api/v1/identify"
4

5
payload = {
6
    "visitorId": "vid_abc123",
7
    "userId": "uid_456",
8
    "traits": {
9
        "email": "user@example.com",
10
        "name": "张三",
11
        "plan": "pro"
12
    }
13
}
14
headers = {
15
    "X-API-Key": "<YOUR_API_KEY>",
16
    "Content-Type": "application/json"
17
}
18

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

21
print(response.json())

1
import httpx
2
import json
3

4
url = "https://api.retidal.com/api/v1/identify"
5

6
headers = {"X-API-Key": "<YOUR_API_KEY>"}
7

8
payload = json.loads("{\n  \"visitorId\": \"vid_abc123\",\n  \"userId\": \"uid_456\",\n  \"traits\": {\n    \"email\": \"user@example.com\",\n    \"name\": \"张三\",\n    \"plan\": \"pro\"\n  }\n}")
9

10
response = httpx.post(url, headers=headers, json=payload)
11

12
print(response.json())

1
package main
2

3
import (
4
  "fmt"
5
  "strings"
6
  "net/http"
7
  "io"
8
)
9

10
func main() {
11

12
  url := "https://api.retidal.com/api/v1/identify"
13

14
  payload := strings.NewReader("{\n  \"visitorId\": \"vid_abc123\",\n  \"userId\": \"uid_456\",\n  \"traits\": {\n    \"email\": \"user@example.com\",\n    \"name\": \"张三\",\n    \"plan\": \"pro\"\n  }\n}")
15

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

18
  req.Header.Add("X-API-Key", "<YOUR_API_KEY>")
19
  req.Header.Add("Content-Type", "application/json")
20

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

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

26
  fmt.Println(res)
27
  fmt.Println(string(body))
28

29
}

202Identity recorded. dropped_keys lists any trait keys filtered out.

1
{
2
  "ok": true,
3
  "dropped_keys": []
4
}

Associate an anonymous visitor with a logged-in user

Authorizations

Request Bodyrequired

Example

Responses

202

400

Examples

401

Examplegenerated

500

Example

Request Body^required

Example^generated