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 stored as profile metadata. 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

Stored as profile metadata. Example: email, plan, company. 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

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