openapi: 3.2.0 info: version: '2.0' title: Admin User Management API description: "
\n

Overview

\n Use the Admin API to manage users, permissions, and other administrative functions across your Demandbase account.\n
\n\n
\n\n> **Rate Limiting** \n>
Admin API endpoints are restricted to 90 requests per minute per HTTP method (e.g., GET, POST, PUT, DELETE).\n>
If the limit is exceeded, the API will respond with an HTTP 429 Too Many Requests error.\n>

Recommendations to Stay Within Limits:\n\n**Example Use**\n```text\ncurl --location 'https://uapi.demandbase.com/admin/v1/users' \\\n--header 'Authorization: Bearer '\n```\n**Response**\n```json\n{\n \"totalCount\": 1,\n \"data\": [\n {\n \"name\": \"Test User\",\n \"email\": \"TestUser@demandbase.com\",\n \"externalIds\": [],\n \"permissionSets\": [\n \"Demandbase One for Sales\",\n \"General User\"\n ],\n \"department\": \"Ad Operations\",\n \"view\": \"Standard View\",\n \"workspaces\": [\n \"Default workspace\"\n ],\n \"date_created\": \"2025-03-11T05:38:17.007Z\",\n \"jobFunction\": \"Other\"\n }\n ]\n}\n```\n
" servers: - url: https://uapi.demandbase.com security: - token: [] tags: - name: User Management paths: /admin/v1/user: post: tags: - User Management summary: Create new user description: '

Overview


Creates a new user within your Demandbase account.
' requestBody: description: '

Request Body


The Create User API request body defines key attributes for a user, including identification, permissions, and default interface (view) preferences.' required: true content: application/json: schema: $ref: '#/components/schemas/User' responses: '201': description: '
Description: User successfully created
Return: JSON object representing the new user
' content: application/json: schema: $ref: '#/components/schemas/NewUserResponse' example: externalId: ext-123abc email: user@example.com fullName: Alex Morgan permissionSets: - Admin department: Customer Success view: Standard View workspaces: - Default workspace jobFunction: Other '400': description: '
Description: Invalid request body or missing required fields
Return: JSON error object
' content: application/json: schema: type: object properties: code: type: integer details: type: array items: type: string requestId: type: string x-examples: Example 1: code: 400 details: - 'department: test is invalid' - 'permissionSet: test is invalid' requestId: cf89308c-7cb9-437a-ac56-2f9804199a3b '401': description: '
Description: Authentication failed or missing credentials
Return: JSON error status object
' content: application/json: schema: type: object properties: status: type: string x-examples: Example 1: status: Authentication Failed - Unauthorized. '403': description: '
Description: Returned if the authenticated credentials lacks the "User Management" permission
Return: JSON error object
' content: application/json: schema: type: object properties: code: type: integer details: type: string requestId: type: string x-examples: Example 1: code: 403 details: You are not authorized to perform this action. requestId: 2159a31a-2b41-4672-9e36-596137771cc9 '500': description: '
Description: Returned if there was an issue on the server side and the user could not be created.
' security: - token: [] servers: - url: https://uapi.demandbase.com put: tags: - User Management summary: Update users description: '

Overview


Updates an existing user within your Demandbase account.
' operationId: put-users requestBody: description: '

Request Body


The Update User API request body defines key attributes for a user, including identification, permissions, and default interface (view) preferences.' required: true content: application/json: schema: $ref: '#/components/schemas/User' responses: '200': description: '
Description: User successfully updated
Return: JSON object representing the updated user
' content: application/json: schema: $ref: '#/components/schemas/NewUserResponse' example: externalId: ext-123abc email: user@example.com fullName: Alex Morgan permissionSets: - Admin department: Customer Success view: Standard View workspaces: - global workspace jobFunction: Other '400': description: '
Description: Invalid request body or missing required fields
Return: JSON error object
' content: application/json: schema: type: object properties: code: type: integer details: type: array items: type: string requestId: type: string '401': description: '
Description: Authentication failed or missing credentials
Return: JSON error status object
' content: application/json: schema: type: object properties: status: type: string x-examples: Example 1: status: string '403': description: '
Description: Returned if the authenticated user lacks the "User Management" permission
Return: JSON error object
' content: application/json: schema: type: object properties: code: type: string details: type: string requestId: type: string x-examples: Example 1: code: integer details: string requestId: string '500': description: '
Description: Returned if there was an issue on the server side and user could not be updated.
' security: - token: [] servers: - url: https://uapi.demandbase.com /admin/v1/users: get: tags: - User Management summary: Get list of users description: '

Overview


This endpoint allows you to retrieve users with pagination (max pageSize 100) and filters for departments, views, permissionSets, and workspaces.
' parameters: - name: departments in: query description: '
comma separated list of departments
Example: Marketing,Sales
' schema: type: string - name: views in: query description: '
comma separated list of views
Example: Standard View,Marketing View
' schema: type: string - name: permissionSets in: query description: '
comma separated list of permission sets
Example: General User,Admin
' schema: type: string - name: workspaces in: query description: '
comma separated list of workspaces (if enabled)
Example: global workspace
' schema: type: string - name: pageNo in: query description: '
Default: 1
Example: 5
' schema: type: integer - name: pageSize in: query description: '
Default: 25
Example: 25
Max: 100
' schema: type: integer responses: '200': description: '
Returns a paginated list of users.
' content: application/json: schema: $ref: '#/components/schemas/UserListResponse' example: totalCount: 2 data: - name: Alex Morgan email: alex.morgan@example.com externalIds: - ext-12345 permissionSets: - General User - Admin department: Engineering view: Standard View workspaces: - Default workspace date_created: '2024-01-15T12:34:56Z' jobFunction: Other - name: Jordan Lee email: jordan.lee@example.com externalIds: [] permissionSets: - General User department: Marketing view: Standard View workspaces: - Default workspace date_created: '2023-11-02T08:15:30Z' jobFunction: Marketing '400': description: '
Returned if the user specification in the request does not match the required format.
' '401': description: '
Returned if the authentication credentials are missing or invalid
' '403': description: '
Returned if the authenticated user lacks the "User Management" permission
' '500': description: '
Returned if there was an issue on the server side and could not get list of users.
' security: - token: [] servers: - url: https://uapi.demandbase.com /admin/v1/user/{id}: get: tags: - User Management summary: Get a user by external id description: '

