--- title: Users description: Manage users. --- # Users Manage users. ## [GET /users](/api-reference/users#tag/users/GET/users) List users List all users. Will return all users the requester has access to. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Query parameters - `filter` (`string`, optional) — A free text search string to filter users by name or email. - `customerId` (`array of string`, optional) — Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ### Responses #### 200 A list of users. Type: `object` - `items` (`array of User`, required) - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. - `name` (`string`, required, example John Doe) — The user's full name, shown in account management and used when the user is listed as a customer's contact person. - `email` (`string`, optional, email, example john.doe@example.com) — The user's email address. This is their sign-in identity — login verification codes are sent to it — and it is used to reach them when they are a customer's contact person. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person. - `identity` (`string`, optional, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `referenceId` (`string`, optional, max length 255, example hr-employee-98765) — A reference identifier provided by API clients to identify this user in their own systems. Must be unique per tenant. Use this field to look up users or to create/retrieve users during order creation. - `customers` (`array of EmbeddedCustomer`, optional) — The customers this user is associated with. The user can sign in and act on behalf of each of these customers. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer. Use it with the customer endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers. - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the user was created. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — Date and time when the user was last updated. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/users \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [POST /users](/api-reference/users#tag/users/POST/users) Create user Create a new user. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `name` (`string`, required, example John Doe) — The user's full name, shown in account management and used when the user is listed as a customer's contact person. - `email` (`string`, required, email, example john.doe@example.com) — The user's email address. This becomes their sign-in identity — login verification codes are sent to it. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person. - `role` (`enum`, optional, default MEMBER, one of MEMBER, MANAGER, ADMIN) — The role of the user when assigned to a customer. Defaults to 'MEMBER' if not specified. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer to whom the user will belong. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `referenceId` (`string`, optional, max length 255, example hr-employee-98765) — A reference identifier provided by API clients to identify this user in their own systems. Must be unique per tenant. Use this field to look up users by your external identifier. - `identity` (`string`, optional, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ### Responses #### 201 User created successfully. Type: [User](/api-reference/models.md#models/User) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/users \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "role": "ADMIN", "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "referenceId": "hr-employee-98765" }' ``` ## [GET /users/{userId}](/api-reference/users#tag/users/GET/users/{userId}) Get user Get a user by ID or referenceId. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `userId` (`string`, required) — The unique identifier of the user. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_hr-employee-98765`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ### Responses #### 200 User details. Type: [User](/api-reference/models.md#models/User) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/users/USER_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [PUT /users/{userId}](/api-reference/users#tag/users/PUT/users/{userId}) Update user Update an existing user. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `userId` (`string`, required) — The unique identifier of the user. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_hr-employee-98765`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ### Request body (required) Type: `object` - `name` (`string`, optional, example John Doe) — The user's full name, shown in account management and used when the user is listed as a customer's contact person. - `email` (`string`, optional, email, example john.doe@example.com) — The user's email address. This is their sign-in identity — changing it changes where login verification codes are sent. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ### Responses #### 200 User updated successfully. Type: [User](/api-reference/models.md#models/User) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/users/USER_ID \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "metadata": { "propertyName": "string" } }' ```