On this page

Internal REST API

If your subscription includes it, you can enable API-level control over your candidates, assessments, and more through the Qualified API. Once it's enabled, your account will have a unique access key associated with it.

Internal API

The API on this page includes private endpoints not found in our public API.
These endpoints are generally not useful or usable for normal clients or customers, and are not guaranteed to be consistent.

Please see the main API docs for more complete details on access and authorization.

Parameter Casing

Both camel and underscore casing is supported when sending data to the sever.

For Example:

# Example request with underscore casing 
curl --request POST \
     --url https://www.qualified.io/api/v1/assessments/5da42a8ea54d75e0663421c2/challenge_items/ \
     --header 'authorization: 1MnbNTTL1O' \
     --header 'Content-Type: application/json' \
     --data '{"data":{"challenge_id":"5fa42a8ea54d75e066342d39"}}'

and 

# Example request with camel casing 
curl --request POST \
     --url https://www.qualified.io/api/v1/assessments/5da42a8ea54d75e0663421c2/challenge_items/ \
     --header 'authorization: 1MnbNTTL1O' \
     --header 'Content-Type: application/json' \
     --data '{"data":{"challengeId":"5fa42a8ea54d75e066342d39"}}'

are equivalent to each other.

Request Examples

The request examples given in the RESOURCES section will use underscore casing for consistency. Keep in mind that you can use either casing format.

Query Params

"includes" Param

There is a special parameter called "includes", available on most model requests. This parameter will fetch additional relations related to each model and include them within the model's JSON response. For example if you are returning an assessment result and want to include the related solutions, you can include them within a single API call.

The following example shows how to include challenge data on a solution.

curl --require POST \
     --url https://www.qualified.io/api/v1/solutions/5ca42f3ea54d75e0653421d2?includes=challenge \
     --header 'authorization: 1MnbNTTL1O' \
     --header 'Content-Type: application/json' \
Multiple Params

If you wish to include multiple relations, you will need to use multiple instances of the includes param, except you will also need to name it includes[].

For example:

curl --require POST \
     --url https://www.qualified.io/api/v1/solutions/5ca42f3ea54d75e0653421d2?includes[]=challenge&includes[]=assessment_result \
     --header 'authorization: 1MnbNTTL1O' \
     --header 'Content-Type: application/json' \

"where" Param

A where param with an encoded JSON value can be passed in to certain List endpoints. This param allows you to filter list data by specific fields. Not all fields on the object are typically available for use with filters, in some cases only a few fields have been whitelisted.

The following example shows how to filter challenges to only show those that are published.

curl --require POST \
     --url https://www.qualified.io/api/v1/challenges/5ea42a8ea54d75e0653421d2?where=%7B%22state%22%3A%20%22published%22%7D \
     --header 'authorization: 1MnbNTTL1O' \
     --header 'Content-Type: application/json' \

Notice that the where query parameter has an encoded {"state": "published"} value.

Where Operators

The JSON that is sent to the where param can be more than just search for equality. The following operators are supported:

  • "==", "!=", ">=", "<=", ">", and "<"
  • "contains": Partial text matches
  • "in": If one or more values are within an array or match a field
  • "nin": If zero values are within an array or field
Example

Select records which state are either opened or started

{ "state": { "in": ["opened", "started"] } }
Performance Considerations

Please keep your queries simple and short, ideally limited to no more than two filters at once. Not all fields are indexed and you may not achieve good performance with certain combinations.

Filterable Fields

Only some fields can be used as filters on certain "List" endpoints, while some List endpoints don't allow filters at all. Check each endpoint's parameter list to see what fields are filterable.

RESOURCES

Andela

InviteCandidate

Invites Andela Talent to take an assessment and returns details on them. If the talent has already been invited to the assessment, the Talent details for this assessment are returned.

POSTandela/invite_candidate
JSON Body Parameters:
data.assessment_idrequiredString
The ID of the assessment the candidate is being invited to.
data.candidate_emailrequired
The email address of the candidate.
data.retake_actionoptional
Allows talent to be reinvited to an assessment.
data.talent_idrequiredString
The Andela Talent ID of the candidate that is being invited.
Example Request
Example Response JSON

Results

Retrieves a list of all results associated to the Team Candidate.

GETandela/results/:team_candidate_id
URL Parameters:
team_candidate_idrequiredString
The ID of the Team Candidate whose results will be retrieved.
assessment_idoptionalString
The ID of the assessment you wish to restrict results to.
Example Request
Example Response JSON

AssessmentsBySkill

Retrieves a list of assessments associated to a skill. Returns a hash of passed, failed, and still unattempted assessments by the team candidate provided.

GETandela/assessments_by_skill/:team_candidate_id
URL Parameters:
team_candidate_idrequiredString
The ID of the team candidate whose assessments should be retrieved.
skillrequired
The name of the skill assessments are mapped to. Case sensitive.
Example Request
Example Response JSON

AssessmentReport

Retrieves a list of all results associated to the Team Candidate.

GETandela/assessment_report/:assessment_result_id
URL Parameters:
assessment_result_idrequiredString
The ID of the assessment result you want a report on.
Example Request
Example Response JSON

TalentReport

Retrieves a list of all results associated to the Team Candidate.

GETandela/talent_report/:team_candidate_id
URL Parameters:
team_candidate_idrequiredString
The ID of the Team Candidate whose report card you wish to retrieve.
Example Request
Example Response JSON

TalentReport

Retrieves a list of all results associated to the Team Candidate.

GETandela/report_card/:team_candidate_id
URL Parameters:
team_candidate_idrequiredString
The ID of the Team Candidate whose report card you wish to retrieve.
Example Request
Example Response JSON

ChangeEmail

Changes the email of a team candidate to the new email provided.

PUTandela/change_email/:team_candidate_id
URL Parameters:
team_candidate_idrequiredString
The ID of the Team Candidate whose email is being changed.
JSON Body Parameters:
data.emailrequired
The email address the team candidate should have their email changed to
Example Request
Example Response JSON

Account

PreCheck

Checks if a user exists in the system with the email. Returns login options if user exists

POST/v1/account/precheck
JSON Body Parameters:
data.$typeoptional
a user type
data.emailrequired
email to check for
Example Request
Example Response JSON

PreCheck

Checks if a user exists in the system with the email. Returns login options if user exists

POST/v1/account/precheck
JSON Body Parameters:
data.$typeoptional
a user type
data.emailrequired
email to check for
Example Request
Example Response JSON

Set Password

PUT/v1/account/password
URL Parameters:
idrequiredString
Object ID
JSON Body Parameters:
data.new_passwordrequired
the new password to use
data.old_passwordoptional
required if the password is already set
Expected Response Status:
204
Example Request

Confirm

Confirms the user. If the user was previously unconfirmed, this endpoint will also log the user in

POST/v1/account/confirm
JSON Body Parameters:
data.tokenrequired
Example Request
Example Response JSON

Activate Check

Checks the provided confirmation token, and returns the current user data. Does not complete activation

POST/v1/account/activate_check
JSON Body Parameters:
data.tokenrequired
Example Request
Example Response JSON

Activate Team Member

Activates the user and returns their account information. Users must choose a password or an OAuth login method to activate their account.

POST/v1/account/activate
JSON Body Parameters:
data.angellist_oauthoptional
data.angellist oauth
data.github_oauthoptional
data.github oauth
data.google_oauthoptional
data.google oauth
data.linkedin_oauthoptional
data.linkedin oauth
data.nameoptional
invited users can update their name if it was input incorrectly by the invitee
data.passwordoptional
Required if the user did not choose an OAuth method
data.tokenrequired
Example Request
Example Response JSON

Activate Candidate

Activates the user and returns their account information. Users must choose a password or an OAuth login method to activate their account.

POST/v1/account/activate
JSON Body Parameters:
data.angellist_oauthoptional
data.angellist oauth
data.github_oauthoptional
data.github oauth
data.google_oauthoptional
data.google oauth
data.linkedin_oauthoptional
data.linkedin oauth
data.nameoptional
invited users can update their name if it was input incorrectly by the invitee
data.passwordoptional
Required if the user did not choose an OAuth method
data.tokenrequired
Example Request
Example Response JSON

Forgot Password

Sends the user an email with a link to reset their password

POST/v1/account/forgot_password
JSON Body Parameters:
data.emailrequired
data.redirectTorequired
Should be an absolute path and include :token so that the token can be inserted
Expected Response Status:
204
Example Request

Reset Password

Resets the user password using the token as the secure way of accessing the user

POST/v1/account/reset_password
JSON Body Parameters:
data.passwordrequired
data.tokenrequired
Example Request
Example Response JSON

AdvancedCodeSolution

Log Test

PUT/v1/advanced_code_solutions/:id/log_test
JSON Body Parameters:
data.responserequired
Hash representing the response from the CodeRunner run
Example Request
Example Response JSON

Submit

PUT/v1/advanced_code_solutions/:id/submit
JSON Body Parameters:
data.responserequired
Hash representing the response from the CodeRunner run
Example Request
Example Response JSON

Assessment Challenge Items

Endpoints for viewing and configuring which challenges which are associated to each assessment.

Create

Associates a challenge to an assessment by creating a AssessmentChallengeItem record. If the challenge already exists for the assessment, a 409 will be returned. If a global challenge is passed, a copy of it will be created for the given team and that copy will be used instead.

POST/v1/assessments/:assessment_id/challenge_items/
URL Parameters:
assessment_idrequiredString
The ID of the assessment you wish to update an item on
JSON Body Parameters:
data.challenge_idrequiredString
The ID of the challenge you wish to associated to the assessment
Example Request
Example Response JSON

Update

Allows you to modify the position and disabled languages of the AssessmentChallengeItem record. When changing the position, all other items in the list will be adjusted to account for the item's new position. If you wish to replace the challenge, you should first delete the AssessmentChallengeItem that you wish to replace, then create a new one.

PUT/v1/assessments/:assessment_id/challenge_items/:id
URL Parameters:
assessment_idrequiredString
The ID of the assessment you wish to update an item on
idrequiredString
The item ID (not the challenge ID)
JSON Body Parameters:
data.disabled_languagesoptionalArray
An array of language identifiers (aka ["csharp", "ruby"]) which indicate which languages should not be allowed for the challenge
data.positionoptionalInteger
1 based index that determines the order of the challenge sequence for the assessment.
Example Request
Example Response JSON

Delete

Removes the AssessmentChallengeItem item from the assessment, causing the challenge to be disassociated.

DELETE/v1/assessments/:assessment_id/challenge_items/:id
URL Parameters:
assessment_idrequiredString
The ID of the assessment you wish to remove an item from
idrequiredString
The item ID (not the challenge ID)
Expected Response Status:
204
Example Request

Assessment Cohorts

Endpoints for managing and creating assessment cohorts. Assessment cohorts are groups of candidates who get invited in bulk to a same assessment at one time.

List

Returns a paged list of all assessment cohorts for the team.

GET/v1/assessment_cohorts
URL Parameters:
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
created_at id state team_candidate_ids title updated_at
order_byoptionalString
i.e. "createdAt DESC"
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
Example Request
Example Response JSON
Notable Response Fields

Retrieve

Retrieves a single assessment cohort by ID.

GET/v1/assessment_cohorts/:id
URL Parameters:
idrequiredString
The ID of the cohort you wish to retrieve.
Example Request
Example Response JSON

Invite Candidates

Create an assessment cohort and invite all candidates included.

POST/v1/assessment_cohorts/
JSON Body Parameters:
data.access_ends_atoptionalDate

The date and time in which the candidate will no longer have access to the assessment. Useful if you want to set a hard stop date in which no more candidate activity is allowed. When using with retakes, this value can be used to set the retake stop window. The value must be at least one hour into the future.

data.access_lockedoptionalBoolean

Set to true if you wish to prevent the candidate from starting the assessment until it is manually unlocked. This allows you to give access but still retain control of exactly when the candidate can start. If true, access will be locked even if within the access window defined by access_starts_at and access_ends_at.

data.access_starts_atoptionalDate

The date and time that the candidate can start the assessment. Useful if you want to invite one or more candidates and ensure that they all have a the same start time. When using with expires_at, this value should be sooner than expires_at. When using with retakes, this value can be used to set the retake start window.

data.apply_day_defaultsoptionalBoolean

Assessments can be configured with default expiration and reminder values. If this is true, then default will be applied if not specifically set.

data.assessment_idrequiredString

The ID of the assessment you wish to send the invitation for.

data.assigned_team_member_idsoptionalArray

An array of team members ID strings that should be assigned to the candidate.

data.candidatesrequiredArray

An array of candidate emails to send invitations to.

data.custom_messageoptional

Customizes the message that is emailed to the candidate. Only relevant if send_email_to_candidate is true.

data.enforced_time_limitoptionalInteger

Set to number of minutes you wish to enforce as a time limit. If not set, will use the time limit set on the assessment. This value is only relevant if the candidate has not yet been invited, or if retry_action is set.

data.expires_atoptional

The date in which the invitation can no longer be accepted. Once the candidate starts the assessment, this value is no longer relevant.

data.first_nameoptionalString

First name of candidate, can only be used when single email is passed to candidates array

data.labelsoptionalArray

An array of strings indicating which labels should be applied to the invited candidates.

data.last_nameoptionalString

Last name of candidate, can only be used when single email is passed to candidates array

data.reminder_atoptional

The date in which a reminder email should be sent to the candidate. Only sent if the candidate has not started the assessment by the date.

data.reopen_submittedoptionalBoolean

DEPRECATED: True if retry_action should be set to "reopen". Use retry_action property instead.

data.reset_challenge_timersoptionalBoolean

True if any challenge based timers should be reset. Timers will start over again from 0 when the candidate revisits each solution.

data.retry_actionoptionalString

The type of action that should be performed if the candidate has already submitted and you would like them to take further action. A null or omitted value indicates no retry action will be performed.

Accepted Values:
"reopen":Reopens the assessment result when the candidate visits the assessment. The candidate will be able to resume where they left off.
"retake":The candidate will be asked to start a new assessment, without carrying any previous work over. The original assessment result data will be kept as a separate record, and the new retake will be the featured result within the Qualified team UI.
data.send_email_to_candidateoptionalBoolean

Set to false if you do not wish to send an invitation email. This can be useful for when you simply want to use the invitation_url returned by this request, and send that URL on your own. If false is not explicitly passed, then the email will be sent by default.

data.send_email_to_inviteroptionalBoolean

Set to true if you wish to send a copy of the invitation email to the inviting user's email address. This only has an affect on new invitations, if the invitation was already previously sent then this value will be ignored.

data.skip_email_resendoptionalBoolean

Set to true if you wish to skip resending the email if the candidate is already invited. This can be useful if you are not sure if the invite has been sent yet and only want to send the email if one wasn't already sent. This value is ignored if send_email_to_candidate is explicitly set to false.

data.skip_registrationoptionalBoolean

True if the first and last name should not be collected from new candidates. Otherwise new candidates will be asked to enter these details before starting the assessment.

data.track_active_timeoptionalBoolean

False if you wish to prevent active time from being tracked. This is only relevant if retry_action is "reopen". You can use this value when you want to allow a candidate to reopen their assessment result for the purpose of review.

Example Request
Example Response JSON
Notable Response Fields

Update

Updates a single assessment cohort by ID.

PUT/v1/assessment_cohorts/:id
URL Parameters:
idrequiredString
The ID of the cohort you wish to update.
JSON Body Parameters:
data.candidatesoptionalString
Additional candidate emails you wish to invite.
data.titleoptionalString
Title you wish to change the cohort title to.
Example Request
Example Response JSON

Delete

Deletes the assessment cohort retrieved by id.

DELETE/v1/assessment_cohorts/:id
URL Parameters:
idrequiredString
The ID of the cohort you wish to delete
Expected Response Status:
204
Example Request

Assessment Invitations

Endpoints for managing and creating invitations. Invitations are how candidates get explicitly introduced into the system. For private assessments, this is the only way to gain access to take the assessment.

List

Returns a paged list of all active invitations for the team.

GET/v1/assessment_invitations
URL Parameters:
team_candidate_idoptionalString
The ID of the team candidate you wish to restrict the query to.
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
order_byoptionalString
i.e. "createdAt DESC"
Example Request
Example Response JSON
Notable Response Fields

Invite Candidates

The way to create a candidate within the system is to invite them to an assessment.

POST/v1/assessment_invitations/invite_candidates
JSON Body Parameters:
data.access_ends_atoptionalDate

The date and time in which the candidate will no longer have access to the assessment. Useful if you want to set a hard stop date in which no more candidate activity is allowed. When using with retakes, this value can be used to set the retake stop window. The value must be at least one hour into the future.

data.access_lockedoptionalBoolean

Set to true if you wish to prevent the candidate from starting the assessment until it is manually unlocked. This allows you to give access but still retain control of exactly when the candidate can start. If true, access will be locked even if within the access window defined by access_starts_at and access_ends_at.

