Welcome to the Talentsoft Recruiting APIs!

These APIs represent, through several endpoints, the several actions that a candidate (or an employee) can perform through a Talentsoft Recruiting Front Office portal.

APIs specifications by topic:

Availability

In order to access the APIs, you should target a Front Office site through its URL along with:
```
http://[front-office-url]/api/v{number}/{endpoint}
```
In the previous example, {number} corresponds to the version of the API and {endpoint} to the action you are calling.
The API will respect the targeted Front Office configuration to generate a response (unless indicated otherwise).
If the targeted Front Office site is secured (it uses HTTPS protocol), you should use https:// when calling any API endpoint.

Language

The official language of the APIs is English: all the objects returned by the API (or sent back to it) contain properties named only in English.
The content of the response will correspond to the language provided in the Accept-Language request header.
The APIs will fallback to the targeted Front Office default language if the Accept-Language request header is missing. The same will happen if the header makes reference to a language that is not available in the targeted Front Office.

Authorization

In order to interact with the APIs, the application will need to be identified through a client_id and a client_secret.
You can generate many client_ids and client_secrets for a particular Front Office through the Talentsoft Recruiting Back Office page.
If you are developing a website, don't forget to add your URL into the whitelist section in the Talentsoft Recruiting Back Office page.
All your calls to the APIs should send a Token (to identify your application).
To get a Token, visit the Authentication section.

Response and Request formats

These APIs work only with JSON as their transport format.
All JSON properties are named in camel case starting by lower case (e.g. customFields).
Dates follow the ISO 8601 standard.

Multilocation Management

This new functionality is available only on FOs with Apis. Thanks to it, customers can build their own career website based on multi-location feature, set multiple locations for one offer and then publish it instead of duplicating it per location each time. Once the multilocation feature is activated, a new field "locations" is available, allowing recruiters to select multiple locations for their offers. This field uses Azure map geolocation services by default.

Implementation recommendations

The implementer must comply with Talentsoft’s general terms of use. In order to reduce the number of requests, please abide by the following recommendations:

Global:

The number of API calls must be kept to a minimum.
Errors must be corrected.

Authentication:

Request only one token for a given user session. Avoid requesting a new token between each API call and only request a new token when the current one has expired (20-minute duration).
The token request should be made by the server. If an api/token call is made from a browser, then the client_id & client_secret are shared with the end user, which is not recommended for security reasons. The token should therefore be obtained from a backchannel request.

