Managing Participants

Understanding EX, CX, and BX Directories

At Qualtrics, some API endpoints are denoted by initials to distinguish the group of users and services the API belongs to.

This guide details managing participants within these groups:

Employee Experience (EX) | Customer Experience (CX) | Brand Experience (BX)

Each directory manages a unique set of users — it is important to know the differences.

The Key Difference Between EX, CX, and BX Directories

Each directory has a unique set of users:

• EX (Employee Experience) Directory: Lists all participants and administrators in your organization. For more information, see the Qualtrics guide for Employee Directory (EX).
• CX (Customer Experience) Directory: Manages users with access to CX dashboards. For more information, see the Qualtrics guide for Managing CX Dashboard Users.
• BX (Brand Experience) Directory: Manages users with access to BX dashboards. For more information, see the Qualtrics guides for BX Dashboards.

For the directoryId property, use:

• ex for employee directory
• cx for CX directory
• bx for BX directory

Managing Participants and Users with Import Operations

Use Import operations to manage users and participants. Users are individuals with Qualtrics accounts and login credentials, while participants are survey respondents with various metadata depending on the survey details.

Employee Directory

Summary	Description
Import Participants	Start participants' addition or updates to the specified employee directory.
Export Participants	Start participants' export from the specified employee directory.
Delete Participants	Start participants' deletion from the specified employee directory.
Get Global Participant	Retrieves the specified participant in the employee directory.
Get All Participants Post	Retrieves all participants in the specified directory.

Import Participants endpoint used for both new and updated participants

Use the Import Participants endpoint, which uses the POST method, to both add new participants and update existing ones.

EX projects

Summary	Description
Import participants	Start addition of new or existing participants to the specified EX project. Existing participants should be in employee directory based on uniqueIdentifier. If new participants are added, they are also added to employee directory.
Import 360 Subjects	Start addition of new or existing subjects to the specified EX 360 project. Existing subjects should be in employee directory based on uniqueIdentifier. If new subjects are added, they are also added to employee directory.
Import 360 Evaluators	Start addition of new or existing evaluators to the specified EX 360 project. Existing evaluators should be in employee directory based on uniqueIdentifier. If new evaluators are added, they are also added to employee directory.
Export participants	Start participants export from the specified EX project.
Delete participants	Start participants deletion from the specified EX project.
Copy participants from the Employee Directory	Copy participants identified by given list of uniqueIdentifier from employee directory to project. Participant's metadata in employee directory is also copied into project.
Copy 360 Subjects from the Employee Directory	Copy subjects identified by given list of uniqueIdentifier from employee directory to project. Subject's metadata in employee directory is also copied into project.
Copy 360 Evaluators from the Employee Directory	Copy evaluators identified by given list of uniqueIdentifier from employee directory to project. Evaluator's metadata in employee directory is also copied into project.
Get Specific Participant	Retrieve details of a specific participant, such as firstName, lastName, email, username, userId, participantId, uniqueIdentifier.
Get Participants Post	Return a list of all participants in a specific EX project, including participant data, such as firstName, lastName, email, username, userId, participantId, uniqueIdentifier.

For information on 360 Subject and Evaluator Imports, refer to the Qualtrics guide for Adding Subjects, Evaluators, & Managers (360)

CX and BX Directories

Summary	Description
Import Participants	Start participants' addition or updates to the specified directory.
Export Participants	Start participants' export from the specified directory.
Delete Participants	Start participants' deletion from the specified directory.
Get Global Participant	Retrieves the specified participant in the directory.
Get All Participants Post	Retrieves all participants in the specified directory.

How to Provide Custom UserNames

If you’d like to specify a different username for your participants, add a username column and define a username. This username is what your participants will use to log in to view dashboards.

Disable Users Instead of Deleting

Instead of deleting a user, you can update the user's status to disabled with the Import Users.

Directory APIs and Asynchronous Jobs

Import Participants, Export Participants, and Delete Participants requests can involve large datasets and are asynchronous operations. To track the status of these operations, call the APIs in sequence:

1. Call the first API to create the job for the corresponding operation (e.g., Import Participants). The API response includes the property jobId, a unique identifier for that job.
2. Call the second (GET Status) with the jobId as a path parameter. This call polls the server for the operation status. To avoid excessive API calls, add a delay of at least 10 seconds between status requests. The API response includes a resultId, a unique identifier for that result.
3. Call the final API when the previous API returns progressPercent = 100, in which case a resultId will be present in the response as well. Then call the final API ending in /results/:resultId with the resultId as a path parameter to request the operation results.

