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 in the dashboard and enriches visitor profiles returned by Get visitor.

Send any extra top-level JSON fields — they are shallow-merged into profile metadata. Re-sending the same user_id and datafast_visitor_id updates the profile (action: created, updated, or unchanged). Omitted keys are preserved. Placeholder names like undefined undefined are ignored. On cookieless websites, the request succeeds but no profile is persisted.

Related: User identification · Web-to-app tracking

Try on Playground

Request

Query parameters

websiteId

string

Required with a dft_ account token on Website API routes. Omit with a df_ website key. Example: ?websiteId=665f0b3c4d2e1a0012345678.

Body parameters

user_id

string

required

Your stable user ID (from your auth system). Example: "user_123". Max 255 chars. Links the visitor to this user in Identify.

datafast_visitor_id

string

required

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

Shallow-merged into profile metadata. Example: email, plan, company. Omitted keys are preserved. Do not send secrets or payment credentials.

Example request body

{
  "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

status

string

success.

data.message

string

Human-readable confirmation or status message for the operation.

data.profileId

string (optional)

ObjectId of the Identify profile created or found by DataFast. Profile ObjectId for the latest profile version. Omitted for cookieless websites.

data.action

string (optional)

created, updated, or unchanged. Omitted for cookieless websites.

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 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 for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown

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"}'