Qualtrics User Management API Guide

Auth method: API Token (X-API-TOKEN header)

Setup steps

1. Log in to Qualtrics and navigate to Account Settings > Qualtrics IDs.
2. Locate or generate your API Token under the 'API' section.
3. Include the token in all API requests as the header: X-API-TOKEN: .
4. Identify your datacenter ID from the same Qualtrics IDs page (e.g., 'iad1', 'fra1') and substitute it into the base URL.

List Users

• Method: GET
• URL: https://{datacenterid}.qualtrics.com/API/v3/users
• Watch out for: Pagination uses a full URL in 'nextPage'; iterate until nextPage is null.

Request example

GET /API/v3/users?pageSize=100 HTTP/1.1
Host: iad1.qualtrics.com
X-API-TOKEN: <token>

Response example

{
  "result": {
    "elements": [{"id":"URH_abc","username":"user@example.com"}],
    "nextPage": "https://iad1.qualtrics.com/API/v3/users?pageSize=100&offset=100"
  },
  "meta": {"httpStatus": "200 - OK"}
}

Get User

• Method: GET
• URL: https://{datacenterid}.qualtrics.com/API/v3/users/{userId}
• Watch out for: Use the Qualtrics user ID (URH_...), not the email address, as the path parameter.

Request example

GET /API/v3/users/URH_abc123 HTTP/1.1
Host: iad1.qualtrics.com
X-API-TOKEN: <token>

Response example

{
  "result": {
    "id": "URH_abc123",
    "username": "user@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "user@example.com",
    "status": "active"
  },
  "meta": {"httpStatus": "200 - OK"}
}

Create User

• Method: POST
• URL: https://{datacenterid}.qualtrics.com/API/v3/users
• Watch out for: userType must be a valid type for your brand; invalid types return a 400 error.

Request example

POST /API/v3/users HTTP/1.1
Host: iad1.qualtrics.com
X-API-TOKEN: <token>
Content-Type: application/json

{"username":"new@example.com","firstName":"John","lastName":"Smith","email":"new@example.com","userType":"UT_RESPONDENT"}

Response example

{
  "result": {"id": "URH_newuser123"},
  "meta": {"httpStatus": "200 - OK"}
}

Update User

• Method: PUT
• URL: https://{datacenterid}.qualtrics.com/API/v3/users/{userId}
• Watch out for: Qualtrics uses PUT (not PATCH) for user updates; only include fields you wish to change.

Request example

PUT /API/v3/users/URH_abc123 HTTP/1.1
Host: iad1.qualtrics.com
X-API-TOKEN: <token>
Content-Type: application/json

{"firstName":"Jane","status":"disabled"}

Response example

{
  "result": {},
  "meta": {"httpStatus": "200 - OK"}
}

Delete User (Disable)

• Method: DELETE
• URL: https://{datacenterid}.qualtrics.com/API/v3/users/{userId}
• Watch out for: Deleting a user may disable rather than permanently remove the account depending on brand settings; verify behavior in your environment.

Request example

DELETE /API/v3/users/URH_abc123 HTTP/1.1
Host: iad1.qualtrics.com
X-API-TOKEN: <token>

Response example

{
  "result": {},
  "meta": {"httpStatus": "200 - OK"}
}

Get Authenticated User (Whoami)

• Method: GET
• URL: https://{datacenterid}.qualtrics.com/API/v3/whoami
• Watch out for: Useful for validating token identity and resolving the caller's userId and datacenter.

Request example

GET /API/v3/whoami HTTP/1.1
Host: iad1.qualtrics.com
X-API-TOKEN: <token>

Response example

{
  "result": {
    "userId": "URH_abc123",
    "username": "admin@example.com",
    "brandId": "mybrand"
  },
  "meta": {"httpStatus": "200 - OK"}
}

List Divisions

• Method: GET
• URL: https://{datacenterid}.qualtrics.com/API/v3/divisions
• Watch out for: Division IDs are required when assigning users to divisions during creation or update.

Request example

GET /API/v3/divisions HTTP/1.1
Host: iad1.qualtrics.com
X-API-TOKEN: <token>

Response example

{
  "result": {
    "elements": [{"id":"DV_abc","name":"Sales Division"}],
    "nextPage": null
  },
  "meta": {"httpStatus": "200 - OK"}
}

Get User API Token

• Method: GET
• URL: https://{datacenterid}.qualtrics.com/API/v3/users/{userId}/apitoken
• Watch out for: Requires Brand Administrator privileges; returns the target user's API token, not the caller's.

Request example

GET /API/v3/users/URH_abc123/apitoken HTTP/1.1
Host: iad1.qualtrics.com
X-API-TOKEN: <admin_token>

Response example

{
  "result": {"apiToken": "abc123tokenvalue"},
  "meta": {"httpStatus": "200 - OK"}
}

• Rate limits: Qualtrics enforces rate limits per API token. The official docs note limits exist but do not publicly publish specific numeric thresholds per plan tier.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: Rate limit details are not publicly documented. Qualtrics returns HTTP 429 when limits are exceeded. Contact Qualtrics support for specific limits applicable to your license.

