Users API

Attach identity and group data to your events.

Users and groups

Identity connects events to a person or an account. A user is identified by a string userId, and a group is identified by a string groupId. All identity records are scoped to a single project.

The SDK models identity with vanta.identify() and vanta.group(). Both produce internal events: identifying emits a $identify event and associating a group emits a $group event.

Identify a user

POST /v1/projects/:projectId/identify

Creates a user record if it does not exist, or updates the properties on an existing one. This endpoint uses session authentication and is the dashboard-facing identity API.

{
  "externalId": "user_123",
  "properties": {
    "email": "sarah@example.com",
    "name": "Sarah Chen",
    "plan": "pro",
    "signupChannel": "docs"
  }
}

Request fields:

Response:

{
  "data": {
    "id": "user_123",
    "projectId": "p_123",
    "externalId": "user_123",
    "properties": { "email": "sarah@example.com", "plan": "pro" },
    "firstSeenAt": "2026-08-24T10:32:01.000Z",
    "lastSeenAt": "2026-08-24T10:32:01.000Z"
  }
}

Associate a group

Groups are associated by sending a $group event through the standard ingest endpoint. The event carries the groupId and the group properties:

{
  "type": "$group",
  "groupId": "org_112",
  "data": {
    "type": "organization",
    "name": "Acme Corp",
    "size": 42
  }
}

Send it to POST /v1/events (or as part of a batch). The group record is created or updated from the data object, and the event appears under the group just like any other event.

Get a user

GET /v1/projects/:projectId/users/:userId

Returns the user record for the given userId, including properties and an event count.

Response:

{
  "data": {
    "id": "user_123",
    "projectId": "p_123",
    "externalId": "user_123",
    "properties": { "email": "sarah@example.com", "plan": "pro" },
    "eventCount": 14,
    "firstSeenAt": "2026-08-24T10:32:01.000Z",
    "lastSeenAt": "2026-08-26T08:10:22.000Z"
  }
}

Returns 404 if no user exists for that id in the project.

List users

GET /v1/projects/:projectId/users?limit=50&offset=0

Lists users in the project with limit (default 50) and offset pagination.

Response:

{
  "data": [ "user objects" ],
  "meta": {
    "total": 1240,
    "limit": 50,
    "offset": 0
  }
}