data.access_starts_atoptionalDate

The date and time that the candidate can start the assessment. Useful if you want to invite one or more candidates and ensure that they all have a the same start time. When using with expires_at, this value should be sooner than expires_at. When using with retakes, this value can be used to set the retake start window.

data.alternate_idoptionalString

Used for teams to track their own IDs alongside candidates.

data.apply_day_defaultsoptionalBoolean

Assessments can be configured with default expiration and reminder values. If this is true, then default will be applied if not specifically set.

data.assessment_idrequiredString

The ID of the assessment you wish to send the invitation for.

data.assigned_team_member_idsoptionalArray

An array of team members ID strings that should be assigned to the candidate.

data.candidatesrequiredArray

An array of candidate emails to send invitations to.

data.custom_messageoptionalString

Customizes the message that is emailed to the candidate. Only relevant if send_email_to_candidate is true.

data.enforced_time_limitoptionalInteger

Set to number of minutes you wish to enforce as a time limit. If not set, will use the time limit set on the assessment. This value is only relevant if the candidate has not yet been invited, or if retry_action is set.

data.expires_atoptionalDate

The date in which the invitation can no longer be accepted. Once the candidate starts the assessment, this value is no longer relevant.

data.first_nameoptionalString

First name of candidate, can only be used when single email is passed to candidates array

data.labelsoptionalArray

An array of strings indicating which labels should be applied to the invited candidates.

data.last_nameoptionalString

Last name of candidate, can only be used when single email is passed to candidates array

data.reminder_atoptionalDate

The date in which a reminder email should be sent to the candidate. Only sent if the candidate has not started the assessment by the date.

data.reopen_submittedoptionalBoolean

DEPRECATED: True if retry_action should be set to "reopen". Use retry_action property instead.

data.reset_challenge_timersoptionalBoolean

True if any challenge based timers should be reset. Timers will start over again from 0 when the candidate revisits each solution.

data.retry_actionoptionalString

The type of action that should be performed if the candidate has already submitted and you would like them to take further action. A null or omitted value indicates no retry action will be performed.

Accepted Values:
"reopen":Reopens the assessment result when the candidate visits the assessment. The candidate will be able to resume where they left off.
"retake":The candidate will be asked to start a new assessment, without carrying any previous work over. The original assessment result data will be kept as a separate record, and the new retake will be the featured result within the Qualified team UI.
data.send_email_to_candidateoptionalBoolean

Set to false if you do not wish to send an invitation email. This can be useful for when you simply want to use the invitation_url returned by this request, and send that URL on your own. If false is not explicitly passed, then the email will be sent by default.

data.send_email_to_inviteroptionalBoolean

Set to true if you wish to send a copy of the invitation email to the inviting user's email address. This only has an affect on new invitations, if the invitation was already previously sent then this value will be ignored.

data.skip_email_resendoptionalBoolean

Set to true if you wish to skip resending the email if the candidate is already invited. This can be useful if you are not sure if the invite has been sent yet and only want to send the email if one wasn't already sent. This value is ignored if send_email_to_candidate is explicitly set to false.

data.skip_registrationoptionalBoolean

True if the first and last name should not be collected from new candidates. Otherwise new candidates will be asked to enter these details before starting the assessment.

data.track_active_timeoptionalBoolean

False if you wish to prevent active time from being tracked. This is only relevant if retry_action is "reopen". You can use this value when you want to allow a candidate to reopen their assessment result for the purpose of review.

Example Request
Example Response JSON
Notable Response Fields

Invite Candidates (with API Key)

Inviting Candidates with API key

POST/v1/assessment_invitations/invite_candidates
JSON Body Parameters:
data.access_ends_atoptionalDate

The date and time in which the candidate will no longer have access to the assessment. Useful if you want to set a hard stop date in which no more candidate activity is allowed. When using with retakes, this value can be used to set the retake stop window. The value must be at least one hour into the future.

data.access_lockedoptionalBoolean

Set to true if you wish to prevent the candidate from starting the assessment until it is manually unlocked. This allows you to give access but still retain control of exactly when the candidate can start. If true, access will be locked even if within the access window defined by access_starts_at and access_ends_at.

data.access_starts_atoptionalDate

The date and time that the candidate can start the assessment. Useful if you want to invite one or more candidates and ensure that they all have a the same start time. When using with expires_at, this value should be sooner than expires_at. When using with retakes, this value can be used to set the retake start window.

data.alternate_idoptionalString

Used for teams to track their own IDs alongside candidates.

data.apply_day_defaultsoptionalBoolean

Assessments can be configured with default expiration and reminder values. If this is true, then default will be applied if not specifically set.

data.assessment_idrequiredString

The ID of the assessment you wish to send the invitation for.

data.assigned_team_member_idsoptionalArray

An array of team members ID strings that should be assigned to the candidate.

data.candidatesrequiredArray

An array of candidate emails to send invitations to.

data.custom_messageoptionalString

Customizes the message that is emailed to the candidate. Only relevant if send_email_to_candidate is true.

data.enforced_time_limitoptionalInteger

Set to number of minutes you wish to enforce as a time limit. If not set, will use the time limit set on the assessment. This value is only relevant if the candidate has not yet been invited, or if retry_action is set.

data.expires_atoptionalDate

The date in which the invitation can no longer be accepted. Once the candidate starts the assessment, this value is no longer relevant.

data.first_nameoptionalString

First name of candidate, can only be used when single email is passed to candidates array

data.labelsoptionalArray

An array of strings indicating which labels should be applied to the invited candidates.

data.last_nameoptionalString

Last name of candidate, can only be used when single email is passed to candidates array

data.reminder_atoptionalDate

The date in which a reminder email should be sent to the candidate. Only sent if the candidate has not started the assessment by the date.

data.reopen_submittedoptionalBoolean

DEPRECATED: True if retry_action should be set to "reopen". Use retry_action property instead.

data.reset_challenge_timersoptionalBoolean

True if any challenge based timers should be reset. Timers will start over again from 0 when the candidate revisits each solution.

data.retry_actionoptionalString

The type of action that should be performed if the candidate has already submitted and you would like them to take further action. A null or omitted value indicates no retry action will be performed.

Accepted Values:
"reopen":Reopens the assessment result when the candidate visits the assessment. The candidate will be able to resume where they left off.
"retake":The candidate will be asked to start a new assessment, without carrying any previous work over. The original assessment result data will be kept as a separate record, and the new retake will be the featured result within the Qualified team UI.
data.send_email_to_candidateoptionalBoolean

Set to false if you do not wish to send an invitation email. This can be useful for when you simply want to use the invitation_url returned by this request, and send that URL on your own. If false is not explicitly passed, then the email will be sent by default.

data.send_email_to_inviteroptionalBoolean

Set to true if you wish to send a copy of the invitation email to the inviting user's email address. This only has an affect on new invitations, if the invitation was already previously sent then this value will be ignored.

data.skip_email_resendoptionalBoolean

Set to true if you wish to skip resending the email if the candidate is already invited. This can be useful if you are not sure if the invite has been sent yet and only want to send the email if one wasn't already sent. This value is ignored if send_email_to_candidate is explicitly set to false.

data.skip_registrationoptionalBoolean

True if the first and last name should not be collected from new candidates. Otherwise new candidates will be asked to enter these details before starting the assessment.

data.track_active_timeoptionalBoolean

False if you wish to prevent active time from being tracked. This is only relevant if retry_action is "reopen". You can use this value when you want to allow a candidate to reopen their assessment result for the purpose of review.

Example Request
Example Response JSON
Notable Response Fields

Invite Team Members

Allows you to invite a team member to a specific assessment. This will cause team members to receive an email. This API is useful for when you want to have members of your team test the assessment, before sending it out to candidates. You will not be charged a usage for having your own team members take the assessment.

POST/v1/assessment_invitations/invite_team_members
JSON Body Parameters:
data.assessment_idrequiredString
The ID of the assessment you wish to invite team members to
data.roleoptionalArray
If one or more of the team member emails provided do not match an existing user, then a new user will be created. This value determines the role that those users should be set to.
Accepted Values:
blind_reviewer inviter owner reviewer
data.team_membersrequiredArray
An array of objects containing an email key/value
Example Request
Example Response JSON
Notable Response Fields

Cancel

Cancels the invitation so that a candidate can no longer accept it and gain access to the assessment. If the candidate already started the assessment, their result will be terminated. An "Invitation Cancelled" label will be automatically applied to the candidate.

DELETE/v1/assessment_invitations/:id
URL Parameters:
idrequiredString
The ID of the invitation you wish to cancel
Expected Response Status:
204
Example Request

Assessment Result Reviews

Assessment Result Reviews are the overall review opinion left by team members. These reviews are used to provide feedback on the quality of submissions. Individual solution reviews are then associated to each assessment result review. There is one review per reviewer/assessment result.

List

Returns a paged list of all reviews for the team.

GET/v1/assessment_result_reviews
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment assessment_result reviewed_by team_candidate
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
assessment_id assessment_result_id candidate_id created_at id reviewed_by_id state team_candidate_id
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
order_byoptionalString
i.e. "createdAt DESC"
Example Request
Example Response JSON

Retrieve

Retrieves a single assessment result review by ID.

GET/v1/assessment_result_reviews/:id
URL Parameters:
idrequiredString
The ID of the review you wish to retrieve
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment assessment_result reviewed_by team_candidate
Example Request
Example Response JSON

Create

Creates an assessment result review. There can only be one review per assessment result & reviewer.

POST/v1/assessment_result_reviews
JSON Body Parameters:
data.assessment_result_idrequiredString
The ID of the assessment result being reviewed.
data.feedbackoptionalString

Feedback given by the reviewer. Markdown is supported.

data.ratingoptionalInteger

Subjective rating. 1 - 5, for a 3 point system use 1,3 and 5 as your values.

data.reviewed_by_idrequiredString
The ID of the user who will be doing the assessing. Only one reviewer per assessment result is allowed.
Example Request
Example Response JSON

Update

Update the feedback or rating given by a reviewer.

PUT/v1/assessment_result_reviews/:id
URL Parameters:
idrequiredString
The ID of the review you wish to update
JSON Body Parameters:
data.feedbackoptionalString

Feedback given by the reviewer. Markdown is supported.

data.ratingoptionalInteger

Subjective rating. 1 - 5, for a 3 point system use 1,3 and 5 as your values.

Example Request
Example Response JSON

Delete

Deletes an assessment result review. Deletes any associated solution reviews as well.

DELETE/v1/assessment_result_reviews/:id
URL Parameters:
idrequiredString
The ID of the review you wish to delete
Expected Response Status:
204
Example Request

Assessment Results

Each time a candidate takes an assessment, their work is stored within the assessment result.

List

Returns a paged list of assessment results for the team.

GET/v1/assessment_results
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
access_unlocked_by assessment challenge_items.challenge reopened_by solutions team_candidate
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
created_at current_take id labels score state team_candidate_id updated_at
order_byoptionalString
ie: "created_by DESC".
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
assessment_idoptionalString
The ID of the assessment you wish to restrict results to.
team_candidate_idoptionalString
The ID of the candidate you wish to restrict results to.
Example Request
Example Response JSON
Notable Response Fields

List (with includes)

GET/v1/assessment_results
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
access_unlocked_by assessment challenge_items.challenge reopened_by solutions team_candidate
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
created_at current_take id labels score state team_candidate_id updated_at
order_byoptionalString
ie: "created_by DESC".
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
assessment_idoptionalString
The ID of the assessment you wish to restrict results to.
team_candidate_idoptionalString
The ID of the candidate you wish to restrict results to.
Example Request
Example Response JSON
Notable Response Fields

Retrieve

Retrieves an assessment result by ID. Note that this endpoint returns a large amount of data that is typically consumed by Qualified application itself. Some fields may change. It is recommended to use the "Exhibit" endpoint where possible.

GET/v1/assessment_results/:id
URL Parameters:
idrequiredString
The ID of the assessment result
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
access_unlocked_by assessment challenge_items.challenge invitations most_recent_invitation reopened_by solutions team_candidate
Example Request
Example Response JSON
Notable Response Fields

Get (with includes)

GET/v1/assessment_results/:id
URL Parameters:
idrequiredString
The ID of the assessment result
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
access_unlocked_by assessment challenge_items.challenge invitations most_recent_invitation reopened_by solutions team_candidate
Example Request
Example Response JSON
Notable Response Fields

Exhibit

Provides a more consumer friendly version of assessment result information. This is the recommended endpoint if you wish to consume assessment result information within your own application. The data is streamlined and contains relevant information from other key related data models.

GET/v1/assessment_results/:id/exhibit
URL Parameters:
idrequiredString
The ID of the assessment result
Example Request
Example Response JSON
Notable Response Fields

Share

Returns a set of sharable URLs which do not require login, **only available if feature is enabled on your subscription**.

GET/v1/assessment_results/:id/share
URL Parameters:
idrequiredString
The ID of the assessment result to share
hideoptionalString
Comma separated list of areas which should be hidden. These areas will be signed into the url so that they cannot be changed later. You can also provide any of these as an unsigned parameter by adding a `hide` parameter to the returned URLs. This can be used to provide additional control, while not being able to override the signed options. For example, to hide the page styling without always enforcing it, you might use this: return shareResult.url + '?hide=pageStyling';
Accepted Values:
"pageStyling":Removes print-like page styling (ignored for PDF reports)
"candidateName":Candidate's real name
"candidateAnonymousName":Candidate's Anonymous Name (when combined with candidateName)
"candidateEmail":Candidate's email
"candidateRemarks":Candidate's assessment feedback
"interact":Interact session details
"summary":Assessment summary
"summaryScore":Scoring section
"summaryTiming":Timing section
"reviews":All reviews
"purpose":Reviewing guide
"solutionsSummary":Solutions summary section
"solutions":Solution details
"candidateNotes":Candidate notes for each solution
"instructions":Challenge instructions
"solutionErrors":Submission Errors (if any)
"solutionAnswers":Solution code or answers
Example Request
Example Response JSON

Create

Creates a assessment result for a assessment. The assessment must be published in order for the operation to be valid.

POST/v1/assessment_results
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment challenge solutions team team_candidate
JSON Body Parameters:
data.candidate_remarksoptionalString

Candidate remarks about the assessment process.

Example Request
Example Response JSON
Notable Response Fields

Unlock Access

Unlocks an access_locked assessment result so a candidate can begin their assessment.

PUT/v1/assessment_results/:id/unlock_access
URL Parameters:
idrequiredString
The ID of the assessment result to unlock
Example Request
Example Response JSON

Update

Allows a candidate to update their comments after submission.

PUT/v1/assessment_results/:id/
URL Parameters:
idrequiredString
The ID of the assessment result to unlock
JSON Body Parameters:
data.candidate_remarksoptionalString

Candidate remarks about the assessment process.

Example Request
Example Response JSON
Notable Response Fields

Submit

Submits an assessment to be reviewed/screened by the company/team. This prevents the candidate from continuing, and generates a score. Some automated workflows may be triggered, but client-side workflow features such as show a message and redirect URL will be ignored. Note that the assessment result will be set into the "submitting" state. The full submission process happens within a background process and may take some time to complete. You can utilize web hooks to be notified when the full submission has taken place.

PUT/v1/assessment_results/:id/submit
URL Parameters:
idrequiredString
The ID of the assessment result to submit
Example Request
Example Response JSON

Terminate

Closes without submitting the assessment result. This prevents the candidate from continuing, and also doesn't generate a score, call webhooks, or trigger automated workflows. This can be useful for orchestrating your own expiration functionality where you do not want to submit any pre-existing progress for scoring.

PUT/v1/assessment_results/:id/terminate
URL Parameters:
idrequiredString
The ID of the assessment result to terminate
JSON Body Parameters:
data.closed_reasonoptionalString
Indicates the reason for closing the assessment result without submitting it.
Accepted Values:
assessment_archived candidate_submitted invitation_canceled team_decided team_forced timer_ran_out
Example Request
Example Response JSON

Joined Interview

Notifies Qualified that the current user has joined the interview

PUT/v1/assessment_results/:id/joined_interview
Example Request
Example Response JSON

Unsubmit

Reopens a submitted assessment result so that the candidate can make changes. This endpoint is only valid on assessment results which are current. If a retake has happened since this assessment result was submitted, then it cannot be reopened. This endpoint used to be called "Unsubmit" and is backwards compatible.

