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 and store profile metadata.

# Identify users

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

Link a DataFast visitor to a known user and store profile metadata.

## Request

### Authentication

- `df_` website API key for one website.
- `dft_` account token with `identify:write`. Pass `websiteId` as a query parameter.


### Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | Stable user ID. Non-empty, max 255 characters. |
| `datafast_visitor_id` | string | Yes | DataFast visitor UUID from the browser cookie or client SDK. Used to attach server-side events to a visitor journey. |
| `Any other top-level field` | any | No | Stored inside profile metadata. Example: send `email: "jane@example.com"`, `plan: "pro"`, `company: "Acme"`, `role: "admin"`, or `signup_source: "invite"`. |

## Response

Returns a JSON object with `status` and endpoint-specific fields.

### 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. |

### Errors

Common errors include `400` for invalid input, `401` for missing or invalid tokens, `403` for missing permission or suspended tracking, `404` for missing resources, and `500` for server errors.

## 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" }
}
```