Library (/api/v2/referential/*):

You can retrieve all libraries in a single request.
Retrieving all libraries in a single request can generate a large response (several megabytes).
The number of calls must be limited.
Library retrieval API calls must be cached to limit the number of calls made.
You must use pagination with reasonable values (do not exceed 500 items per page).
Library data does not change very often.
Saving library data using a persistence solution such as local storage helps reduce the number of API calls to the service.
You may also request several library types in one query (see here).

Retrieving offers (/api/v2/offersummaries):

offer endpoints are only designed for performing searches, and not for exports.
It is recommended to avoid making calls with a high count parameter.
Implementation of this behaviour may lead to an API key rate limit or a ban on a given IP address.
We recommend displaying a maximum of 50 offers per page.

Error codes

Error messages of type 400 (Bad Request) and 409 (Conflict) return a standardized error code. This code is embedded in the header "X-TS-ErrorCode" of the Http response.

Cinematics

Cinematic of API calls to search offers and display one:

Retrieve a token “as an application” (grant_type=credentials): POST /api/token
Search for offers: GET api/v2/offersummaries?count=X
Display one offer: GET api/v2/offers/getoffer?reference=[reference]

Cinematic of API calls to apply without account:

Make sure the option is activated on the environment.
Retrieve a token “as an application” (grant_type=credentials): POST /api/token
Create the application: POST api/v2/applicants/applicationswithoutaccount (see attached json file)

Cinematic of API calls to apply with account:

Retrieve a token “as an application” (grant_type=credentials): POST /api/token
Create an account: POST api/v2/accounts
Retrieve a token “as a user” (grant_type=password): POST /api/token using the username and password used in step 2.
Create the applicant: POST api/v2/applicants (see attached json file)
Upload the applicant files: POST api/v2/applicants/files
Create the application: POST api/v2/applicants/applications (see attached json file)

Cimentics of Apis to manage Multilocation :

Retrieve one offer : GET api/v2/offers/getoffer?reference=[reference] When the multi-location is activated, in the Api response, the Customer can see the different geolocated locations previously added in the offer.

Example : "locations": [ { "clientCode": "60169979-0b0f-4300-9e39-1132c0a161f5", "displayedAddress": "8 Rue Heyrault, 92100 Boulogne-Billancourt", "address": { "country": "France", "countryCode": "FR", "countryCodeISO3": "FRA", "countrySecondarySubdivision": "Hauts-de-Seine", "countrySubdivision": "Île-de-France", "freeformAddress": "8 Rue Heyrault, 92100 Boulogne-Billancourt", "municipality": "Boulogne-Billancourt" }, "position": { "lat": 48.83169, "lon": 2.23983 } } ]

Search for offers: GET api/v2/offersummaries?count=X The information linked to the added geolocated locations is available also as a result for this Apis.
Apply with account : POST /api/v2/applicants/multilocationsapplications , The offer reference should be in the Json In the case of multilocation , the applicant can apply multiple times on the same offer,using a different Location each time, unless an error message will be displayed DUPLICATE APPLICATION LOCATION - An application exists already for the location XXXX The chosen location by the applicant will updated in the Backoffice side on the same application file each time a new location is selected.

How to

How to retrieve a token

“As an application”:
- POST /api/token HTTP/1.1
- Host: [front-office-url]
- Cache-Control: no-cache
- Content-Type: application/x-www-form-urlencoded

client_id=[clientID]&client_secret=[clientSecret]&grant_type=client_credentials

“As a user”:
- POST /api/token HTTP/1.1
- Host: [front-office-url]
- Cache-Control: no-cache
- Content-Type: application/x-www-form-urlencoded

client_id=[clientID]&client_secret=[clientSecret]&grant_type=password&username=[username]&password=[password]

How to search offers by geolocation

Make sure the option is activated on the environment and that a Google Maps key was provided to Talentsoft.
Retrieve a token “as an application” (grant_type=credentials): POST /api/token
Search for offers: GET api/v2/offersummaries?latitude=[latitude]&longitude=[longitude]&radius=[radius]

How to set up the redirection url from jobboards

When a candidate consults an offer on a jobboard, he is redirected to Talentsoft to postulate. Thus, an url needs to be set up to catch 3 parameters (offerReference, idOrigine and LCID).

This url will make an API call to GET api/v2/offers/getoffer?reference=[offerReference] and display the offer. The idOrigine must be kept and filled in the “origin” property of the object Application.

The LCID can be used to set up the Accept-Language property of the request header.

Authorized file extensions

doc, docx, pdf, txt, rtf, odt, html, jpg

How to fast apply

The idea is to propose a single form that, when filed out and validated by the candidate, will on the fly:

Create his account
Create his candidate file
Upload his attached file (Resume and cover letter)
Create his application

Make sure the option to generate a password automatically is activated on the environment.
Retrieve a token “as an application” (grant_type=credentials): POST /api/token
Create an account: POST api/v2/accounts
Retrieve a token “as a user” (grant_type=password): POST /api/token using the username and password used in step 2.
Create the candidate: POST api/v2/applicants (see attached json file)
Upload the candidatefiles: POST api/v2/applicants/files
Create the application: POST api/v2/applicants/applications (see attached json file)

Points of attention

When retrieving organisations, the number of levels returned depend on a back office setting.

List of all supported languages

LCID	Language	Abbreviation
1029	Czech	cs
1030	Dansk	da
1031	German	de-DE
1032	Greek	el-GR
1033	Engish (United States)	en-US
1035	Finnish	fi
1036	French (France)	fr-FR
1038	Hungarian	hu
1039	Icelandic	is
1040	Italian	it-IT
1041	Japanese	ja
1043	Dutch (Netherlands)	nl-NL
1044	Norwegian	no-NO
1045	Polish	pl-PL
1046	Portuguese (Brazil)	pt-BR
1048	Romanian	ro
1049	Russian	ru
1051	Slovak	sk
1053	Swedish	sv-SE
2052	Chinese	zh-CN
2057	English(GreatBretagne)	en-GB
2067	Dutch (Belgium)	nl-BE
2070	Portuguese (Portugal)	pt-PT
3082	Spanish	es-ES
3084	French (Canada)	fr-CA

Table of Contents