PUT/v1/assessment_results/:id/unsubmit
URL Parameters:
idrequiredString
The ID of the assessment result to reopen. The assessment result must be current, which means a retake has not happened since it was submitted.
JSON Body Parameters:
data.access_ends_atoptionalDate
The date up to when the candidate is allowed to reopen. If not set there will be no limit.
data.access_starts_atoptionalDate
The date for when the candidate should be allowed to reopen. Defaults to current time if not provided.
data.email_messageoptionalString
Customize the message to be sent, only relevant if send_email_to_candidate is true
data.enforced_time_limitoptionalInteger
Reset the time limit to the specified number of minutes
data.reset_challenge_timersoptionalBoolean
True if you wish to reset all challenge timers, which will cause any timers to start with their original settings. For Q&A challenges, question timers will be reset as well.
data.send_emailoptionalBoolean
True if you wish to send a new invitation email
Example Request
Example Response JSON

Schedule Retry

Schedules a reopen or retake for a submitted assessment result so that the candidate can make changes. This endpoint is only valid on assessment results which are current. If a retake has happened since this assessment result was submitted, then it cannot be reopened. This endpoint used to be called "Unsubmit" and is backwards compatible.

PUT/v1/assessment_results/:id/schedule_retry
URL Parameters:
idrequiredString
The ID of the assessment result to reopen. The assessment result must be current, which means a retake has not happened since it was submitted.
JSON Body Parameters:
data.access_ends_atoptionalDate
The date up to when the candidate is allowed to reopen. If not set there will be no limit.
data.access_starts_atoptionalDate
The date for when the candidate should be allowed to reopen. Defaults to current time if not provided.
data.custom_messageoptionalString
Customize the message to be sent, only relevant if send_email_to_candidate is true.
data.enforced_time_limitoptionalInteger
Reset the time limit to the specified number of minutes.
data.reset_challenge_timersoptionalBoolean
True if you wish to reset all challenge timers, which will cause any timers to start with their original settings. For Q&A challenges, question timers will be reset as well.
data.retry_actionoptionalString
Set to "retake" if you want to have the candidate to start the assessment over from scratch.
data.send_email_to_candidateoptionalBoolean
True if you wish to send a new invitation email.
Example Request
Example Response JSON

Cancel Retry

An assessment result can be scheduled to be reopened or retaken, which happens once the candidate lands on the assessment page. Calling this method will cancel a previously scheduled retry. To schedule a retry, use the invitations invite_candidates endpoint.

PUT/v1/assessment_results/:id/cancel_retry
URL Parameters:
idrequiredString
The ID of the assessment result to cancel.
Example Request
Example Response JSON

Reset

Reopens an assessment result, and updates the challenges to the latest published version of the assessment.

PUT/v1/assessment_results/:id/reset
URL Parameters:
idrequiredString
The ID of the assessment result to reset.
JSON Body Parameters:
data.reset_alloptionalString
If true, completely remove all solutions and start from scratch. Otherwise, only update the assessment result and challenges list.\n\n**NOTE:** If set to true, all solutions will be removed. This is not reversible, solutions will be lost forever.
Example Request
Example Response JSON

Destroy

Enables completely destroying an assessment result that has not been started. NOTE: AssessmentResult state MUST be "invited" or "opened" to be destroyed.

DELETE/v1/assessment_results/:id
URL Parameters:
idrequiredString
The ID of the assessment result to delete.
Expected Response Status:
204
Example Request

AssessmentSets

An assessment set contains one or more assessments to be used in pathways or in interviews.

List

Returns a paged list of all assessment sets for your team.

GET/v1/assessment_sets
URL Parameters:
order_byoptionalString
ie: "title DESC"
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Retrieve

Returns an assessment set for authenticated users.

GET/v1/assessment_sets/:id
URL Parameters:
idrequiredString
The ID of the assessment set you wish to retrieve.
Example Request
Example Response JSON

Create

Creates a new assessment set.

POST/v1/assessment_sets
JSON Body Parameters:
data.itemsrequiredArray

Assessment items to represent the assessments that will be part of the set.

Child Parameters
data.selection_actionoptionalString

Method by which the assessment set will select the next assessment to be taken. If not set, the default is 'weighted_random'.

Accepted Values:
most_recently_published weighted_random
data.selection_preferenceoptionalString

The preference for which assessment to select. If not set, the default is 'not_started'.

Accepted Values:
not_completed not_started passed
data.titlerequiredString

What this assessment set will be titled as.

Example Request
Example Response JSON

Update

Updates an existing assessment set.

PUT/v1/assessment_sets/:id
URL Parameters:
idrequiredString
AssessmentSet ID
JSON Body Parameters:
data.itemsoptionalArray

Assessment items to represent the assessments that will be part of the set.

Child Parameters
data.selection_actionoptionalString

Method by which the assessment set will select the next assessment to be taken. If not set, the default is 'weighted_random'.

Accepted Values:
most_recently_published weighted_random
data.selection_preferenceoptionalString

The preference for which assessment to select. If not set, the default is 'not_started'.

Accepted Values:
not_completed not_started passed
data.titleoptionalString

What this assessment set will be titled as.

Example Request
Example Response JSON

Delete

Deletes the assessment set

DELETE/v1/assessment_sets/:id
URL Parameters:
idrequiredString
AssessmentSet ID
Expected Response Status:
204
Example Request

Assessment Templates

Assessment templates are pre-built assessments which you can use as-is or as a starting point to build your own.

List

Returns a paged list of assessment templates.

GET/v1/assessment_templates
Example Request
Example Response JSON

List (with api key)

GET/v1/assessment_templates
Example Request
Example Response JSON

Import

Imports the assessment template as a new assessment on your team.

PUT/v1/assessment_templates/:id/import
URL Parameters:
idrequiredString
The ID of the template you wish to import into your team.
Example Request
Example Response JSON

AssessmentWorkflowPath

List

GET/v1/assessment_workflow_paths
URL Parameters:
assessment_idrequiredString
the id of the assessment
includesoptionalString
next_assessment
Example Request
Example Response JSON

Retrieve

GET/v1/assessment_workflow_paths/:id
JSON Body Parameters:
data.assessment_idoptionalString
the id of the assessment
Example Request
Example Response JSON

Create

POST/v1/assessment_workflow_paths
JSON Body Parameters:
data.assessment_idrequiredString
the id of the assessment
Example Request
Example Response JSON

Update

PUT/v1/assessment_workflow_paths/:id
JSON Body Parameters:
data.assessment_idrequiredString
the id of the assessment
Example Request
Example Response JSON

Delete

DELETE/v1/assessment_workflow_paths/:id
Expected Response Status:
204
Example Request

Assessments

An Assessment contains one or more challenges that are given to a candidate to assess them on their ability. Typically an AssessmentInvitation is used to invite a TeamCandidate to take it, which will also create an AssessmentResult - which is the record used to track the candidate's assessment progress.

List

Returns a paged list of all assessments for your team.

GET/v1/assessments
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_results assignment_team_members copied_from created_by
order_byoptionalString
ie: "title DESC"
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Retrieve

Returns assessment for both authenticated and unauthenticated users. Only admins and team members can see unpublished assessments.

GET/v1/assessments/:id
URL Parameters:
idrequiredString
The ID of the assessment you wish to retrieve.
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_result_reviews assessment_results assignment_team_members challenge_items.challenge copied_from created_by solution_reviews
Example Request
Example Response JSON

Get (with includes)

Example demonstrates a team member request

GET/v1/assessments/:id
URL Parameters:
idrequiredString
The ID of the assessment you wish to retrieve.
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_result_reviews assessment_results assignment_team_members challenge_items.challenge copied_from created_by solution_reviews
Example Request
Example Response JSON

Create

Creates a new assessment in a draft state. If you wish to create an assessment within a published state, you should first create the assessment, use the Assessment Challenge Items API to add challenges, then call the Assessment publish endpoint.

POST/v1/assessments
JSON Body Parameters:
data.labelsoptionalArray

An array of label strings to assign to the assessment. Any value can be used, it does not need to be previously defined.

data.purposeoptionalString

Internal value useful for explaining to team members why what this assessment is focused on.

data.summaryoptionalString

Used to display a short summary to candidates about the assessment.

data.titlerequiredString

What this assessment will be titled as.

Example Request
Example Response JSON

Update

Updates an existing assessment. This API does not provide access to manipulating the challenge items. To modify the list of challenge items, use the Assessment Challenge Items resource.

PUT/v1/assessments/:id
URL Parameters:
idrequiredObjectId
Assessment ID
JSON Body Parameters:
data.labelsoptionalArray

An array of label strings to assign to the assessment. Any value can be used, it does not need to be previously defined.

data.purposeoptionalString

Internal value useful for explaining to team members why what this assessment is focused on.

data.summaryoptionalString

Used to display a short summary to candidates about the assessment.

data.titlerequiredString

What this assessment will be titled as.

Example Request
Example Response JSON

Publish

Publishes a draft assessment. There must be at least one challenge item associated, and all challenges must already be published.

PUT/v1/assessments/:id/publish
URL Parameters:
idrequiredObjectId
Assessment ID
Example Request
Example Response JSON

Publish (with API key)

PUT/v1/assessments/:id/publish
URL Parameters:
idrequiredObjectId
Assessment ID
Example Request
Example Response JSON

Un-publish

Moves an assessment back to the draft state, preventing new invitations from being able to be sent for this assessment. Existing invitations will remain active.

PUT/v1/assessments/:id/unpublish
URL Parameters:
idrequiredObjectId
Assessment ID
Example Request
Example Response JSON

Archive

Archives the assessment. Any active invitations will be cancelled, and any started assessment results will be closed.

PUT/v1/assessments/:id/archive
URL Parameters:
idrequiredObjectId
Assessment ID
Example Request
Example Response JSON

Unarchive

Unarchives the assessment

PUT/v1/assessments/:id/unarchive
URL Parameters:
idrequiredObjectId
Assessment ID
Example Request
Example Response JSON

Export

Makes a copy of an assessment on the team provided. The user must have access to both teams to export the assessment.

POST/v1/assessments/:id/export
URL Parameters:
idrequiredString
The ID of the assessment you wish to export.
JSON Body Parameters:
data.export_torequiredString
ID of the team the assessment should be exported to.
Example Request
Example Response JSON

Unlock All

Unlocks any access_locked assessment results associated with this assessment. Note the results are unlocked asynchronously.

PUT/v1/assessments/:id/unlock_all
URL Parameters:
idrequiredString
The ID of the assessment you wish to unlock assessment results for.
Example Request
Example Response JSON

Delete

Deletes the assessment

DELETE/v1/assessments/:id
URL Parameters:
idrequiredObjectId
Assessment ID
Expected Response Status:
204
Example Request

Recover

Recovers a soft deleted assessment

PUT/v1/assessments/:id/recover
URL Parameters:
idrequiredString
base16 ObjectId
idrequiredObjectId
Assessment ID
Example Request
Example Response JSON

Billing::Contract

List

GET/v1/billing/contracts
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Example Request
Example Response JSON

Retrieve

GET/v1/billing/contracts/:id
Example Request
Example Response JSON

Create

POST/v1/billing/contracts
Example Request
Example Response JSON

Update

PUT/v1/billing/contracts/:id
Example Request
Example Response JSON

Invoice

PUT/v1/billing/contracts/:id/invoice
Example Request
Example Response JSON

Delete

DELETE/v1/billing/contracts/:id
Expected Response Status:
204
Example Request

Billing::Billing::Customer

Update Payment (invalid token)

PUT/v1/billing/customers/:id/payment
URL Parameters:
date.typeoptional
Payment type, defaults to "card"
JSON Body Parameters:
data.gatewayrequired
The gateway provider
data.tokenrequired
The token returned from the gateway SDK, such as stripe.js
Expected Response Status:
400
Example Request
Example Response JSON

Update Payment (not authorized)

PUT/v1/billing/customers/:id/payment
URL Parameters:
date.typeoptional
Payment type, defaults to "card"
JSON Body Parameters:
data.gatewayrequired
The gateway provider
data.tokenrequired
The token returned from the gateway SDK, such as stripe.js
Expected Response Status:
403
Example Request
Example Response JSON

Billing::Invoice

List

GET/v1/billing/invoices
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Example Request
Example Response JSON

Retrieve

GET/v1/billing/invoices/:id
Example Request
Example Response JSON

Billing::Plan

List

GET/v1/billing/plans
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Example Request
Example Response JSON

Retrieve

GET/v1/billing/plans/:id
Example Request
Example Response JSON

Create

POST/v1/billing/plans
JSON Body Parameters:
data.additional_premium_seat_priceoptional
data.additional premium seat price
data.additional_restricted_seat_priceoptional
data.additional restricted seat price
data.base_intervalrequired
data.base interval
data.base_interval_unitrequired
data.base interval unit
data.base_pricerequired
data.base price
data.bulk_unit_priceoptional
data.bulk unit price
data.bulk_usage_creditsoptional
data.bulk usage credits
data.burst_unit_pricerequired
data.burst unit price
data.commonoptional
True if this should be considered a commonly offered plan
data.features.base_feature_setrequired
data.features.base feature set
data.included_premium_seatsoptional
data.included premium seats
data.included_restricted_seatsoptional
data.included restricted seats
data.plan_categoryrequired
The category of the plan, typically one of payg, starter, bulk, pilot, enterprise, education
data.publicoptional
True if this plan is shown on the public pricing page
data.recurring_usage_allotmentrequired
data.recurring usage allotment
data.usage_intervaloptional
data.usage interval
data.usage_interval_unitoptional
data.usage interval unit
Example Request
Example Response JSON

Update

PUT/v1/billing/plans/:id
JSON Body Parameters:
data.base_intervaloptional
data.base interval
data.base_interval_unitoptional
data.base interval unit
data.base_priceoptional
data.base price
data.bulk_unit_priceoptional
data.bulk unit price
data.bulk_usage_creditsoptional
data.bulk usage credits
data.burst_unit_priceoptional
data.burst unit price
data.commonoptional
True if this should be considered a commonly offered plan
data.features.base_feature_setoptional
data.features.base feature set
data.included_premium_seatsoptional
data.included premium seats
data.included_restricted_seatsoptional
data.included restricted seats
data.plan_categoryoptional
The category of the plan, typically one of payg, starter, bulk, pilot, enterprise, education
data.publicoptional
True if this plan is shown on the public pricing page
data.recurring_usage_allotmentoptional
data.recurring usage allotment
data.usage_intervaloptional
data.usage interval
data.usage_interval_unitoptional
data.usage interval unit
Example Request
Example Response JSON

Delete

DELETE/v1/billing/plans/:id
Expected Response Status:
204
Example Request

Billing::Customer

Create

POST/v1/billing/customers/:customer_id/subscription
JSON Body Parameters:
data.plan_idrequiredString
The plan to subscribe to
Example Request
Example Response JSON

Reactivate (Cancelled)

PUT/v1/billing/customers/:customer_id/subscription/reactivate
Example Request
Example Response JSON

Cancel Downgrade

PUT/v1/billing/customers/:customer_id/subscription/cancel_downgrade
Example Request
Example Response JSON

Estimate Plan

GET/v1/billing/customers/:customer_id/subscription/estimate/:plan_id
Example Request
Example Response JSON

Start or Extend Trial

POST/v1/billing/customers/:customer_id/subscription/trial
Example Request
Example Response JSON

Add coupon (before subscribed)

PUT/v1/billing/customers/:customer_id/subscription/coupon
Example Request
Example Response JSON

Add coupon (before subscribed, invalid coupon)

PUT/v1/billing/customers/:customer_id/subscription/coupon
Expected Response Status:
400
Example Request
Example Response JSON

Add coupon (to existing)

PUT/v1/billing/customers/:customer_id/subscription/coupon
Example Request
Example Response JSON

Cancel - immediately (Unathorized)

DELETE/v1/billing/customers/:customer_id/subscription
JSON Body Parameters:
data.end_of_termoptional
true if should cancel at end of term, otherwise it cancels immediately
Expected Response Status:
403
Example Request
Example Response JSON

Billing::Usage

List

GET/v1/billing/usages
Example Request
Example Response JSON

Retrieve

GET/v1/billing/usages/:id
Example Request
Example Response JSON

Candidates

Meta

GET/v1/candidates/meta
Example Request
Example Response JSON

List

GET/v1/candidates
URL Parameters:
includesoptionalString
team_member, assessments, assessment_results, solutions
sortoptional
Example: "last_name ASC"
pageoptionalInteger
The index of which page of results should be returned.
field_countsoptional
An array of fields which should have their aggregate values counted.
Example Request
Example Response JSON

Retrieve

GET/v1/candidates/:id
URL Parameters:
idrequiredString
Object ID
includesoptionalString
team_massessmenter, jobs, assessment_results, solutions
metaoptional
Currently only "enums" is supported, which will return information for dropdown fields
Example Request
Example Response JSON

Update

Updates a candidate. Only the admins and the candidate themself are allowed access.