Overview


The Get Users By External ID API allows you to retrieve a specific user''s data.
' parameters: - name: id in: path description: '
An external client defined identifier for the user (set when creating the user)
Example: dcb34525-2baa-4f54-8c11-9e6175ecbc74
' required: true schema: type: string responses: '200': description: '
Returns the requested user details matching the provided ID
' content: application/json: schema: $ref: '#/components/schemas/GetUserResponse' example: name: Alex Morgan email: user@example.com externalIds: - ext-123abc permissionSets: - Admin department: Customer Success view: Standard View workspaces: - Default workspace date_created: '2025-08-22T20:43:44.888Z' jobFunction: Other '400': description: '
Returned if the user specification in the request body does not match the required format.
' '401': description: '
Returned if the authentication credentials are missing or invalid.
' '403': description: '
Returned if the authenticated user lacks the "User Management" permission
' '404': $ref: '#/components/responses/404errorNoUserFound' '500': description: '
Returned if there was an issue on the server side and could not find the user.
' security: - token: [] servers: - url: https://uapi.demandbase.com delete: tags: - User Management summary: Delete user using external user id description: '

Overview


Deletes an existing user from your Demandbase account.
' operationId: delete-users parameters: - name: id in: path description: '
An external client defined identifier for the user (set when creating the user)
Example: dcb34525-2baa-4f54-8c11-9e6175ecbc74
' required: true schema: type: string responses: '204': description: '
Returned if the user is successfully deleted.
' '400': description: '
Returned if the user specification in the request body does not match the required format.
' '401': description: '
Returned if the authentication credentials are missing or invalid.
' '403': description: '
Returned if the authenticated user lacks the "User Management" permission
' '404': $ref: '#/components/responses/404errorNoUserFound' '500': description: '
Returned if there was an issue on the server side and user could not be deleted.
' security: - token: [] servers: - url: https://uapi.demandbase.com components: responses: 404errorNoUserFound: description: '
Returned if the provided external user id does not exist in DemandBase
' content: application/json: schema: $ref: '#/components/schemas/ErrorDto' examples: Example 1: $ref: '#/components/examples/errorNoUserFoundExample' schemas: UserListResponse: type: object properties: totalCount: type: integer data: type: array items: $ref: '#/components/schemas/UserListItem' required: - totalCount - data UserListItem: type: object properties: name: type: string email: type: string externalIds: type: array items: type: string permissionSets: type: array items: type: string department: type: string view: type: string workspaces: type: array items: type: string date_created: type: string format: date-time jobFunction: type: string GetUserResponse: type: object properties: name: type: string description: '
The user''s full name
' email: type: string description: '
The user''s email address
' externalIds: type: array description: '
A list of client defined user IDs
' items: type: string permissionSets: type: array description: '
Permissions of the user
' items: type: string department: type: string description: '
Department of the user
' view: type: string description: '
View of the user
' workspaces: type: array description: '
Workspaces of the user if applicable
' items: type: string date_created: type: string description: '
Date when the user was created
' format: date-time jobFunction: type: string description: '
Job function of the user
' ErrorDto: type: object properties: errorCode: type: string description: '
This is a error code
' errorMessage: type: string description: '
A clear text description of the error
' NewUserResponse: type: object properties: fullName: type: string description: '
Name of the user
' email: type: string description: '
Email address of the user
' externalId: type: string description: '
User ID in client''s system
' permissionSets: type: array description: '
Permissions of the user
' items: type: string department: type: string description: '
Department of the user
' view: type: string description: '
View of the user
' workspaces: type: array description: '
Workspaces of the user if applicable
' items: type: string jobFunction: type: string description: '
Job function of the user
' dateCreated: type: string description: '
Date when the user was created
' format: date User: type: object properties: fullName: type: string description: '
The full name of the user.
' email: type: string description: '
The email address of the user
' externalId: type: string description: '
An external identifier for the user, such as user id in your user management system.
' permissionSets: type: array description: '
An array of permission sets assigned to the user. These must match the permission sets configured in the DB1 platform.
More info: Create and Manage Permission Sets
' items: type: string department: type: string description: '
The department the user belongs to, used for organizational grouping.
More info: Create and Manage Departments
' view: type: string description: '
The default view that defines which interface and columns the user sees upon login.
More info: Create and Manage User Views
' required: - fullName - email - externalId - permissionSets - department - view examples: errorNoUserFoundExample: value: errorCode: 400-115 errorMessage: 'No user found with externalId: {NewUserResponse}.externalId' securitySchemes: token: type: http description: '[How To Generate Bearer Tokens](https://developer.demandbase.com/docs/auth-api)' scheme: bearer