• Pagination method: token

• Default page size: 100

• Max page size: 100

• Pagination pointer: nextPage

• Webhooks available: No

• Webhook notes: Qualtrics does not offer native webhooks for user management events (user created, updated, deleted). Survey response events can trigger webhooks, but user lifecycle events are not supported.

• Alternative event strategy: Poll the List Users endpoint periodically to detect changes, or use SCIM provisioning with a supported IdP (Okta, Entra ID) for automated lifecycle management.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (requires SSO to be configured first)

• Endpoint: https://{datacenterid}.qualtrics.com/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PUT /Groups/{id}, DELETE /Groups/{id}

Limitations:

• SSO must be configured and active before SCIM can be enabled.
• Enterprise plan required; not available on self-serve or lower tiers.
• Officially documented IdP integrations are Okta and Microsoft Entra ID (Azure AD); other IdPs may require custom SCIM connector configuration.
• SCIM token is separate from the standard API token and is generated within the SSO/SCIM configuration screen.
• Group provisioning maps to Qualtrics Divisions or Groups depending on configuration.

Provisioning a new user requires a POST to /API/v3/users with username (email), firstName, lastName, email, and a valid userType. The userType value must match a type licensed for the brand; invalid values return a 400.

The response returns the Qualtrics user ID (URH_...), which is the required path parameter for all subsequent user-specific calls - email address cannot be substituted. Division assignment requires a follow-up PUT with divisionId.

Deprovisioning should follow a two-step pattern: PUT status: disabled to immediately block access, then optionally DELETE if permanent removal is required by data retention policy.

DELETE behavior - whether it disables or permanently removes the account - varies by brand configuration and should be validated before automation. If SCIM is active, deprovisioning via the IdP triggers the SCIM DELETE or deactivation flow automatically.

For bulk sync via SCIM with Okta or Entra ID, the SCIM bearer token is generated separately within Admin → SSO → SCIM Provisioning. SSO must be fully active before the token generation option appears.

The SCIM endpoint supports GET, POST, PUT, PATCH, and DELETE on /scim/v2/Users, plus group operations that map to Qualtrics Divisions or Groups depending on configuration.

Provision a new employee user account

1. Authenticate using a Brand Administrator API token.
2. POST /API/v3/users with required fields: username (email), firstName, lastName, email, userType.
3. Capture the returned 'id' (URH_...) from the response.
4. If divisions are used, PUT /API/v3/users/{id} with the appropriate divisionId.
5. Optionally set accountExpirationDate for contractors or temporary staff.

Watch out for: userType must match a type licensed for your brand. Confirm valid userTypes with your Qualtrics account team or by inspecting existing users via GET /users.

Deprovision a departing employee

1. Resolve the user's Qualtrics ID by calling GET /API/v3/users and filtering by username/email, or use a stored mapping.
2. Call PUT /API/v3/users/{userId} with status set to 'disabled' to immediately block access.
3. Optionally call DELETE /API/v3/users/{userId} if permanent removal is required per your data retention policy.
4. If SCIM is configured, deprovisioning via the IdP (Okta/Entra) will automatically trigger the SCIM DELETE or deactivation flow.

Watch out for: DELETE behavior (disable vs. permanent removal) may vary by brand configuration. Test in a non-production environment before automating.

Bulk-sync users via SCIM with Okta

1. Confirm Enterprise plan and active SSO configuration in Qualtrics Admin > SSO.
2. Navigate to Admin > SSO > SCIM Provisioning and generate a SCIM Bearer Token.
3. In Okta, add the Qualtrics application from the Okta Integration Network.
4. Configure the SCIM base URL as https://{datacenterid}.qualtrics.com/scim/v2 and paste the Bearer Token.
5. Enable provisioning features: Push New Users, Push Profile Updates, Deactivate Users.
6. Assign users/groups in Okta; Okta will POST /scim/v2/Users for each assigned user.
7. Verify provisioned users appear in Qualtrics Admin > Users.

Watch out for: The SCIM token is distinct from the REST API token. SSO must be fully active before the SCIM token generation option appears in the admin UI.

The primary integration trap is datacenter-specificity: the base URL is not a single global endpoint. Hardcoding a datacenter ID that differs from the account's actual datacenter produces authentication failures that are easy to misdiagnose as token or permission errors. Always resolve the datacenter ID from the GET /whoami response or a stored, account-verified configuration value.

The REST API uses PUT for user updates - not PATCH. Sending only changed fields in a PUT may overwrite unspecified fields with nulls; include all fields you intend to retain. PATCH is only available via the SCIM endpoint.

This distinction matters when building an identity graph that tracks permission state across users: a partial PUT intended to update divisionId can inadvertently clear the permissions object if the full user record is not reconstructed before the call.

The permissions field is a map of boolean toggles, and its interaction with applied Permission Sets is not fully transparent via the API. A user may have a Permission Set applied at the division level that is not reflected in the per-user permissions object returned by GET.

Any identity graph built on top of the Qualtrics API must account for this layered resolution order - brand default, then division default, then per-user override - to accurately represent effective access state.