PUT/v1/candidates/:id
JSON Body Parameters:
data.angellistOauthoptional
Hash/object with oauth token information
data.emailoptional
A valid email
data.first_nameoptional
data.first name
data.githubOauthoptional
Hash/object with oauth token information
data.last_nameoptional
data.last name
data.linkedinaOauthoptional
Hash/object with oauth token information
data.phoneoptional
data.ui_prefsoptional
A json object for storing custom client-side preferences
Example Request
Example Response JSON

Delete

Deletes the candidate. Admin-Only.

DELETE/v1/candidates/:id
Expected Response Status:
204
Example Request

Delete

Not allowed; Only admins can delete a candidate.

DELETE/v1/candidates/:id
Expected Response Status:
403
Example Request
Example Response JSON

Challenges

General endpoints for working with various types of challenges. The $type parameter will often be warranted as it will allow you to specify the type of challenge that should be handled.

List

Returns all Qualified and team challenges. You can limit results by type or collection to refine the results.

GET/v1/challenges
URL Parameters:
collectionoptional
if provided will filter by either `"team"` or `"global"` (qualified) challenges.
Accepted Values:
global team
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
copied_from created_by solutions sourced_from
templatesoptional
If set to true, will return only templates. By default everything but templates are returned.
$typeoptional
The type of challenge to filter by.
Accepted Values:
AdvancedCodeChallenge CodeChallenge QuizChallenge
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
order_byoptionalString
i.e. "createdAt DESC"
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
_type assessment_ids demo_data difficulty digest.content_type digest.in_library digest.languages.name digest.submitted_solutions_count id labels languages languages.name library library_access q state title topics
Example Request
Example Response JSON

List (Commons Collection)

Returns all commons challenges (available to all teams). Only team members and admins can use this endpoint.

GET/v1/challenges
URL Parameters:
collectionoptional
if provided will filter by either `"team"` or `"global"` (qualified) challenges.
Accepted Values:
global team
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
copied_from created_by solutions sourced_from
templatesoptional
If set to true, will return only templates. By default everything but templates are returned.
$typeoptional
The type of challenge to filter by.
Accepted Values:
AdvancedCodeChallenge CodeChallenge QuizChallenge
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
order_byoptionalString
i.e. "createdAt DESC"
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
_type assessment_ids demo_data difficulty digest.content_type digest.in_library digest.languages.name digest.submitted_solutions_count id labels languages languages.name library library_access q state title topics
Example Request
Example Response JSON

List (Team Collection)

Returns all challenges scoped to the user's current team. Only team members and admins can use this endpoint.

GET/v1/challenges
URL Parameters:
collectionoptional
if provided will filter by either `"team"` or `"global"` (qualified) challenges.
Accepted Values:
global team
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
copied_from created_by solutions sourced_from
templatesoptional
If set to true, will return only templates. By default everything but templates are returned.
$typeoptional
The type of challenge to filter by.
Accepted Values:
AdvancedCodeChallenge CodeChallenge QuizChallenge
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
order_byoptionalString
i.e. "createdAt DESC"
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
_type assessment_ids demo_data difficulty digest.content_type digest.in_library digest.languages.name digest.submitted_solutions_count id labels languages languages.name library library_access q state title topics
Example Request
Example Response JSON

List (Filter by language)

Returns all challenges scoped to the user's current team. Only team members and admins can use this endpoint.

GET/v1/challenges
URL Parameters:
collectionoptional
if provided will filter by either `"team"` or `"global"` (qualified) challenges.
Accepted Values:
global team
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
copied_from created_by solutions sourced_from
templatesoptional
If set to true, will return only templates. By default everything but templates are returned.
$typeoptional
The type of challenge to filter by.
Accepted Values:
AdvancedCodeChallenge CodeChallenge QuizChallenge
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
order_byoptionalString
i.e. "createdAt DESC"
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
_type assessment_ids demo_data difficulty digest.content_type digest.in_library digest.languages.name digest.submitted_solutions_count id labels languages languages.name library library_access q state title topics
Example Request
Example Response JSON

Retrieve

Retrieves a challenge of any $type by ID.

GET/v1/challenges/:id
URL Parameters:
idrequiredString
The ID of the challenge you wish to retrieve. This can either be a Qualified library challenge or a one associated to your team.
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
copied_from created_by revisions solutions sourced_from
Example Request
Example Response JSON
Notable Response Fields

Create Classic Code Challenge

Create a Classic Code Challenge (simply called CodeChallenge within the API). You should specify "CodeChallenge" as the $type.

POST/v1/challenges
JSON Body Parameters:
data.$typerequired
The type of challenge to create. For this example you are required to pass "CodeChallenge"
data.difficultyoptionalInteger

A value from 1 - 4 indicating how difficult the challenge is. Lower is easier.

data.enforce_all_tests_on_publishoptionalBoolean

True if all tests should be verified on publish. Default is true.

data.estimated_timeoptionalInteger

Time, in minutes, that indicates how long candidates should expect to spend on the challenge.

data.instructionsoptionalString

The markdown compatible instructions to give to the candidate.

data.languagesoptionalArray

An array of language objects that define settings on a per language basis.

Child Parameters
data.purposeoptionalString

An internal summary used to clarify to your team what the challenge is for.

data.sample_test_cases_enabledoptionalBoolean

True if sample test cases should be shown to candidates.

data.sample_test_cases_read_onlyoptionalBoolean

True if sample test cases should be readonly for candidates.

data.summaryoptionalString

A short description of the challenge, shown to the candidate before they start it.

data.titlerequiredunique String

The title of the challenge to refer to it by. This title will not be shown to candidates.

data.topicsoptionalArray

An array of strings indicating the topics this challenge focuses on. Useful for defining a simple skill or competency structure.

Example Request
Example Response JSON
Notable Response Fields

Create Project Code Challenge

Create a Project Code Challenge (called AdvancedCodeChallenge within the API). You should specify "AdvancedCodeChallenge" as the $type. Note that this is an advanced API. Please contact us if you plan on using it so that we can discuss its usage further.

POST/v1/challenges
JSON Body Parameters:
data.$typerequired
The type of challenge to create. For this example you are required to pass "CodeChallenge"
data.candidate_tests_enabledoptionalBoolean

True if the candidate should be able to run tests. Default is true.

data.difficultyoptionalInteger

A value from 1 - 4 indicating how difficult the challenge is. Lower is easier.

data.enable_external_idoptionalString

True if the candidate should be allowed to use their own IDE, and connect to the code execution engine using Qualified's attach tool.

Accepted Values:
default disabled enabled
data.enforce_all_tests_on_publishoptionalBoolean

True if all tests should be verified on publish. Default is true.

data.estimated_timeoptionalInteger

Time, in minutes, that indicates how long candidates should expect to spend on the challenge.

data.file_structure_lockedoptionalBoolean

True if the candidate is not allowed to add, rename or delete files.

data.filesoptionalArray

An array of objects indicating the files that should be included within the challenge.

Child Parameters
data.instructionsoptionalString

The markdown compatible instructions to give to the candidate.

data.limit_submission_attemptsoptionalInteger

The maximum number of times a candidate can submit the challenge before being locked from making any more changes. Null indicates unlimited attempts (default).

data.purposeoptionalString

An internal summary used to clarify to your team what the challenge is for.

data.reference_filesoptionalArray

An array of objects representing the reference files for the challenge, which provide a fully working solution to be tested against. A reference files will be used instead of any non-reference file if the paths are the same. See files for schema.

data.run_configrequired

Determines runtime settings for executing the tests.

Child Parameters
data.submission_feedbackoptionalBoolean

True if the candidate should be shown the results of their submission, allowing them to see which tests they failed and to make corrections.

data.summaryoptionalString

A short description of the challenge, shown to the candidate before they start it.

data.titlerequiredunique String

The title of the challenge to refer to it by. This title will not be shown to candidates.

data.topicsoptionalArray

An array of strings indicating the topics this challenge focuses on. Useful for defining a simple skill or competency structure.

Example Request
Example Response JSON
Notable Response Fields

Create Q&A Challenge

Create a Q&A Challenge (called QuizChallenge within the API). You should specify "QuizChallenge" as the $type.

POST/v1/challenges
JSON Body Parameters:
data.$typerequired
The type of challenge to create. For this example you are required to pass "QuizChallenge"
data.difficultyoptionalInteger

A value from 1 - 4 indicating how difficult the challenge is. Lower is easier.

data.estimated_timeoptionalInteger

Time, in minutes, that indicates how long candidates should expect to spend on the challenge.

data.instructionsoptionalString

The markdown compatible instructions to give to the candidate.

data.purposeoptionalString

An internal summary used to clarify to your team what the challenge is for.

data.question_time_limit_secoptionalInteger

The number of seconds the candidate has to complete the challenge. Only relevant if time_limit_type is set to a per_question type.

data.questionsoptionalArray

An array of question objects. See Quiz Questions resource for more details on schema.

data.summaryoptionalString

A short description of the challenge, shown to the candidate before they start it.

data.time_limit_typeoptionalString

Determines if and how the challenge should be timed.

Accepted Values:
challenge none per_question per_question_bonus
data.titlerequiredunique String

The title of the challenge to refer to it by. This title will not be shown to candidates.

data.topicsoptionalArray

An array of strings indicating the topics this challenge focuses on. Useful for defining a simple skill or competency structure.

Example Request
Example Response JSON
Notable Response Fields

Update

Updates an existing challenge. If a challenge is published, it will remained published with the new updates. _You must specify the $type parameter so that the API knows how to process the specific type of challenge update._

PUT/v1/challenges/:id
URL Parameters:
idrequiredString
The ID of the challenge you wish to update
$typerequiredString
The type of challenge being updated.
Accepted Values:
AdvancedCodeChallenge CodeChallenge QuizChallenge
JSON Body Parameters:
data.candidate_tests_enabledoptionalBoolean

True if the candidate should be able to run tests. Default is true.

Only Relevant On $type:
AdvancedCodeChallenge
data.difficultyoptionalInteger

A value from 1 - 4 indicating how difficult the challenge is. Lower is easier.

data.enable_external_idoptionalString

True if the candidate should be allowed to use their own IDE, and connect to the code execution engine using Qualified's attach tool.

Accepted Values:
default disabled enabled
Only Relevant On $type:
AdvancedCodeChallenge
data.enforce_all_tests_on_publishoptionalBoolean

True if all tests should be verified on publish. Default is true.

Only Relevant On $type:
AdvancedCodeChallengeCodeChallenge
data.estimated_timeoptionalInteger

Time, in minutes, that indicates how long candidates should expect to spend on the challenge.

data.file_structure_lockedoptionalBoolean

True if the candidate is not allowed to add, rename or delete files.

Only Relevant On $type:
AdvancedCodeChallenge
data.filesoptionalArray

An array of objects indicating the files that should be included within the challenge.

Only Relevant On $type:
AdvancedCodeChallenge
Child Parameters
data.instructionsoptionalString

The markdown compatible instructions to give to the candidate.

data.languagesoptionalArray

An array of language objects that define settings on a per language basis.

Only Relevant On $type:
CodeChallenge
Child Parameters
data.limit_submission_attemptsoptionalInteger

The maximum number of times a candidate can submit the challenge before being locked from making any more changes. Null indicates unlimited attempts (default).

Only Relevant On $type:
AdvancedCodeChallenge
data.purposeoptionalString

An internal summary used to clarify to your team what the challenge is for.

data.question_time_limit_secoptionalInteger

The number of seconds the candidate has to complete the challenge. Only relevant if time_limit_type is set to a per_question type.

Only Relevant On $type:
QuizChallenge
data.questionsoptionalArray

An array of question objects. See Quiz Questions resource for more details on schema.

Only Relevant On $type:
QuizChallenge
data.reference_filesoptionalArray

An array of objects representing the reference files for the challenge, which provide a fully working solution to be tested against. A reference files will be used instead of any non-reference file if the paths are the same. See files for schema.

Only Relevant On $type:
AdvancedCodeChallenge
data.run_configoptional

Determines runtime settings for executing the tests.

Only Relevant On $type:
AdvancedCodeChallenge
Child Parameters
data.sample_test_cases_enabledoptionalBoolean

True if sample test cases should be shown to candidates.

Only Relevant On $type:
CodeChallenge
data.sample_test_cases_read_onlyoptionalBoolean

True if sample test cases should be readonly for candidates.

Only Relevant On $type:
CodeChallenge
data.submission_feedbackoptionalBoolean

True if the candidate should be shown the results of their submission, allowing them to see which tests they failed and to make corrections.

Only Relevant On $type:
AdvancedCodeChallenge
data.summaryoptionalString

A short description of the challenge, shown to the candidate before they start it.

data.time_limit_typeoptionalString

Determines if and how the challenge should be timed.

Accepted Values:
challenge none per_question per_question_bonus
Only Relevant On $type:
QuizChallenge
data.titleoptionalunique String

The title of the challenge to refer to it by. This title will not be shown to candidates.

data.topicsoptionalArray

An array of strings indicating the topics this challenge focuses on. Useful for defining a simple skill or competency structure.

Example Request
Example Response JSON
Notable Response Fields

Delete

Deletes a challenge. Some challenges may not be deletable if they are actively being used on an assessment.

DELETE/v1/challenges/:id
URL Parameters:
idrequiredString
The ID of the challenge you wish to destroy.
Expected Response Status:
204
Example Request

Un-Publish

Converts a published challenge back to a draft state. This operation is not available if the challenge is associated to a published assessment.

PUT/v1/challenges/:id/unpublish
URL Parameters:
idrequiredString
The ID of the challenge you wish to unpublish.
Example Request
Example Response JSON
Notable Response Fields

Publish

Publishes a challenge, making it available to be used within assessments. USE EXTREME CAUTION! The Qualified UI typically validates code before publishing. This endpoint does not do any validation, so if you publish a challenge directly through the API, you may be publishing a challenge which is not passable by candidates.

PUT/v1/challenges/:id/publish
URL Parameters:
idrequiredString
The ID of the challenge you wish to publish.
Example Request
Example Response JSON
Notable Response Fields

Archive

Archives a challenge, making it unavailable to be used on assessments. This operation is not available if the challenge is associated to a published assessment.

PUT/v1/challenges/:id/archive
URL Parameters:
idrequiredString
The ID of the challenge you wish to archive.
Example Request
Example Response JSON
Notable Response Fields

Archive (with API key)

PUT/v1/challenges/:id/archive
URL Parameters:
idrequiredString
The ID of the challenge you wish to archive.
Example Request
Example Response JSON
Notable Response Fields

Un-archive

Un-archives a challenge, converted it back to its previous state.

PUT/v1/challenges/:id/unarchive
URL Parameters:
idrequiredString
The ID of the challenge you wish to unarchive.
Example Request
Example Response JSON
Notable Response Fields

Make Shared (non-admin)

PUT/v1/challenges/:id/duplicate_to_shared
URL Parameters:
idrequiredString
base16 ObjectId
Expected Response Status:
403
Example Request
Example Response JSON

Make Shared (unpublished)

PUT/v1/challenges/:id/duplicate_to_shared
URL Parameters:
idrequiredString
base16 ObjectId
Expected Response Status:
422
Example Request
Example Response JSON
Notable Response Fields

Make Shared (admin)

PUT/v1/challenges/:id/duplicate_to_shared
URL Parameters:
idrequiredString
base16 ObjectId
Example Request
Example Response JSON

Import

Imports a qualified library challenge into the team library. Can also be used to copy team challenges to a new version.

POST/v1/challenges/:id/import
URL Parameters:
idrequiredString
The ID of the challenge you wish to import.
Example Request
Example Response JSON
Notable Response Fields

Export

Makes a copy of a challenge on the team provided. The user must have access to both teams to export the challenge.

POST/v1/challenges/:id/export
URL Parameters:
idrequiredString
The ID of the challenge you wish to export.
JSON Body Parameters:
data.export_torequiredString
ID of the team the challenge should be exported to.
Example Request
Example Response JSON

Code Challenges

List (Global Collection)

GET/v1/code_challenges
URL Parameters:
collectionoptional
pass "team" to return team challenges, otherwise global challenges will be returned
includesoptionalString
team, created_by, solutions, revisions
Example Request
Example Response JSON

List

GET/v1/code_challenges
URL Parameters:
collectionoptional
pass "team" to return team challenges, otherwise global challenges will be returned
includesoptionalString
team, created_by, solutions, revisions
Example Request
Example Response JSON

Retrieve

GET/v1/code_challenges/:id
URL Parameters:
idrequiredString
base16 ObjectId
Example Request
Example Response JSON

Create

POST/v1/code_challenges
JSON Body Parameters:
data.difficultyoptional
data.enforce_all_tests_on_publishoptional
True if all tests should pass on publish, otherwise only a single test must pass. Default is true for new records
data.estimated_timeoptional
data.estimated time
data.instructionsoptional
data.languagesoptional
An array of language objects.
data.purposeoptional
data.sample_test_cases_enabledoptional
True if the candidate should be allowed to write their own sample test cases
data.stateoptional
The state of the challenge, can be published, draft or archived
data.summaryoptional
data.titleoptional
data.topicsoptional
Example Request
Example Response JSON