Job Queues

Employee Directory and EX Projects: EX Directory and EX Projects support up to 10 jobs queued for your organization. Requests to queue more than 10 jobs return a 409 error.

BX & CX Directories: Queues are not supported for the BX or CX Directory. Attempting to start another job while one is running will result in a 409 error.

Simplify Your Workflow by Running One Job at a Time

Managing a queue with public APIs can be difficult, so, to simplify your workflow:

1. Start a job.
2. Poll for status.
3. Wait for job completion.
4. Start a new job.

Reference the Correct Users/Participant Directory

Users/Participant metadata is stored in a specific directory or project, even if the Users/Participant exists in multiple directories. Ensure you reference the correct directory when you update Users/Participant metadata. Use of the wrong API call or updates to metadata in the wrong directory may lead to accidental overwrites or deletions of data.

Job Management

The processing order for jobs is first in, first out for each job context (where the job was started). Jobs in different projects can run concurrently, but only one job from each context can run at one time. Employee Directory jobs will not start until all jobs started in a different project or directory are complete. Also, no other jobs can run concurrently with Employee Directory jobs.

Here is an example queue for EX Employee Directory showing order of job processing based on the jobs' contexts and projects.

Jobs	Process
Job 1: Project A	Job 1 starts running immediately because there are no other jobs running for this organization.
Job 2: Project B	Job 2 can run simultaneously with Job 1 because they are in different projects
Job 3: Employee Directory	Job 1 and Job 2 must finish before Job 3 can run because Job 3 is a Employee Directory job. When they both complete, Job 3 will start
Job 4: Employee Directory	Job 3 must finish before Job 4 can run because they're in the same job context (Employee Directory). When Job 3 completes, Job 4 will start.
Job 5: Project A	Job 4 must finish before Job 5 can run—it has a different context than the Employee Directory.
Job 6: Project A	Job 5 must finish before Job 6 can run because they are in the same project.

Additional Details for Import APIs: Participants and Their Associated User Objects

How Participants are linked to Users. (username matching, multiple brands)

• Use Import operations to manage participants and users. For participants, the UniqueID must be unique for all participants in your organization (i.e., uniqueIdentifier). For users, the username must be unique for all users in your organization
• Every participant must be a user; however, users don't have to be participants.
• Imports can be used to manage users and participants in the following ways:
  • Create a new participant for an existing user
  • Create a new participant and new user
  • Update an existing participant and existing user
• Participants are linked to their corresponding user during import either by the username field or the Email field.
  • If you include the username column in an import, either a new user is created with a customer username, or, if a user already exists, the user data is updated with the new custom username.
  • If you do not include a column for username, the username defaults to the same value as Email. Because usernames must be unique, the Email value must now be unique for each participant.
• Usernames across multiple brands have different functionality for SSO and non-SSO brands:
  • For organizations with SSO, if you have multiple brands within your organization, you can create new participants or users by specifying a unique username and BrandID for each participant. Nevertheless, the participant must have a unique username across all brands in the organization.
  • For organizations without SSO, participants can utilize the same username across multiple brands.
• Additional details for organizations with SSO
  • If you use single sign-on (SSO), refer to the Qualtrics guide on Managing Users & Brands with SSO
  • If you use SSO with separate brands for EX and CX, there is not a brand selection page during login because the username for a user is different for different brands.

Example of UserNames for an EX vs CX Brand

When your organization has two brands enabled for SSO: exampleCXBrandId and exampleEXBrandId, usernames must maintain uniqueness across both brands.

Both exampleCXBrandId and exampleEXBrandId are enabled for SSO

Let's consider a practical example username@test.com as our example:

For a successful import, you'd import two users with usernames:

• username@test.com#exampleCXBrandId associated with the exampleCXBrandId
• username@test.com#exampleEXBrandId associated with the exampleEXBrandId

Here is an unsuccessful import where the usernames are identical:

username@test.com#exampleCXBrandId associated with the exampleCXBrandId username@test.com#exampleCXBrandId associated with the exampleEXBrandId

Best Practices

1. Ensure you reference the correct directory when updating participant metadata to avoid accidental overwrites or deletions of data.
2. To avoid excessive API calls, add a delay of at least 10 seconds between status requests when polling the server for the operation's status.
3. Simplify your jobs by processing one job at a time when using Qualtrics Public APIs.
4. When importing participants, specify custom usernames by including a username column in your import file. Ensure that these custom usernames are unique within your organization.