Users API reference
Users endpoints of the Quackback REST API: paths, parameters, request fields and responses.
This is the reference for the Users endpoints of the Quackback REST API: every endpoint, its parameters, request fields and response fields. It is generated from the API's OpenAPI description, so it matches what the API accepts.
All paths are relative to /api/v1 on your workspace's address (for example https://feedback.example.com/api/v1). Authenticate with an API key in the Authorization: Bearer qb_... header. For keys, errors, pagination and rate limits, see API overview. Every workspace also serves an interactive reference at /api/v1/docs.
Endpoints
GET /users: List portal usersPOST /users/identify: Identify (create or update) a userGET /users/{principalId}: Get a portal userPATCH /users/{principalId}: Update a portal userDELETE /users/{principalId}: Remove a portal user
List portal users
GET /api/v1/users
Returns a paginated list of portal users (public feedback submitters)
Parameters
Name | In | Type | Required | Description |
|---|---|---|---|---|
| query | string | No | Search by name or email |
| query | string ( | No | Filter by email verification status |
| query | string | No | Filter by join date (from) |
| query | string | No | Filter by join date (to) |
| query | string | No | Comma-separated segment IDs to filter by (OR logic) |
| query | string ( | No | Sort order |
| query | integer | No | Page number |
| query | integer | No | Items per page |
Response 200: returns items, total, hasMore, page, limit.
Identify (create or update) a user
POST /api/v1/users/identify
Create a new portal user or update an existing one by email. User attributes must be configured in Settings > User Attributes before they can be set.
Request body
Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | User email (used for lookup/creation) |
| string | No | Display name |
| string | No | Profile image URL |
| boolean | No | Email verification status |
| string | No | Your system's user ID for cross-referencing |
| object | No | User attributes (must be configured in Settings > User Attributes) |
Response 200: returns principalId, userId, name, email, image, emailVerified, externalId, attributes, createdAt, created.
Get a portal user
GET /api/v1/users/{principalId}
Get detailed information about a portal user, including their activity
Parameters
Name | In | Type | Required | Description |
|---|---|---|---|---|
| path | string | Yes | Principal ID |
Response 200: returns principalId, userId, name, email, image, emailVerified, attributes, joinedAt, postCount, commentCount, voteCount, createdAt, engagedPosts.
Update a portal user
PATCH /api/v1/users/{principalId}
Update a portal user's profile and attributes. User attributes must be configured in Settings > User Attributes before they can be set.
Parameters
Name | In | Type | Required | Description |
|---|---|---|---|---|
| path | string | Yes | Principal ID |
Request body
Field | Type | Required | Description |
|---|---|---|---|
| string | No | Display name |
| string, nullable | No | |
| boolean | No | Email verification status |
| string | No | Your system's user ID (null to unset) |
| object | No | User attributes (must be configured in Settings > User Attributes) |
Response 200: returns principalId, userId, name, email, image, emailVerified, externalId, attributes, createdAt.
Remove a portal user
DELETE /api/v1/users/{principalId}
Remove a portal user from the workspace
Parameters
Name | In | Type | Required | Description |
|---|---|---|---|---|
| path | string | Yes | Principal ID |
Was this helpful?
Your feedback shapes what we write next.