Update

PUT/v1/code_challenges/:id
URL Parameters:
idrequiredString
base16 ObjectId
JSON Body Parameters:
data.difficultyoptional
data.enforce_all_tests_on_publishoptional
True if all tests should pass on publish, otherwise only a single test must pass. Default is true for new records
data.estimated_timeoptional
data.estimated time
data.instructionsoptional
data.languagesoptional
An array of language objects. Provide a removed: true value if you wish to remove an existing challenge language
data.purposeoptional
data.sample_test_cases_enabledoptional
True if the candidate should be allowed to write their own sample test cases
data.summaryoptional
data.titlerequired
data.topicsoptional
Example Request
Example Response JSON

Update and return revisions

PUT/v1/code_challenges/:id
URL Parameters:
idrequiredString
base16 ObjectId
JSON Body Parameters:
data.difficultyoptional
data.enforce_all_tests_on_publishoptional
True if all tests should pass on publish, otherwise only a single test must pass. Default is true for new records
data.estimated_timeoptional
data.estimated time
data.instructionsoptional
data.languagesoptional
An array of language objects. Provide a removed: true value if you wish to remove an existing challenge language
data.purposeoptional
data.sample_test_cases_enabledoptional
True if the candidate should be allowed to write their own sample test cases
data.summaryoptional
data.titlerequired
data.topicsoptional
Example Request
Example Response JSON

Update + Publish

PUT/v1/code_challenges/:id
URL Parameters:
idrequiredString
base16 ObjectId
JSON Body Parameters:
data.difficultyoptional
data.enforce_all_tests_on_publishoptional
True if all tests should pass on publish, otherwise only a single test must pass. Default is true for new records
data.estimated_timeoptional
data.estimated time
data.instructionsoptional
data.languagesoptional
An array of language objects. Provide a removed: true value if you wish to remove an existing challenge language
data.purposeoptional
data.sample_test_cases_enabledoptional
True if the candidate should be allowed to write their own sample test cases
data.summaryoptional
data.titlerequired
data.topicsoptional
Example Request
Example Response JSON

Update (Using $type)

PUT/v1/challenges/:id
URL Parameters:
idrequiredString
base16 ObjectId
$typerequired
Model type. CodeChallenge
JSON Body Parameters:
data.difficultyoptional
data.estimated_timeoptional
data.estimated time
data.instructionsoptional
data.languagesoptional
An array of language objects. Provide a removed: true value if you wish to remove an existing challenge language
data.purposeoptional
data.summaryoptional
data.titleoptional
data.topicsoptional
Example Request
Example Response JSON

Delete

DELETE/v1/code_challenges/:id
Expected Response Status:
204
Example Request

Code Solutions

Create

Creates a new code solution. The solution should always be created as soon as a candidate begins a challenge.

POST/v1/code_solutions
JSON Body Parameters:
data.assessment_result_idrequiredString
data.assessment result
data.challenge_idrequiredString
data.challenge
data.languagerequired
initial language the user started in
Example Request
Example Response JSON

Update

Updates the latest code that the user has authored. Each update results in a revision being created. This example has included "revisions" in order to demonstrate the update behavior.

PUT/v1/code_solutions/:id
JSON Body Parameters:
data.codeoptional
The user's solution code
data.languageoptional
The language that the user is taking the challenge in
data.messageoptional
a revision message
data.tagoptional
a revision tag
data.test_casesoptional
The user's test case code
Example Request
Example Response JSON

Log Attempt

This endpoint is called directly by the code runner service, after code is executed, in order to report the result back to the server.

PUT/v1/code_solutions/:id/log_attempt
JSON Body Parameters:
data.coderequired
The user's solution
data.languagerequired
The programming language used
data.responserequired
Hash representing the response from the CodeRunner run
data.test_casesoptional
The user's test cases. These are passed through simply for logging their test cases as part of the snapshot
Example Request
Example Response JSON

Log Test

This endpoint is called directly by the code runner service, after code is executed, in order to report the tests results back to the server.

PUT/v1/code_solutions/:id/log_test
JSON Body Parameters:
data.coderequired
The user's solution
data.languagerequired
The programming language used
data.responserequired
Hash representing the response from the CodeRunner run
data.test_casesoptional
The user's test cases. These are passed through simply for logging their test cases as part of the snapshot
Example Request
Example Response JSON

Revisions

GET/v1/code_solutions/:id/revisions
Example Request
Example Response JSON

Emails

Meta

GET/v1/emails/meta
Example Request
Example Response JSON

Retrieve

GET/v1/emails/
Example Request
Example Response JSON

Retrieve

GET/v1/emails/:id
URL Parameters:
idrequiredString
base16 ObjectId
Example Request
Example Response JSON

Embed Assessment

Embed Assessment

POST/v1/embed_assessment/:assessment_id
URL Parameters:
embed_client_keyrequired
embed client key associated with team account
embed_domainrequired
indicates the parent domain that the embed is within
Expected Response Status:
204
Example Request

Embed Assessment without auth

POST/v1/embed_assessment/:assessment_id
URL Parameters:
embed_client_keyrequired
embed client key associated with team account
embed_domainrequired
indicates the parent domain that the embed is within
Expected Response Status:
401
Example Request
Example Response JSON

Embed Assessment with wrong domain

POST/v1/embed_assessment/:assessment_id
URL Parameters:
embed_client_keyrequired
embed client key associated with team account
embed_domainrequired
indicates the parent domain that the embed is within
Expected Response Status:
422
Example Request
Example Response JSON

Embed Challenge

Embed Challenge

POST/v1/embed_challenge/:id
URL Parameters:
embed_client_keyrequired
embed client key associated with team account
embed_domainrequired
indicates the parent domain that the embed is within
dataoptional
data to be passed to newly created solution
auto_startoptional
true if the assessment result should be started, and solution created
Example Request
Example Response JSON

Embed Challenge with Auto Start

POST/v1/embed_challenge/:id
URL Parameters:
embed_client_keyrequired
embed client key associated with team account
embed_domainrequired
indicates the parent domain that the embed is within
dataoptional
data to be passed to newly created solution
auto_startoptional
true if the assessment result should be started, and solution created
Example Request
Example Response JSON

Embed Challenge without auth

POST/v1/embed_challenge/:id
URL Parameters:
embed_client_keyrequired
embed client key associated with team account
embed_domainrequired
indicates the parent domain that the embed is within
dataoptional
data to be passed to newly created solution
auto_startoptional
true if the assessment result should be started, and solution created
Example Request
Example Response JSON

Embed Challenge without auth and not embeddable

POST/v1/embed_challenge/:id
URL Parameters:
embed_client_keyrequired
embed client key associated with team account
embed_domainrequired
indicates the parent domain that the embed is within
dataoptional
data to be passed to newly created solution
auto_startoptional
true if the assessment result should be started, and solution created
Expected Response Status:
401
Example Request
Example Response JSON

Embed Challenge without auth and wrong domain

POST/v1/embed_challenge/:id
URL Parameters:
embed_client_keyrequired
embed client key associated with team account
embed_domainrequired
indicates the parent domain that the embed is within
dataoptional
data to be passed to newly created solution
auto_startoptional
true if the assessment result should be started, and solution created
Expected Response Status:
422
Example Request
Example Response JSON

ExternalEvidenceResults

External evidence refers to data gathered from outside Qualified, such as an interview.

List

Returns a paged list of all external evidence results for your team.

GET/v1/external_evidence_results
URL Parameters:
order_byoptionalString
ie: "title DESC"
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Retrieve

Returns external evidence result for authenticated users.

GET/v1/external_evidence_results/:id
URL Parameters:
idrequiredString
The ID of the external evidence result you wish to retrieve.
Example Request
Example Response JSON

Create

Creates a new external evidence result.

POST/v1/external_evidence_results
Example Request
Example Response JSON

Update

Updates an existing external evidence result.

PUT/v1/external_evidence_results/:id
URL Parameters:
idrequiredObjectId
ExternalEvidenceResult ID
Example Request
Example Response JSON

Delete

Deletes the external evidence result

DELETE/v1/external_evidence_results/:id
URL Parameters:
idrequiredObjectId
ExternalEvidenceResult ID
Expected Response Status:
204
Example Request

ExternalEvidences

External evidence refers to data gathered from outside Qualified, such as an interview.

List

Returns a paged list of all external evidences for your team.

GET/v1/external_evidences
URL Parameters:
order_byoptionalString
ie: "title DESC"
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Retrieve

Returns external evidence for authenticated users.

GET/v1/external_evidences/:id
URL Parameters:
idrequiredString
The ID of the external evidence you wish to retrieve.
Example Request
Example Response JSON

Create

Creates a new external evidence.

POST/v1/external_evidences
Example Request
Example Response JSON

Update

Updates an existing external evidence.

PUT/v1/external_evidences/:id
URL Parameters:
idrequiredObjectId
ExternalEvidence ID
Example Request
Example Response JSON

Delete

Deletes the external evidence

DELETE/v1/external_evidences/:id
URL Parameters:
idrequiredObjectId
ExternalEvidence ID
Expected Response Status:
204
Example Request

Interview Result Reviews

Interview Result Reviews are the overall review opinion left by team members. These reviews are used to provide feedback on the quality of an interview. Individual interview step result reviews are then associated to each interview result review. There is one review per interviewer/interview result.

List

Returns a paged list of all reviews for the team.

GET/v1/interview_result_reviews
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
interview interview_result reviewed_by team_candidate
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
candidate_id created_at id interview_id interview_result_id reviewed_by_id team_candidate_id
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
order_byoptionalString
i.e. "createdAt DESC"
Example Request
Example Response JSON

Retrieve

Retrieves a single interview result review by ID.

GET/v1/interview_result_reviews/:id
URL Parameters:
idrequiredString
The ID of the review you wish to retrieve
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
interview interview_result reviewed_by team_candidate
Example Request
Example Response JSON

Create

Creates an interview result review. There can only be one review per interview result & reviewer.

POST/v1/interview_result_reviews
JSON Body Parameters:
data.feedbackoptionalString

Feedback given by the reviewer. Markdown is supported.

data.interview_result_idrequiredString
The ID of the interview result being reviewed.
data.interview_result_idoptionalObject

The ID of the solution being reviewed.

data.ratingoptionalInteger

Subjective rating. 1 - 5, for a 3 point system use 1,3 and 5 as your values.

data.reviewed_by_idrequiredString
The ID of the user who will be doing the assessing. Only one reviewer per assessment result is allowed.
data.reviewed_by_idoptionalObject

The ID of the team member who reviewed the candidate.

Example Request
Example Response JSON

Update

Update the feedback or rating given by a reviewer.

PUT/v1/interview_result_reviews/:id
URL Parameters:
idrequiredString
The ID of the review you wish to update
JSON Body Parameters:
data.feedbackoptionalString

Feedback given by the reviewer. Markdown is supported.

data.interview_result_idoptionalObject

The ID of the solution being reviewed.

data.ratingoptionalInteger

Subjective rating. 1 - 5, for a 3 point system use 1,3 and 5 as your values.

data.reviewed_by_idoptionalObject

The ID of the team member who reviewed the candidate.

Example Request
Example Response JSON

Delete

Deletes an interview result review. Deletes any associated interview step result reviews as well.

DELETE/v1/interview_result_reviews/:id
URL Parameters:
idrequiredString
The ID of the review you wish to delete
Expected Response Status:
204
Example Request

InterviewResults

An interview result is a collection of evidence from a candidate's interview.

List

Returns a paged list of all interview results for your team.

GET/v1/interview_results
URL Parameters:
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Create

Creates a new interview result. This is the intended method of inviting a candidate to an interview.

POST/v1/interview_results
JSON Body Parameters:
data.interview_idrequiredString

The ID of the interview the interview result is being to be based on.

data.interviewer_idrequiredString

The ID of the team member who will be conducting the interview.

data.notesrequiredString

Notes on the candidate regarding the interview.

data.team_candidate_idrequiredString

The ID of the candidate that will be invited into the interview

Example Request
Example Response JSON

Create

Updates an existing interview result.

PUT/v1/interview_results/:id
URL Parameters:
idrequiredObjectId
Interview Result ID
JSON Body Parameters:
data.interview_idrequiredString

The ID of the interview the interview result is being to be based on.

data.interviewer_idrequiredString

The ID of the team member who will be conducting the interview.

data.notesrequiredString

Notes on the candidate regarding the interview.

data.team_candidate_idrequiredString

The ID of the candidate that will be invited into the interview

Example Request
Example Response JSON

Start

Sets an interview as having started and redirects to the meeting URL

PUT/v1/interview_results/:id/start
URL Parameters:
idrequiredObjectId
Interview Result ID
Example Request
Example Response JSON

End

Sets an interview as having finished

PUT/v1/interview_results/:id/end
URL Parameters:
idrequiredObjectId
Interview Result ID
Example Request
Example Response JSON

Confirm

Sets an interview as confirmed by a team member. Confirmation notes are required, even if they are an empty string.

PUT/v1/interview_results/:id/confirm
URL Parameters:
idrequiredObjectId
Interview Result ID
JSON Body Parameters:
data.confirmation_notesrequiredString
data.confirmation notes
Example Request
Example Response JSON

Cancel

Cancels an interview result.

PUT/v1/interview_results/:id/cancel
URL Parameters:
idrequiredObjectId
Interview Result ID
JSON Body Parameters:
data.cancellation_reasonrequiredString
data.cancellation reason
Example Request
Example Response JSON

InterviewStepItems

A interview contains one or more assessments.

Create

Creates a new interview step item.

POST/v1/interviews/:interview_id/steps/
URL Parameters:
interview_idoptionalObjectId
Interview ID
JSON Body Parameters:
data.interview_idoptionalObjectId
InterviewStepID
Example Request
Example Response JSON

Delete

Deletes the interview step item

DELETE/v1/interviews/:interview_id/steps/:id
URL Parameters:
interview_idoptionalObjectId
Interview ID
idrequiredObjectId
InterviewStepItem ID
Expected Response Status:
204
Example Request

InterviewSteps

An interview step is a section composing a specific part of an interview_step.

List

Returns a paged list of all interview_steps for your team.

GET/v1/interview_steps
URL Parameters:
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Create

Retrieves an existing interview step.

GET/v1/interview_steps/:id
URL Parameters:
idrequiredObjectId
Interview Plan ID
Example Request
Example Response JSON

Create

Creates a new interview step.

POST/v1/interview_steps
JSON Body Parameters:
data.descriptionoptionalString

The description of the interview step. Supports markdown.

data.live_assessmentoptionalBoolean

Whether this step pertains to a live assessment. Default is false

data.time_estimaterequiredInteger

The time estimate of the step.

data.titlerequiredString

The title of the interview step

Example Request
Example Response JSON

Update

Updates an interview step.

PUT/v1/interview_steps/:id
URL Parameters:
idrequiredObjectId
Interview Plan ID
Example Request
Example Response JSON

Interviews

An interview is a template on which to base candidate interviews.

List

Returns a paged list of all interviews for your team.

GET/v1/interviews
URL Parameters:
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Create

Retrieves an existing interview.

GET/v1/interviews/:id
URL Parameters:
idrequiredObjectId
Interview Plan ID
Example Request
Example Response JSON

Create

Creates a new interview.

POST/v1/interviews
JSON Body Parameters:
data.interviewer_idrequiredString

The ID of the team member who will be conducting the interview.

data.notesrequiredString

Notes on the candidate regarding the interview.

data.prep_itemsoptionalArray

A list of items belonging to the candidate a team member can use to confirm the interview.

Child Parameters
data.stepsoptionalArray

A list of interview step items that compose the interview.

Child Parameters
data.support_materialsoptionalArray

A list of materials to help interviewers through the interview process.

Child Parameters
data.titlerequiredString

The title of the interview

Example Request
Example Response JSON

Update

Updates an interview.

PUT/v1/interviews/:id
URL Parameters:
idrequiredObjectId
Interview ID
JSON Body Parameters:
data.interviewer_idrequiredString

The ID of the team member who will be conducting the interview.

data.notesrequiredString

Notes on the candidate regarding the interview.

data.prep_itemsoptionalArray

A list of items belonging to the candidate a team member can use to confirm the interview.

Child Parameters
data.stepsoptionalArray

A list of interview step items that compose the interview.

Child Parameters
data.support_materialsoptionalArray

A list of materials to help interviewers through the interview process.

Child Parameters
data.titlerequiredString

The title of the interview

Example Request
Example Response JSON

Label History

Each time a label is added or removed, it is recorded.

List

Returns a paged list of recent history items.

