Brandwatch User Management API Guide

Auth method: OAuth 2.0 (client credentials)

Setup steps

1. Log in to Brandwatch and navigate to Settings > API Access.
2. Create an API client to obtain a client_id and client_secret.
3. POST to https://api.brandwatch.com/oauth/token with grant_type=client_credentials, client_id, and client_secret to receive an access_token.
4. Include the access_token as a Bearer token in the Authorization header of all subsequent API requests.

Required scopes

List users in account

• Method: GET
• URL: https://api.brandwatch.com/accounts/{accountId}/users
• Watch out for: accountId must be obtained separately; users without admin API client permissions will receive 403.

Request example

GET /accounts/12345/users?page=0&pageSize=100
Authorization: Bearer {access_token}

Response example

{
  "resultsTotal": 25,
  "results": [
    {"id": 1, "username": "user@example.com", "role": "analyst"}
  ]
}

Get single user

• Method: GET
• URL: https://api.brandwatch.com/accounts/{accountId}/users/{userId}
• Watch out for: Returns 404 if userId does not belong to the specified accountId.

Request example

GET /accounts/12345/users/67890
Authorization: Bearer {access_token}

Response example

{
  "id": 67890,
  "username": "user@example.com",
  "role": "analyst",
  "active": true
}

Create user

• Method: POST
• URL: https://api.brandwatch.com/accounts/{accountId}/users
• Watch out for: User receives an invitation email; account must have available user seats. Auto-provisioning is NOT supported - seats must exist.

Request example

POST /accounts/12345/users
Content-Type: application/json
{
  "username": "newuser@example.com",
  "role": "analyst"
}

Response example

{
  "id": 99001,
  "username": "newuser@example.com",
  "role": "analyst",
  "active": true
}

Update user

• Method: PUT
• URL: https://api.brandwatch.com/accounts/{accountId}/users/{userId}
• Watch out for: Full object replacement semantics may apply; confirm fields not included are not cleared.

Request example

PUT /accounts/12345/users/67890
Content-Type: application/json
{
  "role": "admin"
}

Response example

{
  "id": 67890,
  "username": "user@example.com",
  "role": "admin"
}

Delete user

• Method: DELETE
• URL: https://api.brandwatch.com/accounts/{accountId}/users/{userId}
• Watch out for: Deletion is permanent. Ensure data ownership/transfer is handled before removing a user.

Request example

DELETE /accounts/12345/users/67890
Authorization: Bearer {access_token}

Response example

HTTP 204 No Content

Get account details (to retrieve accountId)

• Method: GET
• URL: https://api.brandwatch.com/accounts
• Watch out for: The accountId returned here is required for all user-management endpoint calls.

Request example

GET /accounts
Authorization: Bearer {access_token}

Response example

{
  "results": [
    {"id": 12345, "name": "My Organization"}
  ]
}

• Rate limits: Brandwatch enforces rate limits on API requests but does not publicly document specific numeric thresholds per plan. Limits are applied per API client/token.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: HTTP 429 is returned when limits are exceeded. Specific limits are communicated via account management. Retry with exponential backoff is recommended.
• Pagination method: offset
• Default page size: 100
• Max page size: 500
• Pagination pointer: page / pageSize

• Webhooks available: No
• Webhook notes: Brandwatch does not publicly document webhook support for user lifecycle events (create, update, delete).
• Alternative event strategy: Poll the GET /accounts/{accountId}/users endpoint periodically to detect changes.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• Native SCIM provisioning is not supported by Brandwatch.
• Limited user sync is available via Okta integration only, but this is SSO-based and does not constitute full SCIM 2.0 provisioning.
• Admin must manually create user accounts; auto-provisioning is not available.
• An SSO setup fee applies for Okta/Entra integrations.

Three primary automation scenarios are supported by the API. Onboarding: POST to /accounts/{accountId}/users with username and role; the user receives an invitation email and must activate their account manually - a seat must exist in the contract or the call will fail.

Role promotion: PUT to /accounts/{accountId}/users/{userId} with the updated role field; confirm whether full-replace semantics apply and include all required fields to avoid unintentional data loss.

Offboarding: DELETE to /accounts/{accountId}/users/{userId} is permanent and immediate; content ownership transfer has no API support and must be handled in the UI before deletion. No webhooks are available for user lifecycle events; polling GET /accounts/{accountId}/users is the only mechanism for detecting changes.

Onboard a new analyst user

1. POST to https://api.brandwatch.com/oauth/token to obtain an access_token using client_id and client_secret.
2. GET https://api.brandwatch.com/accounts to retrieve the accountId for your organization.
3. POST https://api.brandwatch.com/accounts/{accountId}/users with body {username, role: 'analyst'} to create the user.
4. User receives an invitation email to set their password and activate the account.

Watch out for: Ensure a user seat is available in the contract before attempting creation; the API will return an error if seats are exhausted.

Promote a user to admin role

1. GET https://api.brandwatch.com/accounts/{accountId}/users to find the target user's userId.
2. PUT https://api.brandwatch.com/accounts/{accountId}/users/{userId} with body {role: 'admin'} to update the role.

Watch out for: Confirm whether PUT uses full-replace semantics; include all required fields to avoid unintentional data loss.

Offboard a departing user

1. GET https://api.brandwatch.com/accounts/{accountId}/users to locate the user's userId by email.
2. Reassign or export any dashboards/reports owned by the user via the Brandwatch UI (no API for ownership transfer documented).
3. DELETE https://api.brandwatch.com/accounts/{accountId}/users/{userId} to remove the user.

Watch out for: Deletion is irreversible. Data owned by the deleted user may be lost if not transferred beforehand. No automated offboarding via SCIM is available.

The API does not eliminate the core provisioning constraint: seats are contract-gated, auto-provisioning is not supported, and SCIM is absent. Attempting to create a user beyond the contracted seat limit returns an error with no self-serve resolution path. OAuth tokens have a finite expiry and require refresh logic using the client credentials flow.

The accountId is not surfaced in the UI and must be retrieved programmatically via GET /accounts before any user call can be made - teams that skip this step will encounter 403 or 404 errors. The developer portal may lag behind production endpoint changes; validate critical calls with Brandwatch support before deploying to production.