On this page

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.

Premium Feature

API Access is only available on our custom plans.

Authorization

Authorization is done by passing in an API key to the Authorization header. If your account is on a plan that allows API access then you will be able to find your key by going to Team Settings > Integrations within the Qualified app.

Generating an API Key

On the API Access page you'll be able to generate a new API key if you don't have one already or in case you believe your current API key could have been compromised. Once you generate a new key, the old key is no longer valid. Keep it a secret!

API key shown within team integrations settings page
API key shown within team integrations settings page
API Key Safety

Make sure to keep your API key safe. Do not expose it through client-side applications.

Authorization Header

All resource endpoints should be requested using the authorization header. In the example requests shown below for each resource, you can see where this value would be set. You should replace :api_key with your actual API key.

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

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 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 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

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

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

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

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.

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

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

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

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

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_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 note_created solution_created solution_updated team_candidate_label_added team_candidate_label_removed 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_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 note_created solution_created solution_updated team_candidate_label_added team_candidate_label_removed 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