GET/v1/label_histories
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
added_by removed_by
pageoptionalInteger
The index of which page of results should be returned.
limitoptionalInteger
The limit on how many results can be returned. This value determines the page size.
order_byoptionalString
i.e. "createdAt DESC"
Example Request
Example Response JSON

Notes

Notes can be attached to candidates in order to track miscellaneous information that you want to keep attached. These notes are shown on the candidate profile.

List

Returns a paged list of notes. Utilize the notable ID query param to only return notes for a specific resource.

GET/v1/notes
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
notable user
notable_idoptionalString
id of the parent the note belongs to. Currently only team candidates are supported.
Example Request
Example Response JSON

Retrieve

Retrieves a specific note by ID.

GET/v1/notes/:id
URL Parameters:
idrequiredString
ID of the note to retrieve
Example Request
Example Response JSON

Create

Creates a new note for the given resource.

POST/v1/notes
JSON Body Parameters:
data.bodyoptionalString

The text content of the note.

data.notable_idrequiredString
id of the parent the note belongs to
data.notable_typerequired
type of the parent. Defaults to TeamCandidate
Example Request
Example Response JSON

Update

Update the body of an existing note.

PUT/v1/notes/:id
URL Parameters:
idrequiredString
The ID of the note to update
JSON Body Parameters:
data.bodyoptionalString

The text content of the note.

Example Request
Example Response JSON

Delete

Deletes a note from the system.

DELETE/v1/notes/:id
URL Parameters:
idrequiredString
The ID of the note to delete.
Expected Response Status:
204
Example Request

PathwayResults

Pathway result is the resulting record of a team candidate undertaking a pathway

List

Returns a paged list of all pathway results for your team.

GET/v1/pathway_results
URL Parameters:
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Create

Creates a new pathway result. This is the intended method of inviting a candidate to a pathway.

POST/v1/pathway_results
JSON Body Parameters:
data.emailrequiredString

The email of the candidate that will be invited into the pathway process. If missing, then a TeamCandidate ID must be provided.

data.first_nameoptionalString

First name of candidate. Will only be used if the candidate is new.

data.initial_stepoptionalArray

Pathway step on which the candidate should start. If not set, the default is the first step in the pathway.

data.labelsoptionalArray

An array of label strings to assign to the candidate. Any value can be used, it does not need to be previously defined.

data.last_nameoptionalString

Last name of candidate. Will only be used if the candidate is new.

data.pathway_idrequiredString

The ID of the pathway candidates are being invited to. If missing, then a PathwaySet ID must be provided.

data.pathway_set_idrequiredString

The ID of the pathway set candidates are being invited to. If missing, then a Pathway ID must be provided.

data.retry_actionoptionalString

Retry action to apply on assessments within the pathway previously passed by the candidate. If not set, previously passed assessments will be skipped.

Accepted Values:
"reopen":Reopens the assessment result when the candidate visits the assessment. The candidate will be able to resume where they left off.
"retake":The candidate will be asked to start a new assessment, without carrying any previous work over. The original assessment result data will be kept as a separate record, and the new retake will be the featured result within the Qualified team UI.
data.rule_tagsrequiredArray

Array of tags associated with the candidate. Must be provided, even as an empty array.

data.team_candidate_idrequiredString

The ID of the candidate that will be invited into the pathway process. If missing, then an email must be provided.

Example Request
Example Response JSON
Notable Response Fields

Terminate

Terminates the pathway result

PUT/v1/pathway_results/:id/terminate
URL Parameters:
idrequiredObjectId
Pathway Result ID
Expected Response Status:
204
Example Request

PathwaySets

A pathway set is a container for one or more pathways.

List

Returns a paged list of all pathway sets for your team.

GET/v1/pathway_sets
URL Parameters:
order_byoptionalString
ie: "title DESC"
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Retrieve

Returns pathway set for authenticated users.

GET/v1/pathway_sets/:id
URL Parameters:
idrequiredString
The ID of the pathway set you wish to retrieve.
Example Request
Example Response JSON

Create

Creates a new pathway set.

POST/v1/pathway_sets
JSON Body Parameters:
data.pathway_itemsrequiredArray

Pathway items to represent the pathways that will be part of the set.

Child Parameters
data.selection_actionoptionalString

Method by which the pathway set will select the pathway to be taken. If not set, the default is 'weighted_random'.

Accepted Values:
most_recently_published weighted_random
data.selection_preferenceoptionalString

The preference for which pathway to select. If not set, the default is 'not_started'.

Accepted Values:
not_completed not_started
data.titlerequiredString

What this pathway set will be titled as.

Example Request
Example Response JSON

Update

Updates an existing pathway set.

PUT/v1/pathway_sets/:id
URL Parameters:
idrequiredObjectId
PathwaySet ID
JSON Body Parameters:
data.pathway_itemsoptionalArray

Pathway items to represent the pathways that will be part of the set.

Child Parameters
data.selection_actionoptionalString

Method by which the pathway set will select the pathway to be taken. If not set, the default is 'weighted_random'.

Accepted Values:
most_recently_published weighted_random
data.selection_preferenceoptionalString

The preference for which pathway to select. If not set, the default is 'not_started'.

Accepted Values:
not_completed not_started
data.titleoptionalString

What this pathway set will be titled as.

Example Request
Example Response JSON

Rules

Returns available rule tags for an existing pathway set.

GET/v1/pathway_sets/:id/rules
URL Parameters:
idrequiredObjectId
PathwaySet ID
Example Request
Example Response JSON

Delete

Deletes the pathway set

DELETE/v1/pathway_sets/:id
URL Parameters:
idrequiredObjectId
PathwaySet ID
Expected Response Status:
204
Example Request

PathwayStepOptions

A pathway step option represents one of the branches a team candidate will go through when going through a pathway step

Create

Creates a new pathway step option.

POST/v1/pathways/:pathway_id/steps/:pathway_step_id/options
JSON Body Parameters:
data.assessment_idrequiredString

ID of the assessment to use if the option is selected. If this field is missing, either assessment_set_id, interview_id or external_evidence_id must be set.

data.assessment_set_idrequiredString

ID of the assessment set to use if the option is selected. If this field is missing, either assessment_id, interview_id or external_evidence_id must be set.

data.external_evidence_idrequiredString

ID of the external evidence to use if the option is selected. If this field is missing, either assessment_set_id, interview_id or assessment_id must be set.

data.interview_assessment_set_idoptionalString

ID of an assessment set to be used alongside an interview. This field is mandatory and only usable if an interview is set.

data.interview_idoptionalString

ID of the interview to use if the option is selected. If this field is missing, either assessment_set_id, external_evidence_id or assessment_id must be set.

data.selection_actionoptionalString

Method by which the pathway set will select the pathway to be taken. If not set, the default is 'weighted_random'.

Accepted Values:
most_recently_published weighted_random
data.selection_preferenceoptionalString

The preference for which pathway to select. If not set, the default is 'not_started'.

Accepted Values:
not_completed not_started
data.selection_rulesrequiredObject

The rules that determine which options can be chosen on a given step.

Child Parameters
data.titlerequiredString

What this pathway step option will be titled as.

Example Request
Example Response JSON

Update

Updates an existing pathway step option.

PUT/v1/pathways/:pathway_id/steps/:pathway_step_id/options/:id
URL Parameters:
pathway_idoptionalObjectId
Pathway ID
pathway_step_idoptionalObjectId
PathwayStep ID
idrequiredObjectId
PathwayStepOption ID
JSON Body Parameters:
data.assessment_idoptionalString

ID of the assessment to use if the option is selected. If this field is missing, either assessment_set_id, interview_id or external_evidence_id must be set.

data.assessment_set_idoptionalString

ID of the assessment set to use if the option is selected. If this field is missing, either assessment_id, interview_id or external_evidence_id must be set.

data.external_evidence_idoptionalString

ID of the external evidence to use if the option is selected. If this field is missing, either assessment_set_id, interview_id or assessment_id must be set.

data.interview_assessment_set_idoptionalString

ID of an assessment set to be used alongside an interview. This field is mandatory and only usable if an interview is set.

data.interview_idoptionalString

ID of the interview to use if the option is selected. If this field is missing, either assessment_set_id, external_evidence_id or assessment_id must be set.

data.selection_actionoptionalString

Method by which the pathway set will select the pathway to be taken. If not set, the default is 'weighted_random'.

Accepted Values:
most_recently_published weighted_random
data.selection_preferenceoptionalString

The preference for which pathway to select. If not set, the default is 'not_started'.

Accepted Values:
not_completed not_started
data.selection_rulesoptionalObject

The rules that determine which options can be chosen on a given step.

Child Parameters
data.titleoptionalString

What this pathway step option will be titled as.

Example Request
Example Response JSON

Delete

Deletes the pathway step option

DELETE/v1/pathways/:pathway_id/steps/:pathway_step_id/options/:id
URL Parameters:
pathway_idoptionalObjectId
Pathway ID
pathway_step_idoptionalObjectId
PathwayStep ID
idrequiredObjectId
PathwayStepOption ID
Expected Response Status:
204
Example Request

PathwayStepResults

A pathway step result is the resulting record of a team candidate going through a pathway step.

Activate

Activates a new available pathway step result.

PUT/v1/pathway_results/:pathway_result_id/step_results/:id/activate
URL Parameters:
pathway_result_idoptionalObjectId
Pathway Result ID
idrequiredObjectId
PathwayStepResult ID
Example Request
Example Response JSON

Skip

Skips the given pathway step result and activates the next one

PUT/v1/pathway_results/:pathway_result_id/step_results/:id/skip
URL Parameters:
pathway_result_idoptionalObjectId
Pathway Result ID
idrequiredObjectId
PathwayStepResult ID
Example Request
Example Response JSON

Move to

Moves the pathway to the given pathway step result.

PUT/v1/pathway_results/:pathway_result_id/step_results/:id/move_to
URL Parameters:
pathway_result_idoptionalObjectId
Pathway Result ID
idrequiredObjectId
PathwayStepResult ID
Example Request
Example Response JSON

PathwaySteps

A pathway step represents the stages a candidate will go through when undertaking a pathway.

Create

Creates a new pathway step.

POST/v1/pathways/:pathway_id/steps/
URL Parameters:
pathway_idoptionalObjectId
Pathway ID
JSON Body Parameters:
data.empty_selection_actionoptionalString

Action to be taken if the option selection comes up empty. Default is 'skip_step'.

Accepted Values:
pathway_error skip_step
data.fail_actionoptionalString

Action to be taken if a step result is failed. Default is 'reject'.

Accepted Values:
reject skip
data.flag_actionoptionalString

Action to be taken if a step result is flagged. Default is 'ignore'.

Accepted Values:
fail ignore require_review
data.flag_rulesoptionalPathwayStepFlagRules

The rules that determine if a step result is flagged. By default, all values are null.

Child Parameters
data.milestone_keyrequiredString

Key used externally as a milestone identifier

data.multi_selection_actionoptionalString

Action to be taken if the option selection returns several valid options. Default is 'select_first'.

Accepted Values:
pathway_error random select_first select_first_unattempted
data.pass_rulesoptionalPathwayStepPassRules

The rules that determine if a step result passes. By default, all values are null.

Child Parameters
data.process_workflow_rulesoptionalBoolean

Set as false by default, if set to true regular workflows will be processed.

data.titlerequiredString

What this pathway step will be titled as.

Example Request
Example Response JSON

Update

Updates an existing pathway step.

PUT/v1/pathways/:pathway_id/steps/:id
URL Parameters:
pathway_idoptionalObjectId
Pathway ID
idrequiredObjectId
PathwayStep ID
JSON Body Parameters:
data.empty_selection_actionoptionalString

Action to be taken if the option selection comes up empty. Default is 'skip_step'.

Accepted Values:
pathway_error skip_step
data.fail_actionoptionalString

Action to be taken if a step result is failed. Default is 'reject'.

Accepted Values:
reject skip
data.flag_actionoptionalString

Action to be taken if a step result is flagged. Default is 'ignore'.

Accepted Values:
fail ignore require_review
data.flag_rulesoptionalPathwayStepFlagRules

The rules that determine if a step result is flagged. By default, all values are null.

Child Parameters
data.milestone_keyoptionalString

Key used externally as a milestone identifier

data.multi_selection_actionoptionalString

Action to be taken if the option selection returns several valid options. Default is 'select_first'.

Accepted Values:
pathway_error random select_first select_first_unattempted
data.pass_rulesoptionalPathwayStepPassRules

The rules that determine if a step result passes. By default, all values are null.

Child Parameters
data.process_workflow_rulesoptionalBoolean

Set as false by default, if set to true regular workflows will be processed.

data.titleoptionalString

What this pathway step will be titled as.

Example Request
Example Response JSON

Delete

Deletes the pathway step

DELETE/v1/pathways/:pathway_id/steps/:id
URL Parameters:
pathway_idoptionalObjectId
Pathway ID
idrequiredObjectId
PathwayStep ID
Expected Response Status:
204
Example Request

Pathways

A pathway consists of a series of pathway steps, each intended to evaluate a candidate in some manner.

List

Returns a paged list of all pathways for your team.

GET/v1/pathways
URL Parameters:
order_byoptionalString
ie: "title DESC"
pageoptionalInteger
Default = 1
Example Request
Example Response JSON

Retrieve

Returns pathway for authenticated users.

GET/v1/pathways/:id
URL Parameters:
idrequiredString
The ID of the pathway you wish to retrieve.
Example Request
Example Response JSON

Create

Creates a new pathway.

POST/v1/pathways
JSON Body Parameters:
data.labelsoptionalArray

An array of label strings to assign to the pathway. Any value can be used, it does not need to be previously defined.

data.max_retakesoptionalInteger

The maximum number of times a candidate can retake the pathway. If set to -1, then unlimited retakes are allowed. The default value is 0.

data.metadataoptionalObject

Additional data on the pathway. This is a free form object that can be used to store any data you wish to associate with the pathway.

data.retake_cooldown_daysoptionalInteger

Number of days that must pass before a candidate can retake the pathway.

data.stateoptionalSymbol

The state of the pathway. On creation the default value is "draft". A pathway needs at least two existing steps before being published.

Accepted Values:
archived draft published
data.titlerequiredString

What this pathway will be titled as.

data.version_numberoptionalInteger

What iteration of the pathway this is. The default value is 1.

Example Request
Example Response JSON

Update

Updates an existing pathway.

PUT/v1/pathways/:id
URL Parameters:
idrequiredObjectId
Pathway ID
JSON Body Parameters:
data.labelsoptionalArray

An array of label strings to assign to the pathway. Any value can be used, it does not need to be previously defined.

data.max_retakesoptionalInteger

The maximum number of times a candidate can retake the pathway. If set to -1, then unlimited retakes are allowed. The default value is 0.

data.metadataoptionalObject

Additional data on the pathway. This is a free form object that can be used to store any data you wish to associate with the pathway.

data.retake_cooldown_daysoptionalInteger

Number of days that must pass before a candidate can retake the pathway.

data.stateoptionalSymbol

The state of the pathway. On creation the default value is "draft". A pathway needs at least two existing steps before being published.

Accepted Values:
archived draft published
data.titleoptionalString

What this pathway will be titled as.

data.version_numberoptionalInteger

What iteration of the pathway this is. The default value is 1.

Example Request
Example Response JSON

Delete

Deletes the pathway

DELETE/v1/pathways/:id
URL Parameters:
idrequiredObjectId
Pathway ID
Expected Response Status:
204
Example Request

Product::ChangeLog

List

GET/v1/product_change_logs
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Example Request
Example Response JSON

Retrieve

GET/v1/product_change_logs/:id
Example Request
Example Response JSON

Create

POST/v1/product_change_logs
JSON Body Parameters:
data.foorequired
Example Request
Example Response JSON

Update

PUT/v1/product_change_logs/:id
JSON Body Parameters:
data.foorequired
Example Request
Example Response JSON

Delete

DELETE/v1/product_change_logs/:id
Expected Response Status:
204
Example Request

Product::Releases

List

Returns most recent 100 releases

GET/v1/product_releases
Example Request
Example Response JSON

Viewed

POST/v1/product_releases/viewed
Expected Response Status:
204
Example Request

Quiz Challenges

List (Global Collection)

GET/v1/quiz_challenges
URL Parameters:
collectionoptional
pass "team" to return team challenges, otherwise global challenges will be returned
includesoptionalString
team, created_by, solutions, revisions
Example Request
Example Response JSON

List

GET/v1/quiz_challenges
URL Parameters:
collectionoptional
pass "team" to return team challenges, otherwise global challenges will be returned
includesoptionalString
team, created_by, solutions, revisions
Example Request
Example Response JSON

Retrieve

GET/v1/quiz_challenges/:id
URL Parameters:
idrequiredString
base16 ObjectId
Example Request
Example Response JSON

Create

