Setup

In this article:

• REST HTTP/SSL method
• API request details
• URL parameters and responses

REST HTTP/SSL method

This method for passing us your org structure allows you to send us your structure and to request status updates using the endpoint.

API request details

This section describes how to submit your users and teams CSV files for syncing your organization structure into Pluralsight. After submitting the files, you will receive a statusURL to check the status of the sync job.

API requests should be delivered to an endpoint appended to the production URL https://integrations-api.pluralsight.com.

Note: Remove special characters from the CSV files (e.g., quotation marks, commas) to avoid parsing errors.

Sync Process Options

• Dry Run: By default, the sync process is a "dry run", meaning that the operations to sync your structure will be generated and stored but not applied. To apply the operations, set the dryRun parameter in the URL to false.

• Email Invitations: You can choose to run the sync process without inviting managers to Pluralsight via email. The sync will still apply all other operations, and you can view your team structure within Pluralsight. Managers not already in Pluralsight will not receive an email invitation or be added to the team.

URL parameters and responses

Dry run (dryRun)

What It Does:

• Dry Run lets you test the sync process without actually making changes. It shows you what would happen if the sync were applied, allowing you to review the results first.

Default Setting:

• true (meaning changes are not applied by default)

How to Use:

• To apply changes, add ?dryRun=false to the end of your endpoint URL.

Example URL:

• https://integrations-api.pluralsight.com/sync-users?dryRun=false

Strict mode (exitOnError)

What It Does:

• Strict Mode stops the sync process if any errors are found. Useful for initial setups or testing. Only the validation of files is completed if errors are detected.

Default Setting:

• false (errors are logged, and sync continues)

How to Use:

• To stop on errors, add ?exitOnError=true to the end of your endpoint URL.

Example URL:

• https://integrations-api.pluralsight.com/sync-users?exitOnError=true

Turning off manager invites

What It Does:

• You can choose not to send email invitations to managers not yet in Pluralsight.

Default Setting:

• true (invitations are sent by default)

How to Use:

• To disable invites, add ?sendManagerInvites=false to the end of your endpoint URL.
• Combine with dryRun=false to ensure no invitations are sent.

Example URL:

• https://integrations-api.pluralsight.com/sync-users?dryRun=false&sendManagerInvites=false

Additional Options:

• Toggle in Pluralsight Integration Portal: Disable manager invite emails through a setting in the portal.
• SendManagerInvites Flag: Use this flag to control invite generation.

Syncing only a part of your organization/retain manually created teams

What It Does:

• Allows you to sync only specific parts of your organization by specifying top-level teams. Manually created teams not affected by the sync will be preserved.

How to Use:

• Add ?rootTeamIds=id1,id2 to the end of your endpoint URL, replacing id1, id2 with the IDs of the top-level teams you want to sync.

Example URL:

• https://integrations-api.pluralsight.com/sync-users?rootTeamIds=id1,id2

Possible responses

If you've provided only the users file:

“status”: “Awaiting teams file”

Status Code: 200 Content-type: application/json

Note: We do not begin data validation on either file until we have both files. Once both files have been provided you will either get a success or an error response with further information.

If you've provided both files:

“status”: “processing”,
“statusUrl”: “https://integrations-api.pluralsight.com/sync-users/:id/status”

Status Code: 200 Content-type: application/json

Note: You can then use the returned statusUrl to poll for status updates. See below.

If you have uploaded both files but provided invalid data or headers in one or both files:

“status”: “Invalid data”,
“errors”: [
"Missing header(s) for [either users or teams] file: [list of headers missing]",
...
]

Request status of sync job

What it does:

• This endpoint allows you to request updates to a sync job using the url returned when you finished uploading both files.

Example url:

• GET /sync-users/:id/status

Note: :id is the job ID from the URL returned after submitting the users.csv and teams.csv files.

Possible Responses

In Progress

“status”: “processing”
“dryRun”: true|false

Status Code: 200

Completed

“status”: “completed”,
“dryRun”: true|false,
“listOfOperations”: [‘operation one’, operation two’],
“errors’: []

Status Code: 200

Completed with Errors

“status”: “completedWithErrors”,
“dryRun”: true|false,
“listOfOperations”: [‘operation one’, operation two’],
“errors’: [‘error one’, ‘error two’, ...]

Status Code: 200

Full example

curl 
  -T teams.csv 
  -X POST 
  -H “Authorization: Bearer [insert-your-api-key-here]“ 
  -H 'Content-Disposition: attachment; filename="teams.csv"' 
  -H “Content-Type: text/csv“ 
  https://integrations-api.pluralsight.com/sync-users 
  
curl 
  -T users.csv 
  -X POST 
  -H “Authorization: Bearer [insert-your-api-key-here]“ 
  -H 'Content-Disposition: attachment; filename="users.csv"' 
  -H “Content-Type: text/csv“ 
  https://integrations-api.pluralsight.com/sync-users

Poll the statusUrl from the response of the previous request for updates

curl
  https://integrations-api.pluralsight.com/sync-users/:id/status
  -H “Authorization: Bearer [insert-your-api-key-here]” 

Note: In this example, we used Bearer Authentication, but you could have used Basic Authentication instead. See Authentication for details.