> For the complete documentation index, see [llms.txt](https://developers.talentlyft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.talentlyft.com/partner-api-reference/assessments.md).
# Assessments
After employers have sourced, recruited and attracted talent, the evaluation begins. Assessment testing is an extremely important part of every successful hiring strategy.
## **Why bother integrating assessment tools with recruiting tools?**
Employers perform different types of assessment tests based on their culture, positions and expectations. Assessment test are one of the best ways for confirming that you have found your candidate persona.
Hiring the right person has an influence on many things that happen after a candidate is hired. These include candidate’s satisfaction, performance, length of stay, his or her word of mouth and engagement with the company.
Recruiting and candidate assessment can be more streamlined if the two tools are integrated. By integrating your assessment tool with TalentLyft you can ensure much faster and easier assessment of existing candidates in TalentLyft’s talent pools. Your users can now test candidates using your assessment tool within TalentLyft’s candidate pools.
Together, we can provide better experience to our users!
{% hint style="info" %}
**Join the TalentLyft API Partner Program**
To apply join the TalentLyft Partner Partner program or to gain deeper access to the API, [complete the application form](https://get.talentlyft.com/en/partner-program) telling us about the product or service that you provide.
{% endhint %}
## Workflows
## Listing available tests in TalentLyft
TalentLyft needs access to the tests from assessments provider. Assessment provider endpoint should be formatted as `https://${BASE_URL}/tests` and the response should be a JSON document with an array of tests.
```javascript
[
{
"Id": "1",
"Name": ".NET Middle Developer - ASP.NET - RESTful reservations application ",
"Description": "Contains following tasks: 1. Choice questions - assessing...",
"Language": "en",
"LearnMore": null,
"AssessmentTypes": "BehavioralAssessment",
"Price": [{
"Currency": "USD",
"Value": 30
},
{
"Currency": "EUR",
"Value": 25
}
]
},
{
"Id": "2",
"Name": ".NET Middle Developer - ASP.NET - RESTful reservations application ",
"Description": "Contains following tasks: 1. Choice questions - assessing...",
"Language": "en",
"LearnMore": null,
"AssessmentTypes": "BehavioralAssessment",
"Price": [{
"Currency": "USD",
"Value": 30
},
{
"Currency": "EUR",
"Value": 25
}
]
}
]
```
| Key | Type | Description |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| TestId\* | `string` | The identification provided in the previous step |
| Name\* | `string` | Test title (max 80 characters) |
| Description\* | `string` | Test description (max 80 characters) |
| Language\* | `string` | [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), default value is "en" |
| LearnMore | `string` | External url to test details |
| AssessmentTypes | `string` | This can take any of the values:
BehavioralAssessmentSkillsTest
|
| Price\* | `array` | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) → USD price is mandatory |
## TalentLyft Ordering an Assessment
TalentLyft provides users with the ability to create an assessment for a candidate on demand. If the action is called, TalentLyft will `POST` the Assessments Provider on `https://${BASE_URL}/assessments` with a payload
### Request payload
```javascript
{
"TestId": "12345",
"CallbackUrl": "https://api.talentlyft.com/v2/assessments/dcc2b8d4 ",
"Candidate": {
"Id": 34,
"FirstName": "John",
"LastName": "Doe",
"Phone": "+385 98 18337",
"Email": "info@talentlyft.com"
},
"Job": {
"Id": 345,
"Title": "Operations Manager",
"Url": "https://careers.talentlyft.com/o/cVw",
"Location": "Zagreb, Croatia"
},
"Company": {
"Id": "96989f95-2647-45a2-b98c-23060739e1b8",
"Name": "TalentLyft",
"CareersSiteUrl": "https://careers.talentlyft.com",
"CompanyWebsite": "https://www.talentlyft.com"
},
"Requestor": {
"Id": "27d79297-070d-4bc9-acbe-58da9848f685",
"Name": "John Doe",
"Email": "info@talentlyft.com"
}
}
```
**Headers**
| Key | Type | Description |
| ------------- | -------- | --------------------------- |
| Authorization | `string` | Partner Authorization Token |
**Body Parameters**
| Key | Type | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------- |
| TestId | `string` | The identification provided in the previous step |
| CallbackUrl | `string` | The URL in which the Assessment Provider should publish the results (see below) |
| Candidate.Id | `int` | Candidate id |
| Candidate.FirstName | `string` | Candidate first name. Can be used in the invitation email. |
| Candidate.LastName | `string` | Candidate last name. Can be used in the invitation email. |
| Candidate.Phone | `string` | Candidate phone. Can be used in the invitation email. |
| Candidate.Email | `string` | Candidate email. Can be used in the invitation email. |
| Job.Id | `int` | Job id |
| Job.Title | `string` | Job title. Can be used in the invitation email. |
| Job.Url | `string` | Job url. Can be used in the invitation email. |
| Job.Location | `string` | Job location. Can be used in the invitation email. |
| Company.Id | `string` | Company id |
| Company.Name | `string` | Company name. Can be used in the invitation email. |
| Company.CareerSiteUrl | `string` | Company career site. Can be used in the invitation email. |
| Requestor.Id | `string` | Requestor Id |
| Requestor.Name | `string` | Requestor name. Can be used in the invitation email. |
| Requestor.Email | `string` | Requestor email. Can be used in the invitation email. |
### Response
The Assessment Provider should respond with a 201 status and an identifier for the created assessment.
```javascript
{
"AssessmentId": "2044922"
}
```
### **Retries**
For each sent assessment order if response status code is equal or greater then 300 event will be sent again after 10 minutes. TalentLyft will try to resend each webhook 5 times in total. If response code is >= 300 after all 5 attempts, this event will be discarded.
## Publishing the Results to TalentLyft
There are 4 statuses for an assessment. The initial status is `Pending` and then the assessment can be `Completed`, `Rejected` (candidate rejected assessment), `Declined` (vendor rejected assessment order) or `Expired`. The status depends on the actions of the candidate regarding the assessment.
When the status is `Completed`, the request should include the assessment results.
Whenever the status changes, the Assessments Provider should publish the new status to TalentLyft using `PUT` on the `Callback_url` provided in the assessment creation step. When the status is completed, the request should include the assessment results.
```javascript
{
"Status": "Completed",
"Result": {
"ResultsUrl": "https://yoururl.com/assessment/print/2044922 ",
"Score": "78",
"Grade": "excelled",
"Summary": "This candidate is an excellent prospect.",
"Duration": 5435454,
"Details": {
"Proaktivnost": {
"Dinamičnost": "97",
"Dominacija": "76"
},
"Mental Skills": {
"Problem_Solving": "82",
"Aptitude": "91"
}
},
"Attachments": [{
"FileName": "Assessment Report",
"Url": "https://yoururl.com//assessment/report.pdf ",
"ContentType": "application/pdf",
"Content": "Base64 encoded content of the attachment"
}]
}
}
```
**Body Parameters**
| Key | Type | Description |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status\* | `string` | This can take any of the values:
Completed - candidate completed assessmentRejected - candidate rejected assessmentDeclined - vendor rejected assessment orderExpired - test expired
|
| Result.ResultsUrl | `string` | A link to the fully fledged report on the Vendor's site. |
| Result.Score | `string` | An overall score, preferably a percentage. Max 250 characters. |
| Result.Grade | `string` | his is the final conclusion of the assessment. This can take any of the values:
Poor BelowAverage AverageSuperior
This is respectively mapped to TalentLyft evaluation system.
|
| Result.Summary | `string` | Description/evaluation of the assessment. Max 4000 characters. |
| Result.Duration | `int` | How long in seconds did it take the candidate to complete the assessment, if available. |
| Result.Attachments | `array` | A results report of the assessment along with a description, if available. Currently supporting: .pdf, .doc, .docx. Maximum file upload size is 20MB. |
| Result.Details | `object` | This can be used to provide a deeper analysis on the candidate's results. It's a JSON with a maximum of two levels nested objects. The structure should follow the `key: value` format. |