POST/v1/quiz_challenges
JSON Body Parameters:
data.difficultyoptional
data.estimated_timeoptional
data.estimated time
data.instructionsoptional
data.purposeoptional
data.stateoptional
The state of the challenge, can be published, draft or archived
data.summaryoptional
data.titleoptional
data.topicsoptional
Example Request
Example Response JSON

Update

PUT/v1/quiz_challenges/:id
URL Parameters:
idrequiredString
base16 ObjectId
JSON Body Parameters:
data.difficultyoptional
data.estimated_timeoptional
data.estimated time
data.instructionsoptional
data.purposeoptional
data.summaryoptional
data.titlerequired
data.topicsoptional
Example Request
Example Response JSON

Update + Publish

PUT/v1/quiz_challenges/:id
URL Parameters:
idrequiredString
base16 ObjectId
JSON Body Parameters:
data.difficultyoptional
data.estimated_timeoptional
data.estimated time
data.instructionsoptional
data.purposeoptional
data.summaryoptional
data.titlerequired
data.topicsoptional
Example Request
Example Response JSON

Delete

DELETE/v1/quiz_challenges/:id
Expected Response Status:
204
Example Request

Quiz Questions

One or more QuizQuestions are associated to a QuizChallenge (aka "Q&A Challenge"). These questions define the questions that a candidate will be given.

List

Returns a list of questions for a particular quiz challenge. You can also pull these down by retrieving the QuizChallenge itself.

GET/v1/quiz_questions?challengeId=:challenge_id
URL Parameters:
challenge_idrequiredString
The ID of the challenge to return questions for.
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
revisions
Example Request
Example Response JSON

Retrieve

Retrieves an existing quiz question by ID. Useful if you need a specific question and do not want to load the parent QuizChallenge (which would have this information nested within it).

GET/v1/quiz_questions/:id
URL Parameters:
idrequiredString
The ID of the question you wish to retrieve.
challenge_idoptionalString
Recommended for faster question lookup.
Example Request
Example Response JSON

Create

Creates a quiz question for a QuizChallenge. $type must be provided to specify the type of question being created. $type cannot be changed once the record is created.

POST/v1/quiz_questions
JSON Body Parameters:
data.$typerequired

The model type of the question.

Accepted Values:
QuizTextQuestion QuizWeightedChoiceQuestion
data.all_or_nothingoptionalBoolean

True if fractional scoring should not be performed.

data.challenge_idrequiredString

The ID of the challenge to add the question to.

data.choicesoptionalArray

An array of objects defining what choices should be available for the question.

Only Relevant On $type:
QuizWeightedChoiceQuestion
Child Parameters
data.default_valueoptionalString

Provide a default answer text if you want the candidate to modify something, such as performing a manually-scored refactoring or other text transformation.

Only Relevant On $type:
QuizTextQuestion
data.matchesoptionalArray

An array of objects used to calculate score by matching answer text.

Only Relevant On $type:
QuizTextQuestion
Child Parameters
data.max_charactersoptionalInteger

The maximum number of characters that an answer can have.

Only Relevant On $type:
QuizTextQuestion
data.max_selectionsoptionalInteger

The total number of choices a candidate can select.

Only Relevant On $type:
QuizWeightedChoiceQuestion
data.max_sumoptionalFloat

The maximum sum that can be scored. Useful when using multiple weighted choices and it is possible to weight higher than the total that you may wish to score.

Only Relevant On $type:
QuizWeightedChoiceQuestion
data.min_charactersoptionalInteger

The minimum number of characters that an answer needs to have.

Only Relevant On $type:
QuizTextQuestion
data.positionoptionalInteger

The 1 based position of the challenge within the list. Will be auto-set to the end of the list if omitted.

data.promptrequiredString

The question prompt. Markdown is supported.

data.weightoptionalFloat

The weight to assign to this question. The default is 1.

data.weighted_scoringoptionalBoolean

True if weighted scoring should be used. Otherwise all choices will count as an equal weight, regardless of what their individual weights are set as.

Only Relevant On $type:
QuizWeightedChoiceQuestion
Example Request
Example Response JSON

Update

Updates an existing question on a QuizChallenge.

PUT/v1/quiz_questions/:id
URL Parameters:
idrequiredString
The ID of the question you wish to update.
challenge_idoptionalString
Recommended for faster question lookup.
JSON Body Parameters:
data.$typeoptional

The model type of the question.

Accepted Values:
QuizTextQuestion QuizWeightedChoiceQuestion
data.all_or_nothingoptionalBoolean

True if fractional scoring should not be performed.

data.challenge_idoptionalString

The ID of the challenge to add the question to.

data.choicesoptionalArray

An array of objects defining what choices should be available for the question.

Only Relevant On $type:
QuizWeightedChoiceQuestion
Child Parameters
data.default_valueoptionalString

Provide a default answer text if you want the candidate to modify something, such as performing a manually-scored refactoring or other text transformation.

Only Relevant On $type:
QuizTextQuestion
data.matchesoptionalArray

An array of objects used to calculate score by matching answer text.

Only Relevant On $type:
QuizTextQuestion
Child Parameters
data.max_charactersoptionalInteger

The maximum number of characters that an answer can have.

Only Relevant On $type:
QuizTextQuestion
data.max_selectionsoptionalInteger

The total number of choices a candidate can select.

Only Relevant On $type:
QuizWeightedChoiceQuestion
data.max_sumoptionalFloat

The maximum sum that can be scored. Useful when using multiple weighted choices and it is possible to weight higher than the total that you may wish to score.

Only Relevant On $type:
QuizWeightedChoiceQuestion
data.min_charactersoptionalInteger

The minimum number of characters that an answer needs to have.

Only Relevant On $type:
QuizTextQuestion
data.positionoptionalInteger

The 1 based position of the challenge within the list. Will be auto-set to the end of the list if omitted.

data.promptoptionalString

The question prompt. Markdown is supported.

data.weightoptionalFloat

The weight to assign to this question. The default is 1.

data.weighted_scoringoptionalBoolean

True if weighted scoring should be used. Otherwise all choices will count as an equal weight, regardless of what their individual weights are set as.

Only Relevant On $type:
QuizWeightedChoiceQuestion
Example Request
Example Response JSON

Delete

Deletes the specified quiz question from the associated QuizChallenge. The operation is not reversible, the question data will be lost.

DELETE/v1/quiz_questions/:id
URL Parameters:
idrequiredString
The ID of the question you wish to delete.
challenge_idoptionalString
Recommended for faster question lookup.
Expected Response Status:
204
Example Request

Quiz Solutions

Create

Creates a new solution of the type specified. This is an alias endpoint for the subtype specific route. See each type specific section for more details. For this example, this route is actually linking to the POST /v1/qui_solutions route.

POST/v1/solutions
JSON Body Parameters:
data.$typerequired
The type of solution to create
data.assessment_result_idrequiredString
data.assessment result
data.challenge_idrequiredString
data.challenge
data.languagerequired
initial language the user started in
Example Request
Example Response JSON

Update

This route is used as an alias to the subtype specific update. For example, this example maps to PUT /quiz_solutions/:id

PUT/v1/solutions/:id
JSON Body Parameters:
data.$typerequired
The type of solution to create
data.messageoptional
a revision message
data.tagoptional
a revision tag
Example Request
Example Response JSON

Simple Preview

POST/v1/quiz_solutions/score_preview
Example Request
Example Response JSON

Unsaved Preview

POST/v1/quiz_solutions/score_preview
Example Request
Example Response JSON

Sessions

Create

Authenticates the user credentials and returns an auth token

POST/v1/sessions
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
JSON Body Parameters:
data.$typeoptional
The type of user to return. If provided, will error if different type of user was found
data.emailoptional
A valid email
data.oauthoptional
oauth data returned by oauth service
data.oauth_provideroptional
oauth provider to login with, optionally used instead of email/password
data.passwordoptional
Password
Example Request
Example Response JSON

Create (with includes)

Authenticates the user credentials and returns an auth token. This example demonstrates how both a team_member and candidate can be returned as json data.

POST/v1/sessions
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
JSON Body Parameters:
data.$typeoptional
The type of user to return. If provided, will error if different type of user was found
data.emailoptional
A valid email
data.oauthoptional
oauth data returned by oauth service
data.oauth_provideroptional
oauth provider to login with, optionally used instead of email/password
data.passwordoptional
Password
Example Request
Example Response JSON

Create (using oauth)

Authenticates the user using their OAuth access token

POST/v1/sessions
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
JSON Body Parameters:
data.$typeoptional
The type of user to return. If provided, will error if different type of user was found
data.emailoptional
A valid email
data.oauthoptional
oauth data returned by oauth service
data.oauth_provideroptional
oauth provider to login with, optionally used instead of email/password
data.passwordoptional
Password
Example Request
Example Response JSON

Impersonate a team members candidate user

POST/v1/sessions/shadow
Example Request
Example Response JSON

Create (with enforced type)

Authenticates the user credentials and returns an auth token. The user found must match the type specified. A 404 will be returned if a user with the type specified is not found. When providing the type parameter, only one object type token will be returned, and the resource will always be returned as data.

POST/v1/sessions
JSON Body Parameters:
data.$typerequired
The type of user that must be present. Values = Candidate, TeamMember, Admin
data.emailrequired
A valid email
data.passwordrequired
Password
Example Request
Example Response JSON

Solution Reviews

Solution reviews are individual review data given by each reviewer, for a given solution. Each solution review will be associated to a parent assessment result review. This API currently supports subjective ratings and feedback only, contact us if you wish to use objective ratings via a rubric.

List

Returns a paged list of solution reviews.

GET/v1/solution_reviews
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment assessment_result assessment_result_review challenge reviewed_by team_candidate
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
assessment_result_id assessment_result_review_id id reviewed_by_id solution_id team_candidate_id
Example Request
Example Response JSON

Retrieve

Retrieves a specific solution review.

GET/v1/solution_reviews/:id
URL Parameters:
idrequiredString
The ID of the solution review you wish to retrieve
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment assessment_result assessment_result_review challenge reviewed_by team_candidate
Example Request
Example Response JSON

Create

Creates a new solution review record. There can be only one record per reviewed_by_id/solution_id pairing. This record must be associated to an existing assessment result review.

POST/v1/solution_reviews
JSON Body Parameters:
data.assessment_result_review_idrequiredObject

The ID of the assessment result review this.

data.feedbackoptionalString

Feedback given by the reviewer. Markdown is supported.

data.ratingoptionalInteger

Subjective rating. 1 - 5, for a 3 point system use 1,3 and 5 as your values.

data.reviewed_by_idrequiredObject

The ID of the team member who reviewed the candidate.

data.solution_idrequiredObject

The ID of the solution being reviewed.

Example Request
Example Response JSON

Update

Updates an existing solution review.

PUT/v1/solution_reviews/:id
URL Parameters:
idrequiredString
The ID if the review you wish to update.
JSON Body Parameters:
data.feedbackoptionalString

Feedback given by the reviewer. Markdown is supported.

data.ratingoptionalInteger

Subjective rating. 1 - 5, for a 3 point system use 1,3 and 5 as your values.

Example Request
Example Response JSON

Delete

Deletes an existing solution review.

DELETE/v1/solution_reviews/:id
URL Parameters:
idrequiredString
The ID if the review you wish to delete.
Expected Response Status:
204
Example Request

Solutions

Solutions are the result of a candidate taking a challenge. Available endpoints are relevant for all solution sub-types.

List

Returns a paged listed of solutions.

GET/v1/solutions
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_result candidate challenge cloned_from clones similarity
challenge_idoptionalString
ID of the challenge you wish to filter by.
assessment_result_idoptionalString
ID of the assessment result you wish to filter by.
Example Request
Example Response JSON

List (Assessment Result Scope)

GET/v1/solutions
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_result candidate challenge cloned_from clones similarity
challenge_idoptionalString
ID of the challenge you wish to filter by.
assessment_result_idoptionalString
ID of the assessment result you wish to filter by.
Example Request
Example Response JSON

List (Valid Where Params)

GET/v1/solutions
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_result candidate challenge cloned_from clones similarity
challenge_idoptionalString
ID of the challenge you wish to filter by.
assessment_result_idoptionalString
ID of the assessment result you wish to filter by.
Example Request
Example Response JSON

List (Invalid Where Params)

GET/v1/solutions
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_result candidate challenge cloned_from clones similarity
challenge_idoptionalString
ID of the challenge you wish to filter by.
assessment_result_idoptionalString
ID of the assessment result you wish to filter by.
Example Request
Example Response JSON

Retrieve

Retrieves a solution by ID. Fields returned depend on the type of solution.

GET/v1/solutions/:id
URL Parameters:
idrequiredString
The ID of the solution you wish to retrieve.
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_result candidate challenge cloned_from clones similarity
Example Request
Example Response JSON

Get Similar

Returns similar solutions to that of the ID given. Only relevant for CodeSolution and AdvancedCodeSolution solution types. Similarity feature must be enabled on your subscription.

GET/v1/solutions/:id/similar
URL Parameters:
idrequiredString
The ID of the solution you wish to get similar solutions for.
Example Request
Example Response JSON

Create

Creates a new solution of the type specified. This is an alias endpoint for the subtype specific route. See each type specific section for more details. For this example, this route is actually linking to the POST /v1/code_solutions route.

POST/v1/solutions
JSON Body Parameters:
data.$typerequired
The type of solution to create
data.assessment_result_idrequiredString
data.assessment result
data.challenge_idrequiredString
data.challenge
data.languagerequired
initial language the user started in
Example Request
Example Response JSON

Fetch or Create

Fetches or creates a new solution of the type specified. This is an alias endpoint for the subtype specific route. See each type specific section for more details. For this example, this route is actually linking to the POST /v1/code_solutions route.

POST/v1/solutions
JSON Body Parameters:
data.$typerequired
The type of solution to create
data.assessment_result_idrequiredString
data.assessment result
data.challenge_idrequiredString
data.challenge
data.languagerequired
initial language the user started in
Example Request
Example Response JSON

Update

This route is used as an alias to the subtype specific update. For example, this example maps to PUT /code_solutions/:id

PUT/v1/solutions/:id
URL Parameters:
idrequiredString
The ID of the solution you wish to update.
JSON Body Parameters:
data.$typerequiredString
The type of the solution to update.
data.codeoptionalString
The user's solution code
data.messageoptionalString
a revision message
data.tagoptionalString
a revision tag
data.test_casesoptionalString
The user's test case code
Example Request
Example Response JSON

Team Candidates

Team Candidates are the users whom take an assessment. While they have their own user account, the TeamCandidate record is always data specific to your team.

List

Returns a paged list of team candidates.

GET/v1/team_candidates
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_invitations assessment_result_reviews assessment_results assessments assigned_team_members notes solution_reviews solutions
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
alternate_id archived assessment_ids assigned_team_member_ids cohort_ids created_at demo_data digest.interact_sessions_count digest.recently_abandoned digest.reviewed_by_ids email first_name id interact_sessions labels last_name name q reviewed_by_ids state state_updated_at test_team_member updated_at
Example Request
Example Response JSON

List (with API key)

Can use the API key to look up team members

GET/v1/team_candidates
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_invitations assessment_result_reviews assessment_results assessments assigned_team_members notes solution_reviews solutions
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
alternate_id archived assessment_ids assigned_team_member_ids cohort_ids created_at demo_data digest.interact_sessions_count digest.recently_abandoned digest.reviewed_by_ids email first_name id interact_sessions labels last_name name q reviewed_by_ids state state_updated_at test_team_member updated_at
Example Request
Example Response JSON

List (with includes)

GET/v1/team_candidates
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_invitations assessment_result_reviews assessment_results assessments assigned_team_members notes solution_reviews solutions
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
alternate_id archived assessment_ids assigned_team_member_ids cohort_ids created_at demo_data digest.interact_sessions_count digest.recently_abandoned digest.reviewed_by_ids email first_name id interact_sessions labels last_name name q reviewed_by_ids state state_updated_at test_team_member updated_at
Example Request
Example Response JSON

List (with archived filter)

GET/v1/team_candidates
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_invitations assessment_result_reviews assessment_results assessments assigned_team_members notes solution_reviews solutions
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
alternate_id archived assessment_ids assigned_team_member_ids cohort_ids created_at demo_data digest.interact_sessions_count digest.recently_abandoned digest.reviewed_by_ids email first_name id interact_sessions labels last_name name q reviewed_by_ids state state_updated_at test_team_member updated_at
Example Request
Example Response JSON

List (with assessment filter)

GET/v1/team_candidates
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_invitations assessment_result_reviews assessment_results assessments assigned_team_members notes solution_reviews solutions
whereoptional
A URI encoded JSON value indicating the query you wish to filter by.
Accepted Fields:
alternate_id archived assessment_ids assigned_team_member_ids cohort_ids created_at demo_data digest.interact_sessions_count digest.recently_abandoned digest.reviewed_by_ids email first_name id interact_sessions labels last_name name q reviewed_by_ids state state_updated_at test_team_member updated_at
Example Request
Example Response JSON

