Source: https://datafa.st/docs/api/website/identity/identify
Markdown source: https://datafa.st/docs/api/website/identity/identify.md
Description: Link a DataFast visitor to a known user ID and store profile metadata from your backend. This powers [user identification](/docs/user-identification) in the dashboard and enriches visitor profiles returned by [Get visitor](/docs/api-get-visitor).

# Identify users

`POST https://datafa.st/api/v1/identify`

Link a DataFast visitor to a known user ID and store profile metadata from your backend. This powers [user identification](/docs/user-identification) in the dashboard and enriches visitor profiles returned by [Get visitor](/docs/api/website/visitors/retrieve).

Send any extra top-level JSON fields — they are stored as profile metadata. On cookieless websites, the request succeeds but no profile is persisted.

> **Related:** [User identification](/docs/user-identification) · [Web-to-app tracking](/docs/web-to-app-tracking)

## Request

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | Required with dft_ | Required with a `dft_` account token on Website API routes. Omit with a `df_` website key. Example: `?websiteId=665f0b3c4d2e1a0012345678`. |

#### Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | Your stable user ID (from your auth system). Example: `"user_123"`. Max 255 chars. Links the visitor to this user in [Identify](/docs/user-identification). |
| `datafast_visitor_id` | string | Yes | Visitor UUID from the `datafast_visitor_id` cookie or tracking script. Example: `"a3ab2331-989f-4cfa-91c6-2461c9e3c6bd"`. Alias: `visitorId` on some endpoints. |
| `Any other top-level field` | any | No | Stored as profile metadata. Example: `email`, `plan`, `company`. Do not send secrets or payment credentials. |

#### Example request body

```json
{
  "user_id": "user_123",
  "datafast_visitor_id": "a3ab2331-989f-4cfa-91c6-2461c9e3c6bd",
  "email": "jane@example.com",
  "plan": "pro"
}
```

Extra top-level fields (like `email`, `plan`) are stored as profile metadata — not secrets or payment credentials.

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data` (and `pagination` when the endpoint is paginated).

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | `success`. |
| `data.message` | string | Human-readable confirmation or status message for the operation. |
| `data.profileId` | string | ObjectId of the Identify profile created or found by DataFast. Profile ObjectId when a profile exists or is created. |

## Authentication

- **`df_` website API key:** The website is inferred from the key. You do not need a `websiteId` query parameter.
- **`dft_` account token:** Requires `identify:write` permission and `?websiteId=` on every request. The token must be allowed to access that website.

Read [authentication and scopes](/docs/api/authentication) for token creation, permission lists, and scoped tokens.

### Errors

**400** — Missing `user_id` or `datafast_visitor_id`, invalid UUID, or `user_id` longer than 255 characters.

**404** — Visitor has no pageviews on this website.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X POST "https://datafa.st/api/v1/identify" \
  -H "Authorization: Bearer df_xxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_123","datafast_visitor_id":"a3ab2331-989f-4cfa-91c6-2461c9e3c6bd","email":"jane@example.com","plan":"pro"}'
```

### Success response

```json
{
  "status": "success",
  "data": { "message": "User profile created successfully", "profileId": "665f0b3c4d2e1a0012345678" }
}
```