1 - Introduction
The purpose of this document is to describe the process of integrating assessment partners.
The concept of a campaign must exist with the partner.
A campaign is the link between one or more tests to be given to the candidate and a job or offer. (It can be a product or a package or…)
If the partner has a test library, Talentsoft will not be aware of it. The management of the tests to be administered remains on the side of the partner. And it is the partner's responsibility to make the link between his test library and the campaigns.
To invite candidates to take the test(s), the recruiter must select the corresponding campaign and then send the invitation.
When the recruiter displays the page of a candidate who has completed a test, the status of the test will be refreshed.
The status of the test may also be refreshed after a notification of a change of partner.
Finally, the test status will be refreshed once a day per batch.
When updating the test, an overall score (%) and a global report will be retrieved.
It will be possible to retrieve several other scores and reports.
The scores should allow candidates to be compared on the same campaign.
Reports can be PDF files or dynamic HTML.
Only scores will be stored by Talentsoft, reports will only be available for consultation.
2 - Authentication
Two types of authentication are possible :
- As a recruiter
- As an application.
Talentsoft will set up a different client_id and client_secret for each customer. A customer may have several client_id / client_secret pairs attached to organizational units. The same client_secret will be used as a client_secret in authentication as an application and as a shared secret key for signing the JWT token in authentication as a user.
2.1 As a recruiter (optional)
This API endpoint is optional but recommended if you want to securely identify recruiters.
This implies that Talentsoft and the partner share the same users (with the same email addresses.) You must implement a POST API endpoint that takes the following parameters (application/xwww-form-urlencoded) :
- grant_type = ‘urn:ietf:params:oauth:grant-type:jwt-bearer’
- assertion : A valid JWT token. The JWT token must contain a iss claim with the client ID provided by Talentsoft. The signature is generated with a client secret exchanged between Talentsoft and the partner (same as client_secret for authentication as an application). You can find the client_secret to be used to verify the signature of the JWT token using the client_id contained in the JWT payload. See https://jwt.io/
You must return a JSON with 3 fields :
- access_token : The access token to be used for all authenticated calls in the Authorization header.
- token_type = ‘bearer’
- expires_in : The lifetime in seconds of the access token.
Sample (with client id = ‘ts_customer’ & client secret = ‘your-256-bit-secret’) :
curl -d "grant_type=urn:ietf:params:oauth:grant-type:jwtbearer&assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ0c19jdXN0b21lciIsInN 1YiI6IlRhbGVudFNvZnRNYXJrZXRQbGFjZSIsImVtYWlsIjoidGVzdEBwYXJ0bmVyLmNvbSIsIm 5hbWUiOiJKb2huIERvZSIsImlhdCI6MTUxNjIzOTAyMiwiZXhwIjoxNjE2MjQwMDAwfQ.ryRdUku stkeG9iNijs0CCm3veo7PuA3DMbOV07-ZsVE" \
https://partner.com/api/v1/token
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoidGVzdEB0YxlbnRzb2Z0LmNvbSIsImdyYW50X3R5cGUiOiJ1cm46aWV0ZjpwYXJhbXM6b2F1dGg6Z3JhbnQtdHlwZTpqd3QtYmVhcmVyIiwibmJmIjoxNTQwODQ5Mjk1LCJleHAiOjE1NDA4NDkzNTUsImlhdCI6MTU0MDg0OTI5NSwiaXNzIjoiQXBpVGVzdFNlcnZlciIsImF1ZCI6IkFwaVRlc3RTZXJ2ZXIifQ.5gNvmpCny5JrDXpsWSghGYf_CQo7eZs6SgyTLQb9jLk",
"token_type": "bearer",
"expires_in": "3600"
}
2.2 As an application (mandatory)
This API endpoint is required for status retrieval by batch / callback (without a connected user) by the Talentsoft application. You must implement a POST API endpoint that takes the following parameters (application/xwww-form-urlencoded) :
- grant_type = ‘client_credentials’
- client_id : Client ID provided by Talentsoft
- client_secret : Client secret provided by Talentsoft
You must return a JSON with 3 fields :
- access_token : The access token to be used for all authenticated calls in the Authorization header.
- token_type = ‘bearer’
- expires_in : The lifetime in seconds of the access token.
Sample :
curl -d "grant_type=client_credentials&client_id=ts_customer&client_secret=your-256-bit-secret" \
https://partner.com/api/v1/token
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWx zb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoidGFsZW50c29mdF90Z XN0IiwiZ3JhbnRfdHlwZSI6ImNsaWVudF9jcmVkZW50aWFscyIsIm5iZiI6MTU0MDg0OTk1NSwi ZXhwIjoxNTQwODUwMDE1LCJpYXQiOjE1NDA4NDk5NTUsImlzcyI6IkFwaVRlc3RTZXJ2ZXIiL CJhdWQiOiJBcGlUZXN0U2VydmVyIn0.QIH9oDk4UDavqHqaWchQQs2J02LOcPQDHrFmnfrG 43M",
"token_type": "bearer",
"expires_in": "3600"
}
2.3 X-Current-User header
A X-Current-User HTTP header with the e-mail of the current connected user is sent for all requests.
This header may not exist if, for example, the request is sent from a batch or triggered from a callback. In these cases, no user are connected so we cannot provide this information.
3 Choice of campaign (mandatory)
To return the list of campaigns you must implement an API endpoint in GET with the following parameters in the query string :
- keyword : A keyword to filter the campaign list.
- language : The language of the campaign. The parameter must be the culture name like 'fr-FR’, 'en-GB’, ...
You must pass an access token into the Authorization header like : Authorization: Bearer <access_token> You must return a JSON like :
{
"code":"200", // HTML status code of the response
"status":"success", // Contains the text:“success”, “fail”, or “error”.
Where “fail” is for HTTP status response values from 500-599,
“error” is for statuses 400-499,
and “success” is for everything else (e.g. 1XX, 2XX and 3XX responses).
"message":null, // Only used for “fail” and “error” statuses to contain the error message.
"data":[ // The campaign list
{
"campaign_id":"1", // The campaign identifier.
"name":"Recruitment of a sales", // The campaign name. "language":"en-GB" // The campaign language. Must be the culture name like 'fr-FR’, 'en-GB’, ...
},
{
"campaign_id": "2",
"name": "Recrutement d'un ingénieur aéronautique",
"language":"fr-FR"
}
]
}
Sample :
curl https://partner.com/api/v1/assessment/campaigns -H "Authorization: Bearer c5586ad97239-421e-aa2b-43dabb2d4034"
{
"data": [
{
"campaign_id": "4",
"name": "Test 3 EN",
"language": "enGB"
},
{
"campaign_id": "1",
"name": "Campagne test FR",
"language": "frFR"
},
{
"campaign_id": "3",
"name": "Test 2 (FR)",
"language": "frFR"
},
{
"campaign_id": "2",
"name": "Test campaign EN",
"language": "enGB"
}
],
"code": 200,
"status": "success",
"message": null
}
4 Direct access link to the creation of a campaign (optional)
You can implement an API point in GET to provide a direct link to the creation of a campaign in your system. This feature is not required. The result must be a JSON like :
{
"code": "200",
"status": "success",
"message": null,
"data": "https://partner.com/campaigns/create" // Campaign creation page URL.
}
Sample :
curl https://partner.com/api/v1/assessment/campaignscreationlink -H "Authorization: Bearer c5586ad9-7239-421e-aa2b-43dabb2d4034"
{
"data": " https://partner.com/campaigns/create",
"code": 200,
"status": "success",
"message": null
}
5 Invitation (mandatory)
You must implement an API access point in POST to invite one or more candidates to complete the personality test. The assessment(s) to be given to candidates must be linked to a campaign. Talentsoft will not be aware of the test library but only of the campaign. A candidate may be invited to several campaigns. We pass the candidate's language so that the partner can send him the e-mail / test in the right language if he supports it.
It takes a JSON parameter like :
{
"campaign_id": "1", // The campaign identifier.
"callback_url": "https://customer.talentsoft.com/api/v1/assessmentcallback", // The callback URL hosted by Talentsoft to call when a candidate complete its interview. The host of the URL is dependent on the client (a different URL per client).
"invitations": [ // Array of invitations.
{
"applicant_id": "dabe28c0-7f0b-470a-8c5b-27bc59092001", // The UUID of the candidate provided by Talentsoft.
"lastname": "Doe", // The candidate lastname.
"firstname": "John", // The candidate firstname.
"phone": "+33610203040", // The candidate phone number.
"email": "john.doe@mail.com", // The candidate email.
"language": "fr-FR" // The candidate language.
},
{
"applicant_id": "4ab5204f-ca41-4de6-8e68-166d69372e89",
"lastname": "Dupond",
"firstname": "Jean",
"phone": "+33610203042",
"email": "jean.dupond@mail.com",
"language": "en-GB"
}
]
}
You must return a JSON like :
{
"code": "200",
"status": "success",
"message": null,
"data": [ // Array of invitation request status.
{
"applicant_id": "dabe28c0-7f0b-470a-8c5b-27bc59092001", // The UUID of the candidate provided by Talentsoft.
"status": "success", // The status of the invitation request for the candidate (success / error).
"error_message": null, // Only used for ‘error’ status to contain the error message.
"interview_invitation_link": "https://partner.com/interview/exgby01" // The link sent to the candidate to complete the assessment.
},
{
"applicant_id": "4ab5204f-ca41-4de6-8e68-166d69372e89",
"status": "error",
"error_message": null,
"interview_invitation_link": null
}
]
}
Sample :
curl -H "Content-Type: application/json" -d '{"campaign_id":"1","callback_url":"https://customer.talentsoft.com/api/v1/assessmentcallback","invitations":[{"applicant_id":"dabe28c0-7f0b-470a-8c5b27bc59092001","lastname":"Doe","firstname":"John","phone":"+33610203040","email":"john.doe @mail.com","language": "en-GB"},{"applicant_id":"4ab5204f-ca41-4de6-8e68166d69372e89","lastname":"Dupond","firstname":"Jean","phone":"+33610203042","email":"jean. dupond@mail.com","language": "fr-FR"}]}' \
-H "Authorization: Bearer c5586ad9-7239-421eaa2b-43dabb2d4034" \
https://partner.com/api/v1/assessment/tests
{
"data": [
{
"applicant_id": "dabe28c0-7f0b-470a-8c5b27bc59092001",
"status": "success",
"error_message": null,
"assessment_invitation_link": "https://pa rtner.com/test/dabe28c0-7f0b-470a-8c5b-27bc59092001"
},
{
"applicant_id": "4ab5204f-ca414de6-8e68166d69372e89",
"status": "success",
"error_message": null,
"assessment_invitation_link": "https://pa rtner.com/test/4ab5204f-ca41-4de6-8e68166d69372e89"
}
],
"code": 200,
"status": "success",
"message": null
}
6 Retrieving the status of the interview (mandatory)
You must implement an API endpoint in GET to retrieve the status, scores and reports of one or more candidates in a campaign. If the list of candidates is not filled in, all the statuses of the campaign assessments will be returned. It takes the following parameters in the query string :
- campaign_id : The campaign identifier.
- applicants : Array of applicants UUID. (example : applicants[]=1&applicants[]=2)
- language: The language of the recruiter. It is not mandatory. The parameter must be the culture name like 'fr-FR’, 'en-GB’, ...
You must return a JSON like :
{
"code": "200",
"status": "success",
"message": null,
"data": [ // Array of assessments status.
{
"campaign_id": "1", // The campaign identifier.
"applicant_id": "dabe28c0-7f0b-470a-8c5b-27bc59092001", // The UUID of
the candidate.
"status": "waiting", // The status of the assessment.
"assessment_invitation_link": "https://partner.com/assessment/exgby01",
// The link sent to the candidate to complete the assessment.
"recruiter_link": "https://partner.com/assessment/12/", // The
recruiter links to the assessment.
"readonly_link": "https://partner.com/assessment/12/iframe", // Links
to the assessment in read only mode. The page must be accessible into an
iFrame.
"global_score": "80", // Score in %.
"global_report": { // The main report
"name": "global", // The name of the report
"url": "https://partner.com/assessment/exgby01/globalreport", // The
URL of the report.
"report_type": "PDF", // The type of the report (HTML / PDF)
"language": "fr-FR", // The language of the report. Not required.
"comment": "x3fgyth" // A comment / access code, ... Not required.
},
"scores": [ // Score list
{
"name": "score1", // The name of the score.
"value": "75" // Score in %.
},
{
"name": "score2",
"value": "85"
}
],
"reports": [ // Report list
{
"name": "report1", // The name of the report
"url": "https://partner.com/assessment/exgby01/report1", // The URL
of the report.
"report_type": "PDF", // The type of the report (HTML / PDF)
"language": "en-GB", // The language of the report. Not required.
"comment": "x3fgyth" // A comment / access code, ... Not required.
},
{
"name": "report2",
"url": "https://partner.com/assessment/exgby01/report2",
"report_type": "PDF"
}
]
},
{
"campaign_id": "1",
"applicant_id": "4ab5204f-ca41-4de6-8e68-166d69372e89",
"status": "completed",
"assessment_invitation_link": "https://partner.com/assessment/exgby02",
"recruiter_link": "https://partner.com/assessment/13/",
"readonly_link": "https://partner.com/assessment/13/iframe",
"global_score": "25",
"global_report": {
"name": "global",
"url": "https://partner.com/assessment/exgby02/globalreport.html",
"report_type": "HTML"
},
"scores": [
{
"name": "score1",
"value": "10"
},
{
"name": "score2",
"value": "40"
}
],
"reports": [
{
"name": "report1",
"url": "https://partner.com/assessment/exgby02/report1",
"report_type": "PDF"
},
{
"name": "report2",
"url": "https://partner.com/assessment/exgby02/report2.html",
"report_type": "HTML"
}
]
}
]
}
The list of statutes is as follows:
- ‘waiting’ : The candidate has received the invitation but has not yet started the tests.
- ‘awaitingSharing’ : The candidate has already passed the tests associated with the campaign for another customer and we are waiting for him to share his results.
- ‘inProgress’ : The candidate has started to complete the test(s).
- ‘completed’ : The candidate has completed all the tests.
- ‘expired’ : The invitation has expired.
- ‘applicantDeclined’ : The candidate refused to pass the test.
- ‘cancelled’ : The recruiter cancelled the invitation.
- ‘deleted’ : The results / the candidate has been deleted.
- ‘archived’ : The results / the candidate has been archived.
The partner does not have to support all statuses, but waiting, inProgress and completed are mandatory.
Sample :
curl "https://partner.com/api/v1/assessment/tests?campaign_id=1&language=frFR&applicants[]=dabe28c0-7f0b-470a-8c5b-27bc59092001&applicants[]=4ab5204f-ca41-4de68e68-166d69372e89" \
-H "Authorization: Bearer c5586ad9-7239-421e-aa2b-43dabb2d4034"
{
"data": [
{
"campaign_id": "1",
"applicant_id": "dabe28c0-7f0b-470a-8c5b27bc59092001",
"status": "waiting",
"assessment_invitation_link": "https://partner.com/test/dabe28 c0-7f0b-470a-8c5b-27bc59092001",
"recruiter_link": "https://recruiterLink.partner.com/dabe28c07f0b-470a-8c5b-27bc59092001",
"readonly_link": "https://readonlyLink.partner.com/dabe28c07f0b-470a-8c5b27bc59092001",
"global_score": "75",
"global_report": null,
"scores": null,
"reports": []
},
{
"campaign_id": "1",
"applicant_id": "4ab5204f-ca41-4de6-8e68166d69372e89",
"status": "waiting",
"assessment_invitation_link": "https://partner.com/test/4ab520 4f-ca41-4de6-8e68-166d69372e89",
"recruiter_link": "https://recruiterLink.partner.com/4ab5204fca41-4de6-8e68-166d69372e89",
"readonly_link": "https://readonlyLink.partner.com/4ab5204fca41-4de6-8e68166d69372e89",
"global_score": "75",
"global_report": null,
"scores": null,
"reports": []
}
],
"code": 200,
"st atus": "success",
"message": null
}
7 Request to delete the candidate (GDPR) (mandatory)
You must implement an API endpoint in DELETE to delete the data of one or more candidates in accordance with the GDPR.
It takes a JSON parameter like :
{
"campaigns": [ // Array of campaign identifiers
"1",
"2"
],
"email": "john.doe@mail.com", // The candidate’s email to be deleted.
"applicant_id": "dabe28c0-7f0b-470a-8c5b-27bc59092001", // The UUID of the candidate.
}
The result must be a JSON like :
{
"code": "200",
"status": "success",
"message": null
}
Sample :
curl -X "DELETE" https://partner.com/api/v1/assessment/tests -H "Content-Type: application/json" \
-d'{"campaigns":["1"],"email":"john.doe@mail.com","applicant_id":" dabe28c07f0b-470a-8c5b-27bc59092001"}' \
-H "Authorization: Bearer c5586ad9-7239-421e-aa2b43dabb2d4034"
{
"code": 200,
"status": "success",
"message": null
}
8 Callback (optional)
API endpoint developed by Talentsoft that will be called by the partner when an update of the assessment takes place. The URL of the callback API endpoint is provided by Talentsoft when inviting candidates. This URL is different for each Talentsoft customer. You can call the API with POST with the following parameters (application/x-www-formurlencoded) :
- client_id : The client id of the partner provided by Talentsoft.
- applicant_id : The UUID of the candidate.
- campaign_id : The campaign identifier.
The call is just a notification, the API endpoint for retrieving the status of the assessment will be called by Talentsoft to update the information.