Retrieve

Retrieves a single team candidate by ID.

GET/v1/team_candidates/:id
URL Parameters:
idrequiredString
The ID of the candidate you wish to retrieve.
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_invitations assessment_result_reviews assessment_results assessments assigned_team_members notes solution_reviews solutions
Example Request
Example Response JSON

Get (with includes)

GET/v1/team_candidates/:id
URL Parameters:
idrequiredString
The ID of the candidate you wish to retrieve.
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
assessment_invitations assessment_result_reviews assessment_results assessments assigned_team_members notes solution_reviews solutions
Example Request
Example Response JSON

Update

Updates basic info for a team candidate.

PUT/v1/team_candidates/:id
URL Parameters:
idrequiredString
The ID of the candidate you wish to update.
JSON Body Parameters:
data.alternate_idoptionalString
Used for teams to track their own IDs alongside candidates.
data.blindingoptionalString
How the candidate should be blinded. By default they are blinded to blind_reviewers only
Accepted Values:
blind_reviewers none restricted team
data.emailoptionalString
A valid email for the candidate.
data.first_nameoptionalString
First name for the candidate.
data.labelsoptionalArray
An array of strings of all labels that should be assigned.
data.last_nameoptionalString
Last name for the candidate.
Example Request
Example Response JSON

Bulk Action

Takes an action on a set of candidates at once. In addition to performing an action (such as archiving), it also allows certain fields to be updated.

POST/v1/team_candidates/bulk_update
URL Parameters:
idsrequiredArray
ids of team candidates to process
bulk_actionrequiredString
The action to take.
Accepted Values:
approve archive cancel reject restore update
JSON Body Parameters:
data.add_labelsoptionalArray
Array of strings to add to the existing labels
data.add_noteoptionalString
a note to add to all candidates
data.remove_labelsoptionalArray
Array of strings to remove from the existing labels
Example Request
Example Response JSON

Approve

Approves a team candidate.

PUT/v1/team_candidates/:id/approve
URL Parameters:
idrequiredString
The ID of the candidate you wish to approve.
Example Request
Example Response JSON

Reject

Marks the candidate as rejected, a final decision state.

PUT/v1/team_candidates/:id/reject
URL Parameters:
idrequiredString
The ID of the candidate you wish to reject.
Example Request
Example Response JSON

Archive

Archives a candidate, moving them out of the inbox

PUT/v1/team_candidates/:id/archive
URL Parameters:
idrequiredString
The ID of the candidate you wish to archive.
Example Request
Example Response JSON

Unarchive

Restores candidate to pre-archived state.

PUT/v1/team_candidates/:id/unarchive
URL Parameters:
idrequiredString
The ID of the candidate you wish to un-archive.
Example Request
Example Response JSON

Restore

Restores the assessment result to its previous state.

PUT/v1/team_candidates/:id/restore
Example Request
Example Response JSON

Assign

Assigns team members to the candidate.

PUT/v1/team_candidates/:id/assign
URL Parameters:
idrequiredString
The ID of the candidate you wish to assign team members to.
JSON Body Parameters:
data.team_member_idsrequiredArray
An array of team member ids to assign.
Example Request
Example Response JSON

Assign (as a reviewer)

Only premium seats can assign team members

PUT/v1/team_candidates/:id/assign
URL Parameters:
idrequiredString
The ID of the candidate you wish to assign team members to.
JSON Body Parameters:
data.team_member_idsrequiredArray
An array of team member ids to assign.
Expected Response Status:
403
Example Request
Example Response JSON

Delete

DELETE/v1/team_candidates/:id
URL Parameters:
idrequiredString
The ID of the team candidate to delete.
Expected Response Status:
204
Example Request

Delete (not authorized)

DELETE/v1/team_candidates/:id
URL Parameters:
idrequiredString
The ID of the team candidate to delete.
Expected Response Status:
403
Example Request
Example Response JSON

Forget

Marks a candidate as forgotten, removing all PII data for GDPR purposes.

PUT/v1/team_candidates/:id/forget
URL Parameters:
idrequiredString
The ID of the candidate you wish to forget.
Example Request
Example Response JSON

Merge Into

Merges a team candidate into a target team candidate. This includes all assessment results, invitations, emails, and all related data. If both team candidates have results for the same assessment, the latest result will be set as the current take.

POST/v1/team_candidates/:id/merge_into/:target_id
URL Parameters:
idrequiredString
id of the team candidate to be merged
target_idrequiredString
ID of the target team candidate, into which all info will be merged.
Example Request
Example Response JSON

TeamMemberPrivileges

Update

Updates privileges on a team member.

PUT/v1/team_members/:id/privileges
URL Parameters:
idrequiredString
The ID of the TeamMember you wish to update privileges on.
Example Request
Example Response JSON

Team Members

Team members are the team's users within the system.

Meta

GET/v1/team_members/meta
Example Request
Example Response JSON

List

Returns all team members for the team.

GET/v1/team_members
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
authored_assessments authored_challenges
Example Request
Example Response JSON

List (with user auth)

GET/v1/team_members
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
authored_assessments authored_challenges
Example Request
Example Response JSON

List

Can pass an optional team id to look up team members by team if the user is qualified staff or admin

GET/v1/team_members
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
authored_assessments authored_challenges
Example Request
Example Response JSON

List

Returns all team members for a team member except staff members

GET/v1/team_members
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
authored_assessments authored_challenges
Example Request
Example Response JSON

Retrieve

Returns a single team member account.

GET/v1/team_members/:id
URL Parameters:
idrequiredString
The ID of the team member to be retrieved
includesoptionalString
One or more values indicating additional associated records that should be included.
Accepted Values:
authored_assessments authored_challenges
Example Request
Example Response JSON

Create

Creates a new team member user. This API is allowed only for authenticated admin and team owners.

POST/v1/team_members
JSON Body Parameters:
data.biooptional
data.emailrequiredString

A valid work email

data.first_namerequiredString

First name

data.last_namerequiredString

Last name

data.passwordoptionalString
The default password for the new member.
data.teamIdrequired
The team must be created first. Not required if team member is authenticated user
data.ui_prefsoptional
A json object for storing custom client-side preferences
Example Request
Example Response JSON

Update

Updates a team member.

PUT/v1/team_members/:id
URL Parameters:
idrequiredString
The ID of the team member to be updated
JSON Body Parameters:
data.emailoptionalString

A valid work email

data.first_nameoptionalString

First name

data.last_nameoptionalString

Last name

Example Request
Example Response JSON

Activate as a reviewer

reviewer cannot activate a team member

PUT/v1/team_members/:id/activate
URL Parameters:
idrequiredString
base16 ObjectId
Expected Response Status:
403
Example Request
Example Response JSON

Activate as an owner

Owner can activate a team member

PUT/v1/team_members/:id/activate
URL Parameters:
idrequiredString
base16 ObjectId
Example Request
Example Response JSON

Activate as an admin

Admin can activate a team member

PUT/v1/team_members/:id/activate
URL Parameters:
idrequiredString
base16 ObjectId
Example Request
Example Response JSON

Deactivate as a reviewer

reviewer cannot deactivate a team member

PUT/v1/team_members/:id/deactivate
URL Parameters:
idrequiredString
base16 ObjectId
Expected Response Status:
403
Example Request
Example Response JSON

Deactivate as an owner

Owner can deactivate a team member

PUT/v1/team_members/:id/deactivate
URL Parameters:
idrequiredString
base16 ObjectId
Example Request
Example Response JSON

Deactivate as an admin

Admin can deactivate a team member

PUT/v1/team_members/:id/deactivate
URL Parameters:
idrequiredString
base16 ObjectId
Example Request
Example Response JSON

Delete

Deletes a team member. Admins, team owners and the team member themself are allowed to do this operation.

DELETE/v1/team_members/:id
Expected Response Status:
204
Example Request

TeamNotification

List

Returns a paged list of TeamNotifications.

GET/v1/team_notifications
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Example Request
Example Response JSON

Retrieve

Retrieves an instance of a TeamNotification.

GET/v1/team_notifications/:id
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
idrequiredString
The ID of the TeamNotification you wish to retrieve
Example Request
Example Response JSON

Retrieve

Retrieves the latest instance of a team's TeamNotification.

GET/v1/team_notifications/latest
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Example Request
Example Response JSON

Create

Creates a new instance of a TeamNotification.

POST/v1/team_notifications
Example Request
Example Response JSON

Update

Updates an existing instance of a TeamNotification.

PUT/v1/team_notifications/:id
URL Parameters:
idrequiredString
The ID of the TeamNotification you wish to update.
Example Request
Example Response JSON

Delete

Deletes an existing instance of a TeamNotification.

DELETE/v1/team_notifications/:id
URL Parameters:
idrequiredString
The ID of the TeamNotification you wish to delete.
Expected Response Status:
204
Example Request

Teams

Meta

GET/v1/teams/meta
Example Request
Example Response JSON

Retrieve

GET/v1/teams/:id
URL Parameters:
idrequiredString
base16 Object ID
Example Request
Example Response JSON

Get (with library review qualities)

GET/v1/teams/:id
URL Parameters:
idrequiredString
base16 Object ID
Example Request
Example Response JSON

List

GET/v1/teams/
Example Request
Example Response JSON

Create

Creates a new team. This API is meant for authenticated admin users only.

POST/v1/teams
JSON Body Parameters:
data.logoImg.fileFormatoptional
data.logoimg.fileformat
data.logoImg.fileIdoptional
data.logoimg.fileid
data.logoImg.heightoptional
data.logoimg.height
data.logoImg.resourceTypeoptional
data.logoimg.resourcetype
data.logoImg.widthoptional
data.logoimg.width
data.logoUrloptional
data.logourl
data.namerequired
Example Request
Example Response JSON

Update

Updates a team. Only admins and team members are allowed to update

PUT/v1/teams/:id
JSON Body Parameters:
data.logoImg.cloudinaryIdoptional
data.logoimg.cloudinaryid
data.logoImg.fileTypeoptional
data.logoimg.filetype
data.logoImg.heightoptional
data.logoimg.height
data.logoImg.s3FileNameoptional
data.logoimg.s3filename
data.logoImg.widthoptional
data.logoimg.width
data.logoUrloptional
data.logourl
data.nameoptional
Example Request
Example Response JSON

Update (as another team member)

Should fail only team members and admins can update teams

PUT/v1/teams/:id
JSON Body Parameters:
data.logoImg.cloudinaryIdoptional
data.logoimg.cloudinaryid
data.logoImg.fileTypeoptional
data.logoimg.filetype
data.logoImg.heightoptional
data.logoimg.height
data.logoImg.s3FileNameoptional
data.logoimg.s3filename
data.logoImg.widthoptional
data.logoimg.width
data.logoUrloptional
data.logourl
data.nameoptional
Expected Response Status:
403
Example Request
Example Response JSON

UserFeedback

Create

POST/v1/user_feedbacks
Example Request
Example Response JSON

Users

List

Returns all users, no matter what type they are. Admin only access.

GET/v1/users
Example Request
Example Response JSON

Retrieve

Returns basic information about any type of user. Useful for when you are not sure of the user type. Admin only access.

GET/v1/users/:id
URL Parameters:
idrequiredString
Object ID
Example Request
Example Response JSON

WebhookEvent

List

Returns a paged list of WebhookEvents.

GET/v1/webhook_events
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
Example Request
Example Response JSON

Retrieve

Retrieves an instance of a WebhookEvent.

GET/v1/webhook_events/:id
URL Parameters:
includesoptionalString
One or more values indicating additional associated records that should be included.
idrequiredString
The ID of the WebhookEvent you wish to retrieve
Example Request
Example Response JSON

Webhook Examples

Resources for simulating and firing webhooks for a given resource and event. **Note** that the data returned is in snake case, as opposed to camel case. This is because webhook data does not support camel casing, unlike the data normally returned by the API.

Simulate Assessment Result Started Response

Return an example of what is sent from a webhook subscription after an assessment result is started.

GET/v1/webhook_examples/:id
URL Parameters:
idrequiredString
ID of the model to simulate
eventrequired
snake cased name of the event to simulate
typerequired
Resource type name to be simulated, i.e. Challenge
Example Request
Example Response JSON

Simulate Assessment Result Submitted Response

Return an example of what is sent from a webhook subscription after an assessment result is submitted.

GET/v1/webhook_examples/:id
URL Parameters:
idrequiredString
ID of the model to simulate
eventrequired
snake cased name of the event to simulate
typerequired
Resource type name to be simulated, i.e. Challenge
Example Request
Example Response JSON

Simulate Solution Updated Response

Return an example of what is sent from a webhook subscription after solution is updated.

GET/v1/webhook_examples/:id
URL Parameters:
idrequiredString
ID of the model to simulate
eventrequired
snake cased name of the event to simulate
typerequired
Resource type name to be simulated, i.e. Challenge
Example Request
Example Response JSON

Simulate Team Candidate State Changed Response

Return an example of what is sent from a webhook subscription after a team candidate's state is changed.

GET/v1/webhook_examples/:id
URL Parameters:
idrequiredString
ID of the model to simulate
eventrequired
snake cased name of the event to simulate
typerequired
Resource type name to be simulated, i.e. Challenge
Example Request
Example Response JSON

Trigger Solution Updated Hook

Triggers a web hook to be sent to the url provided, allowing you to test what its like for the system to send hooks

POST/v1/webhook_examples/:id
URL Parameters:
idrequiredString
ID of the model to trigger
eventrequired
snake cased name of the event to trigger
typerequired
Resource type name to be triggered, i.e. Challenge, Solution, TeamCandidate, Note
urlrequired
URL to send the webhook to
Example Request
Example Response JSON

Webhook Subscriptions

Endpoints for managing your web subscriptions. The Qualified UI currently only supports a single subscription, but more can be managed programmatically via this API.

List

Returns all webhook subscriptions for the team.

GET/v1/webhook_subscriptions
Example Request
Example Response JSON

Retrieve

Retrieves a specific webhook subscription.

GET/v1/webhook_subscriptions/:id
URL Parameters:
idrequiredString
The ID of the subscription you wish to retrieve.
Example Request
Example Response JSON

Create

Creates a new webhook subscription. You can manage multiple subscriptions via the API.

POST/v1/webhook_subscriptions
JSON Body Parameters:
data.event_triggersrequiredObject

An object containing webhook event names as keys and true/false as values indicating that they are enabled or not.

Accepted Values:
assessment_created assessment_destroyed assessment_published assessment_result_merged assessment_result_review_created assessment_result_review_destroyed assessment_result_review_submitted assessment_result_review_updated assessment_result_started assessment_result_state_changed assessment_result_submitted assessment_updated challenge_created challenge_destroyed challenge_published challenge_updated external_evidence_invite_created note_created pathway_interview_booking_created pathway_interview_booking_updated pathway_result_created pathway_result_state_changed pathway_step_result_created pathway_step_result_state_changed solution_created solution_updated team_candidate_label_added team_candidate_label_removed team_candidate_merged team_candidate_started_assessment team_candidate_state_changed team_candidate_submitted_assessment
data.urlrequiredString

URL that should be called whenever one of the subscribed webhook events is triggered.

Example Request
Example Response JSON

Update

Updates an existing webhook subscription.

PUT/v1/webhook_subscriptions/:id
URL Parameters:
idrequiredString
The ID of the subscription you wish to update.
JSON Body Parameters:
data.event_triggersoptionalObject

An object containing webhook event names as keys and true/false as values indicating that they are enabled or not.

Accepted Values:
assessment_created assessment_destroyed assessment_published assessment_result_merged assessment_result_review_created assessment_result_review_destroyed assessment_result_review_submitted assessment_result_review_updated assessment_result_started assessment_result_state_changed assessment_result_submitted assessment_updated challenge_created challenge_destroyed challenge_published challenge_updated external_evidence_invite_created note_created pathway_interview_booking_created pathway_interview_booking_updated pathway_result_created pathway_result_state_changed pathway_step_result_created pathway_step_result_state_changed solution_created solution_updated team_candidate_label_added team_candidate_label_removed team_candidate_merged team_candidate_started_assessment team_candidate_state_changed team_candidate_submitted_assessment
data.urloptionalString

URL that should be called whenever one of the subscribed webhook events is triggered.

Example Request
Example Response JSON

Delete

Deletes a webhook subscription using its ID.

DELETE/v1/webhook_subscriptions/:id
URL Parameters:
idrequiredString
The ID of the subscription you wish to delete.
Expected Response Status:
204
Example Request

Delete By Url

Deletes a webhook subscription by matching the webhook URL to the one provided.

DELETE/v1/webhook_subscriptions/url?url=:url
URL Parameters:
urlrequired
The webhook URL of the subscription you wish to delete.
Expected Response Status:
204
Example Request