Users API — Identify, List, and Delete User Profiles

The Users API manages user profiles and their associated traits inside Cano Analytics. Use it to identify users when they sign up or log in, enrich profiles with traits like plan or email, and look up or delete user records programmatically. All requests require a valid API key sent as a Bearer token.

POST /v1/identify — Identify a User

Create or update a user profile and attach traits to it. If the user_id already exists, Cano Analytics merges the new traits with the existing profile. This endpoint requires the write scope.

Body parameters

string

required

Your application’s unique identifier for this user. Cano Analytics uses this as the canonical user key.

object

A key-value object of user attributes. Common fields include name, email, plan, company, and created_at, but you can include any custom trait.

string

ISO 8601 timestamp indicating when the identification occurred. Defaults to server time if omitted.

Request example

POST /v1/identify

{
  "user_id": "usr_4f8a1c",
  "traits": {
    "name": "Jordan Lee",
    "email": "[email protected]",
    "plan": "pro",
    "company": "Acme Corp",
    "created_at": "2024-01-10T08:00:00Z"
  },
  "timestamp": "2024-06-15T14:00:00Z"
}

Response — 200 OK

200 OK

{
  "id": "usr_4f8a1c",
  "status": "identified",
  "received_at": "2024-06-15T14:00:01.221Z"
}

GET /v1/users — List Users

Retrieve a paginated list of all user profiles in your workspace. This endpoint requires the read scope.

Query parameters

integer

Number of users to return per page. Defaults to 100. Maximum is 1000.

string

Opaque pagination cursor from the previous response’s next_cursor field.

string

Filter users by a specific trait value. For example, ?trait[plan]=pro returns only users whose plan trait equals "pro". You can combine multiple trait filters in one request.

Request example

cURL

curl -G https://api.canoanalytics.io/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "trait[plan]=pro" \
  --data-urlencode "limit=50"

Response — 200 OK

200 OK

{
  "data": [
    {
      "id": "usr_4f8a1c",
      "traits": {
        "name": "Jordan Lee",
        "email": "[email protected]",
        "plan": "pro"
      },
      "created_at": "2024-01-10T08:00:00Z",
      "last_seen_at": "2024-06-15T14:32:00Z",
      "event_count": 284
    }
  ],
  "next_cursor": "cur_eyJ1c2VyIjoyfQ",
  "has_more": false
}

array

An array of user profile objects matching your query.

string

Opaque cursor for the next page. null when no more pages exist.

boolean

true if additional pages of results are available.

GET /v1/users/ — Get a User

Retrieve the full profile for a single user by their ID. This endpoint requires the read scope.

Path parameters

string

required

The unique identifier of the user to retrieve.

Response fields

string

The user’s unique identifier.

object

All traits associated with this user, merged from every identify call.

string

ISO 8601 timestamp of when the user was first identified in Cano Analytics.

string

ISO 8601 timestamp of the most recent event attributed to this user.

integer

Total number of events recorded for this user.

Request example

cURL

curl https://api.canoanalytics.io/v1/users/usr_4f8a1c \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

200 OK

{
  "id": "usr_4f8a1c",
  "traits": {
    "name": "Jordan Lee",
    "email": "[email protected]",
    "plan": "pro",
    "company": "Acme Corp",
    "created_at": "2024-01-10T08:00:00Z"
  },
  "created_at": "2024-01-10T08:00:00Z",
  "last_seen_at": "2024-06-15T14:32:00Z",
  "event_count": 284
}

DELETE /v1/users/ — Delete a User

Permanently delete a user profile and all events associated with that user. Use this endpoint to fulfill GDPR right-to-erasure requests. This endpoint requires the admin scope.

This action is permanent and cannot be undone. Deleting a user removes their profile and every event they have ever generated from Cano Analytics. Export any data you need to retain before calling this endpoint.

Path parameters

string

required

The unique identifier of the user to permanently delete.

Request example

cURL

curl -X DELETE https://api.canoanalytics.io/v1/users/usr_4f8a1c \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY"

Response — 204 No Content

A successful deletion returns HTTP 204 with no response body.

Overview

Endpoints

SDKs

Users API — Identify, List, and Delete User Profiles

POST /v1/identify — Identify a User

Body parameters

Request example

Response — 200 OK

GET /v1/users — List Users

Query parameters

Request example

Response — 200 OK

GET /v1/users/ — Get a User

Path parameters

Response fields

Request example

Response — 200 OK

DELETE /v1/users/ — Delete a User

Path parameters

Request example

Response — 204 No Content

​POST /v1/identify — Identify a User

​Body parameters

​Request example

​Response — 200 OK

​GET /v1/users — List Users

​Query parameters

​Request example

​Response — 200 OK

​GET /v1/users/ — Get a User

​Path parameters

​Response fields

​Request example

​Response — 200 OK

​DELETE /v1/users/ — Delete a User

​Path parameters

​Request example

​Response — 204 No Content

POST /v1/identify — Identify a User

Body parameters

Request example

Response — 200 OK

GET /v1/users — List Users

Query parameters

Request example

Response — 200 OK

GET /v1/users/ — Get a User

Path parameters

Response fields

Request example

Response — 200 OK

DELETE /v1/users/ — Delete a User

Path parameters

Request example

Response — 204 No Content