# Getting started TalentLyft Developer API Whether you’re using [TalentLyft ](https://www.talentlyft.com/en)or you’re a maker of a tool that supports the recruiting pipeline, TalentLyft’s robust API makes integrations simple. ## TalentLyft Users Use the API to customize and automate the way jobs are displayed on your external careers site. Extract information from your TalentLyft account or import candidates from external systems. It is divided into: * [Public Customer API](broken://pages/ZZWB9ZvSGOSv1G0ikC2K) - rendering jobs without API token. Good for rendering jobs. If you prefer [swagger docs you can visit this url](https://api.talentlyft.com/swagger/index.html?urls.primaryName=Public%20\(V1\)). * [Private Customer API](/customer-api-reference) - manipulation of candidates, list of users, candidate applications. A good option if you are doing a complete custom career site. If you prefer [swagger docs you can visit this url](https://api.talentlyft.com/swagger/index.html). ## TalentLyft Partners TalentLyft is end-to-end recruiting software and sits at the heart of a streamlined recruiting process. Get deeper access to the API to integrate your product, app or service directly with TalentLyft. The Partner API is a REST API created for application developers to enable seamless integration with our TalentLyft platform. [Read here more about Partner API](/partner-api-reference). # Requests ## Encryption All requests must be sent using HTTPS with TLS 1.2 or higher. Please make sure your developer tools support this version of TLS as older versions or SSL are not supported for security reasons. ## Headers All TalentLyft API calls must include the following headers to authenticate the request: | **Key** | **Value** | | ------------- | ---------------- | | Authorization | Bearer | | Content-Type | application/json | ## Body For PUT or POST requests (e.g. create, update), the request parameters must be provided as JSON in the request body. ## **Rate limits** All API calls are limited to 600 requests every 10 minutes # Responses The API returns HTTP responses on each request to indicate the success or otherwise of API requests. The codes listed below are often used, and the API may use others. ## Response codes Successful API responses will have a 2xx HTTP status code. | Success code | Description | | ------------ | ----------------------------------------------------------------------------------------- | | 200 | Ok - The request has succeeded. | | 201 | Created - The request has succeeded and a new resource has been created as a result of it | | 204 | No Content - There is no content to send for this request, but the headers may be useful | Note that 4xx and 5xx responses may be returned for any request and clients should cater for them. | Error code | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | Bad Request - Your request included invalid JSON | | 401 | Unauthorized - You have not been authenticated | | 403 | Forbidden - You have been authenticated, but you don't have a permission for the requested resource | | 404 | Not Found - The resource you requested could not be found | | 409 | Conflict | | 422 | Unprocessable Entity - used for validation errors | | 429 | Too many requests | | 500 | Server errors - something went wrong with TalentLyft's servers. | | 502 | Server errors - something went wrong with TalentLyft's servers. | | 503 | These responses are most likely momentary operational errors (e.g. temporary unavailability), and, as a result, requests should be retried once. | | 504 | These responses are most likely momentary operational errors (e.g. temporary unavailability), and, as a result, requests should be retried once. | ## Validation Methods that take input will validate all parameters. Any parameter that fails validation will trigger an error response with status HTTP 422. The response body will be a JSON object that includes a message as well as a list of fields that failed validation. ```javascript { "Message": "Validation Failed", "Errors": [ { "Message": "This is a model-wide error" }, { "Field": "Url", "Message": "'Url' should not be empty." } ] } ``` Pagination Some list resources in the API are paginated by default to allow clients to traverse data over multiple requests. Their responses may contain a `Pages`object that contains pagination links a client can use to traverse the data without having to construct a query. The [link relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml) for the`Pages`field are as follows | Parameter | Description | | --------- | -------------------------------------------------------------------------------------------------------------- | | Next | A link to the next page of results. A response that does not contain link does not have further data to fetch. | | Prev | A link to the previous page of results. | | First | A link to the first page of results. | | Last | A link to the last page of results. | ## Pagination Pagination page out of bounds: return 200 status code - with empty array as data. In addition, you should provide hyperlinks to point clients to "correct" pages, for example the first page or the last "valid" page. ```javascript { "Pages": { "First": "href": "http://example.org/api/user", "Prev": "href": "http://example.org/api/user?page=2", "Next": "href": "http://example.org/api/user?page=4", "Last": "href": "http://example.org/api/user?page=133" }, "PerPage": 50, "Page": 1, "Count": 100, "Results": [ { "Param1": "test1", "Param2": "test2", }, { "Param1": "test1", "Param2": "test2", } ] } ``` # Authorization You'll need an Access Token if you want to use the API to access your own TalentLyft data – for example, if you use the API with your own scripts to get data from your TalentLyft account. #### How to get your Access Token Creating your Access Token is simple and you can get a Token with all scopes instantly (see below for more on scopes). To create your Access Token, visit the integration menu of the TalentLyft app. [Here is step by step guide](https://help.talentlyft.com/en/articles/21966-talentlyft-customer-api-documentation). #### Using Access Tokens To use your Access Token simply provide it as part of the `Authorization` header when you make a request. TalentLyft API uses Bearer token for auhorization. This means you need to include the token in format `Bearer `. For more info on the bearer token framework please see the [official spec](https://tools.ietf.org/html/rfc6750). # Customer API reference # Candidates {% openapi src="" path="/v2/candidates" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/candidates" method="post" expanded="true" %} {% endopenapi %} This endpoint allows for the creation of candidate profiles directly within TalentLyft, either associated with a specific job or without being linked to any job. This functionality can be particularly useful in several scenarios: **Using Your Custom Application Form:** If your website hosts a custom job application form that you prefer to continue using, you can enable candidates to apply through your form. Subsequently, you can utilize this API to seamlessly import the candidate details into your TalentLyft account. **Migrating Existing Candidates:** For those who already have a candidate database, whether in a spreadsheet or another system, this API provides an efficient method to transfer all those candidate profiles into TalentLyft. **Integrating with Other Systems:** This API facilitates the integration of TalentLyft with any other system that maintains people profiles, allowing for a smooth transfer of these profiles into TalentLyft. By leveraging this API, you can ensure a streamlined process of managing and creating candidate profiles, enhancing your recruitment workflow. ### **Request Body** | Name | Type | Description | | ---------------------- | ------- | ------------------------------------------------------------------------------------------ | | FirstName | string | The candidate’s first name | | LastName | string | The candidate’s last name | | JobId | integer | Job id | | StageId | integer | Stage id, if not provided applied | | Applied | boolean | Candidates are considered as applied and receiving the "thank you for applying" email. | | IsProspect | boolean | Candidates are considered as sourced and not receiving the "thank you for applying" email. | | Disqualified | boolean | If `true`, it will mark the candidate as diqualified | | DisqualifiedAt | string | If you leave this field empty, we will use the current timestamp | | DisqualificationReason | integer | The candidate’s disqualification reason id | | Created | string | ISO 8601 | | CoverLetter | string | The candidate’s cover letter | | Summary | string | The candidate’s summary | | Title | string | The candidate’s job title | | Company | string | The candidate’s company | | Location | object | Explained below | | Avatar | object | Explained below | | Tags | array | Array of tags as strings | | Skills | array | Array of skills as strings | | Resume | object | Candidate’s resume. Explained below. | | Attachments | array | Explained below | | Emails | array | Array of emails. Explained below | | PhoneNumbers | array | Array of phone numbers. Explained below | | SocialNetworks | array | Array of website/social network addresses. Explained below | | Answers | array | Explained below | | Projects | array | Explained below | | Experiences | array | Explained below | | Educations | array | Explained below | | Languages | array | Explained below | | Source | object | Explained below | | Compliance | object | Explained below | ### Candidate's avatar Candidate’s avatar is a object. | Parameter | Required | Type | Description | | ----------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | FileName | no | `string` | Name of the image file with extension (resume.pdf, cv.docx) | | Content | yes\* | `string` | Base64 encoded content of the attachment (if you are providing content, you do not need to provide url). String must be UTF-8 encoded. | | Url | yes\* | `string` | Url of the image (if you are providing the url, you do not need to provide the content). | | ContentType | no | `string` | MIME type, one of the following types: `image/jpeg`, `image/png` | ### Candidate's resume Candidate’s resume is a object. | Parameter | Required | Type | Description | | ----------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FileName | yes | `string` | Name of the file with extension (resume.pdf, cv.docx) | | Content | yes\* | `string` | Base64 encoded content of the attachment (if you are providing content, you do not need to provide url). String must be UTF-8 encoded. | | Url | yes\* | `string` | Url of the resume (if you are providing the url, you do not need to provide the content). | | ContentType | no | `string` | MIME type, one of the following types: `text/html`, `text/plain`, `application/pdf`, `application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document` | ### Candidate's attachments Candidate’s attachment is a list of entries. Each entry containing the following fields: | Parameter | Required | Type | Description | | ----------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FileName | yes | `string` | Name of the file with extension (resume.pdf, cv.docx) | | Content | yes\* | `string` | Base64 encoded content of the attachment (if you are providing content, you do not need to provide url). String must be UTF-8 encoded. | | Url | yes\* | `string` | Url of the attachment (if you are providing the url, you do not need to provide the content). | | ContentType | no | `string` | MIME type, one of the following types: `text/html`, `text/plain`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/pdf`, `application/zip`, `application/x-7z-compressed` | ### Candidate's location Candidate’s location is a object. | Parameter | Required | Type | Description | | ----------- | -------- | -------- | -------------------------------------------------------------- | | CountryCode | yes | `string` | [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | | City | yes\* | `string` | City | | ZipCode | yes\* | `string` | Zip code | | Address | no | `string` | Full address | ### Candidate's emails Candidate’s email is a list of entries. Each entry containing the following fields: | Parameter | Required | Type | Description | | --------- | -------- | -------- | ---------------------------------------------------------------------- | | Value | yes | `string` | The candidate's email | | Type | no | `string` | One of the following types: `email`, `email_personal` or `email_work`. | ### Candidate's phones Candidate’s phone is a list of entries. Each entry containing the following fields: | Parameter | Required | Type | Description | | --------- | -------- | -------- | ---------------------------------------------------------------------------------- | | Value | yes | `string` | Name of the file with extension (resume.pdf, cv.docx) | | Type | no | `string` | One of the following types: `phone`, `phone_mobile`, `phone_home` and `phone_work` | ### Candidate's social networks Candidate’s social networks is a list of entries. Each entry containing the following fields: | Parameter | Required | Type | Description | | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Value | yes | `string` | The candidate's URL | | Type | yes\* | `string` | One of the following types: `angellist`, `aboutme`, `crunchbase`, `behance`, `bitbucket`, `dribble`, `facebook`, `github`, `googleplus`, `linkedin`, `meetup`, `mixcloud`, `pinterest`, `quora`, `reddit`, `slideshare`, `soundcloud`, `stackexchange`, `stackoverflow`, `stumbleupon`, `tumblr`, `twitter`, `vimeo`, `vk`, `xing`, `youtube`, `instagram`, `klout`, `codeproject`, `other` | ### Candidate's answers Each talentlyft job can have a list of associated questions that can be retrieved from the `/jobs/:id/form` endpoint. For each question, an answer can be provided by adding the answers list in the posted data. For each question, add to the answers list the following attributes based on question’s type. **Questions types: `text`, `textarea`, `address`, `date`, `url`** | Parameter | Required | Type | Description | | --------- | -------- | -------- | -------------------------- | | Id | yes | `int` | The question key | | Body | yes | `string` | One of the following types | **Questions types: `checkbox`, `radio`, `select`, `yesNo`** | Parameter | Required | Type | Description | | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------ | | Id | yes | `int` | The question key | | Choices | yes | `array` | Choices ids, for single answer questions (radio, select, yesNo) provide only one selected choice | **Questions types: `file`** | Required | Type | Description | | | ---------------- | ----- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Id | yes | `string` | The question key | | File.FileName | yes | `string` | Name of the file with extension (resume.pdf, cv.docx) | | File.Content | yes\* | `string` | Base64 encoded content of the attachment (if you are providing content, you do not need to provide url). String must be UTF-8 encoded. | | File.Url | yes\* | `string` | Url of the answer (if you are providing the url, you do not need to provide the content). | | File.ContentType | no | `string` | MIME type, one of the following types: `text/html`, `text/plain`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/pdf`, `application/zip`, `application/x-7z-compressed` | ### Candidate's projects Candidate’s project is a list of entries. Each entry containing the following fields: | Parameter | Required | Type | Description | | ----------- | -------- | -------- | -------------------------------------------------- | | ProjectName | yes | `string` | | | ProjectUrl | no | `string` | | | Description | no | `string` | | | From | no | `date` | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | | To | no | `date` | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | ### Candidate's experiences Candidate’s experience is a list of entries. Each entry containing the following fields: | Parameter | Required | Type | Description | | ----------- | -------- | -------- | -------------------------------------------------- | | Title | yes | `string` | | | Company | yes | `string` | | | Description | no | `string` | | | From | no | `date` | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | | To | no | `date` | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | ### Candidate's education Candidate’s education is a list of entries. Each entry containing the following fields: | Parameter | Required | Type | Description | | ----------- | -------- | -------- | -------------------------------------------------- | | Institution | yes | `string` | | | Degree | yes | `string` | | | Description | no | `string` | | | From | no | `date` | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | | To | no | `date` | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | ### Candidate's languages Candidate’s language is a list of entries. Each entry containing the following fields: | Parameter | Required | Type | Description | | ------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | LanguageIso | yes | `string` | [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) alpha-2 code | | LanguageProficiency | yes | `string` | One of the following types: `elementary`, `limited_working`, `professional_working`, `full_professional` and `native` | ### Candidate's source | Parameter | Required | Type | Description | | ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | SourceType | no | `string` |

One of the following types:

  • JobBoard - job board
  • Recruiter - external recruiter
  • Referral - employee referral
  • CareersPage - organic, direct traffic, referral url, JsWidget and other
  • Sourced - sourced or manually uploaded
  • Social - social network shares or FacebookTab App
  • Campaigns - email or sms campaigns
  • Paid - paid search, paid social...
  • CandidateRediscovery - TalentLyft smart assistant
| | SourceBy | no | `string` | If `SourceType` is one of the following types: `Recruiter` or`Sourced`SourcBy must be Id of the team members. If `SourceType`is Referral SourceBy must be Employee uid | | SourceFrom | no | `string` | Job board name: Indeed, ZipRecruiter or social media: facebook, twitter. | ### Compliance | Parameter | Required | Type | Description | | ------------------------- | -------- | --------- | ----------- | | Gdpr.RetentionConsent | no | `boolean` | | | Gdpr.PrivacyPolicyConsent | no | `boolean` | | | Gdpr.ShareConsent | no | `boolean` | | #### {% openapi src="" path="/v2/candidates/{id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/tags" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/skills" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/note" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/log\_activity" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/evaluations" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/activities" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/applications/{applicationId}" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/applications/{applicationId}/education" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/applications/{applicationId}/education/{educationId}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/applications/{applicationId}/education/{educationId}" method="delete" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/applications/{applicationId}/experience" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/applications/{applicationId}/experience/{experienceId}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/applications/{applicationId}/experience/{experienceId}" method="delete" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/contacts" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/contacts" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/contacts/{contactId}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/candidates/{id}/contacts/{contactId}" method="delete" %} {% endopenapi %} # Departments {% openapi src="" path="/v2/departments" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/departments" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/departments/{id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/departments/{id}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/departments/{id}" method="delete" %} {% endopenapi %} {% openapi src="" path="/v2/departments/{id}/external" method="get" %} {% endopenapi %} # Employees {% openapi src="" path="/v2/employees" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/employees" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/employees/{id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/employees/{id}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/employees/{id}" method="delete" %} {% endopenapi %} {% openapi src="" path="/v2/employees/sync" method="post" %} {% endopenapi %} # Events {% openapi src="" path="/v2/events" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/events/{id}" method="get" %} {% endopenapi %} # Forms {% openapi src="" path="/v2/forms" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/forms/{id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/forms/{id}/candidate" method="post" %} {% endopenapi %} # Jobs {% openapi src="" path="/v2/jobs" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/jobs" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/jobs/{id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/jobs/{id}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/jobs/{id}" method="delete" %} {% endopenapi %} {% openapi src="" path="/v2/jobs/locations" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/jobs/{id}/status\_changes" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/jobs/{id}/stages" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/jobs/{id}/form" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/jobs/{id}/form" method="put" %} {% endopenapi %} # Members {% openapi src="" path="/v2/members" method="get" %} {% endopenapi %} # Pipelines {% openapi src="" path="/v2/pipelines" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/pipelines" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/pipelines/{id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/pipelines/{id}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/pipelines/{id}" method="delete" %} {% endopenapi %} # Rejection reasons {% openapi src="" path="/v2/rejection\_reasons" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/rejection\_reasons" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/rejection\_reasons/{id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/rejection\_reasons/{id}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/rejection\_reasons/{id}" method="delete" %} {% endopenapi %} # Subscriptions A Webhook subscription lets you register a URL which will have notifications posted to it. You can use webhooks to receive notifications. Webhooks are a powerful resource that you can use to automate your use cases and improve your productivity. [You can find more about them through this link if you're unfamiliar](https://requestbin.com/blog/working-with-webhooks/). Unlike the API resources, which represent static data that you can create, update and retrieve as needed, webhooks represent dynamic resources. You can configure them to automatically notify you when a candidate has taken a particular action, such as candidate move or hired. The main concepts for webhooks are **subscriptions**, **topics**, and **notifications**. ## Subscriptions A Webhook subscription lets you register a URL which will have notifications posted to it. ```javascript { "Id": "0f706a09-fc01-4030-a07e-273bfde9bb47", "ServiceType": "Web", "Url": "string", "HubSecret": "d6376ec0-acfc-4820-8eb2-350454b66075", "Created": "2019-06-07T20:39:39.495Z", "Updated": "2019-06-07T20:39:39.495Z", "Topics": ["candidate.sourced", "candidate.applied", "candidate.hired"] } ``` ## Topics A subscription will contain one or more topics. List of available topics: | **Topic Description** | **Topic label** | | ---------------------------------------------- | ------------------------------ | | Candidate sourced | candidate.sourced | | Candidate applied | candidate.applied | | Candidate hired | candidate.hired | | The candidate moved to stage | candidate.moved | | Candidate evaluated | candidate.evaluated | | Candidate disqualified | candidate.disqualified | | Candidate revert | candidate.revert | | Candidate commented | candidate.note | | Candidate external comment | candidate.externalnote | | A candidate submitted assessment result | candidate.assessment | | Candidate replied | candidate.inboundemail | | Candidate merged | candidate.merged | | Candidate task created | candidate.task | | Candidate task completed | candidate.taskcompleted | | The candidate is woken up | candidate.wokenup | | Candidate form submitted | candidate.formsubmission | | Job published | job.published | | Job updated | job.updated | | An event is created | event.created | | An event's title, time, or location is updated | event.updated | | An event is canceled or removed | event.deleted | | An event attendee status is updated | event.attendeestatus | | Blog post edited | post.updated | | Blog post published | post.published | | GDPR - candidate delete data | gdpr.delete | | GDPR - candidate edit request | gdpr.editrequest | | Job requisition status change | job.jobrequisitionstatuschange | ## Notifications The object delivered to a webhook is a notification. Notifications have payloads, which contain the API's existing JSON objects, such as candidate or job. ```javascript { "Uid": "c78d0bee-f4b2-475d-8ca1-de78675888d3", "Topic": "candidate.hired", "Created": "2019-06-07T20:39:39.495Z", "FirstSentAt": "2019-06-07T20:39:39.495Z", "DeliveryAttempts": 1, "SubscriptionId": "5ec42730-9a19-4ccc-acb0-aefdd3426215", "Payload": [ { "Type": "Candidate", "Data": {} } ] } ``` ### Payload types Payload types list | Type | Description | | ---------------------- | ----------- | | Candidate | Candidate | | CandidateApplication | Application | | CandidateEvent | Event | | CandidateNote | Note | | CandidateEvaluation | Evaluation | | CandidateAssessment | Assessment | | CandidateTask | Task | | CandidateEmail | Email | | ProfileMentioned | Profile | | ProfileActionperformer | Profile | ### Signed Notifications You can request notifications from TalentLyft are signed by adding a `HubSecret` field to the subscription. The value of the `HubSecret` is used as the key to create a hash signature of the JSON notification The digest is then sent using an `X-TL-Signature` header in the request and can be verified by the receiving webhook. The signature is the hexadecimal (40-byte) representation of a SHA-1 signature computed using the HMAC algorithm as defined in [RFC2104](https://tools.ietf.org/html/rfc2104). The `X-TL-Signature` header value starts with the string `sha1=` followed by the signature - for example, `X-TL-Signature: sha1=21ff2e149e0fdcac6f947740f6177f6434bda921`. ## Retries Webhook events are sent as json encoded POST request to URL you have specified in your development settings. For each sent webhook 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. If number of failed attempts reaches failure limit (50 failures), webhook will be suspended and no further deliveries will be made. Suspended webhooks can't be activated. ## Network restrictions If you are setting any network restrictions, please let us know so we can send you the list of Ip addresses that you need to allow traffic from for the integration to work. ## Duplicated message Because of possible network or other failures, there can be a duplicated messages that are sent to your webhook endpoint. To process this correctly on your side each event has Id property that will be same for each webhook retry. You can use this identificator to ignore already sent messages. {% openapi src="" path="/v2/subscriptions" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/subscriptions" method="post" %} {% endopenapi %} {% openapi src="" path="/v2/subscriptions/{id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/subscriptions/{id}" method="put" %} {% endopenapi %} {% openapi src="" path="/v2/subscriptions/{id}" method="delete" %} {% endopenapi %} # Articles {% openapi src="" path="/v2/articles" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/articles/{id}" method="get" %} {% endopenapi %} # Public API reference # Jobs {% openapi src="" path="/v2/public/{subdomain}/jobs" method="get" %} {% endopenapi %} # Departments {% openapi src="" path="/v2/public/{subdomain}/departments" method="get" %} {% endopenapi %} # Locations {% openapi src="" path="/v2/public/{subdomain}/locations" method="get" %} {% endopenapi %} # Partner API reference TalentLyft is end-to-end recruiting software and sits at the heart of a streamlined recruiting process. Get deeper access to the API to integrate your product, app or service directly with TalentLyft. The Partner API is a REST API created for application developers to enable seamless integration with our TalentLyft platform. It is divided into several components: * [Sourcing & Employee referrals](https://developers.talentlyft.com/partners-api/sourcing) - exposes the full candidate application, allows new applications to be submitted, and exposes the status of previously submitted applications. * [Job Boards](https://developers.talentlyft.com/partners-api/job-boards) - allows job board vendors to integrate with TalentLyft. The following sections describe how to connect and interact with the API. * [Assessments](https://developers.talentlyft.com/partners-api/assessments) - allows partners to provide instant assessments embedded right in the candidate application process * [Video Interviews](https://developers.talentlyft.com/partners-api/video-interviews) - help users create and manage video interviews with candidates, straight from the interview stages in TalentLyft. * [Background checks](https://developers.talentlyft.com/partners-api/background-checks) - enable customers to request and perform background checks via your platform, without ever leaving TalentLyft. * [HRIS & Onboarding](https://developers.talentlyft.com/partners-api/hris-and-onboarding) - speed up the onboarding process for new hires by enabling customers to export candidate details directly into your platform. # Assessments Integrate your assessment tool with TalentLyft 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 ![How it works](https://447108485-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LfvHvAhtSYjBbLMCwkV%2F-LhVT6rNsmThBqE7R-WM%2F-LhVcmloXLtaxKdBwxwW%2F2019-06-16_1613.png?alt=media\&token=ca0504d6-0ea7-4b59-a78b-4e700aa1baa1) ## 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:

  • BehavioralAssessment
  • SkillsTest
| | Price\* | `array` | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) → USD price is mandatory | ![Test list in TalentLyft app](https://447108485-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LfvHvAhtSYjBbLMCwkV%2F-LkJww6c_BXdpX26PnxH%2F-LkK1QxkXdfmyDvS0Nwd%2Ftest-offers.png?alt=media\&token=b2e59d74-46f7-4708-9b6d-719b9b0f0e3a) ## 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 assessment
  • Rejected - candidate rejected assessment
  • Declined - vendor rejected assessment order
  • Expired - 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
  • Average
  • Superior

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. | # HRIS & Onboarding Integrate your HRIS & Onboarding tool with TalentLyft Recruiting and onboarding are the two ends of every successful Talent Acquisition strategy. Most companies use both types of tools, and integrating them can make the HR professionals’ jobs more productive and more streamlined. Integrate your platform with TalentLyft and import hired candidates directly to your HRIS. ## **Why bother integrating HRIS and onboarding tools with recruiting tools?** Integrating HRSI and onboarding platforms with recruiting platforms make a lot of sense. Most of the companies today use both tools, and they just complement each other. After the selection process is done, candidates move to onboarding. Without HRIS and recruiting tool integration, this flow would be interrupted and much more confusing than it should be. By integrating your HRIS with TalentLyft, you will let your users import hired candidates directly from TalentLyft’s talent pools. Every piece of candidates’ profiles can be imported to HRIS, which makes onboarding much easier, especially if you have different department that do recruiting and onboarding. 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 %} # Background checks Integrate your tool for background checks with TalentLyft Background checks, similarly to assessment test, ensure hiring with more confidence and productivity. TalentLyft users perform background check every day. Integrate your background check tool with TalentLyft, and let your users perform background checks on candidates from TalentLyft talent pools. ## **Why bother integrating background check tools with recruiting tools?** Not having background check and recruiting tools integrated, makes the hiring process slower and less productive. Integrating the two tools enables HR managers to access all the candidates’ data and contact information, and perform background checks from one place. Since recruiting and background checking are two inevitable steps of every hiring strategy, it makes sense to make the process more streamlined and integrated. Letting your users perform background checks on TalentLyft’s talent pools would make the whole process less confusing and more enjoyable. 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 %} # Video Interviews Integrate your video interviewing tool with TalentLyft Interviews are the most important part of every selection process. TalentLyft users schedule interviews with the candidates on a daily basis. Integrate your video interview tool with TalentLyft and let your users schedule their video interviews with candidates from TalentLyft’s talent pools. ## **Why bother integrating video interview tools with recruiting tools?** One of the most important parts of every recruiting process are interviews. Our users schedule meetings and interviews with candidates every day. Without integration, users that have both recruiting and video interview tools, scheduling video interviews would be much more complicated. Users would have to leave one platform to go to another, and the whole process would be slower and less productive. Automation and more streamlined process are what HR people are looking for. Therefore, integrate with TalentLyft and let your users access candidates from TalentLyft’s talent pools and set up video interviews. 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 %} # Job Boards Integrate your job board with TalentLyft Whether international or regional, Job Boards help companies to publicly notify that they're hiring. Job Boards are the main key to attracting plenty of candidates for a specific Job post. More candidates interested in a job role enhances chances to find the most qualified one. ## **Why bother integrating with recruiting tool?** Benefit your sales strategy and attract more users. TalentLyft helps various companies all around the world to find their ideal employees and build their perfect team. Become a part of our candidate selection process and integrate your job board with TalentLyft! ## **How does integration work?** To provide TalentLyft users to publish a job post on your job board, you will have to integrate with TalentLyft. We made sure to make this process easier as possible for you, as well as covering all formats most Job Boards prefer. You can choose one of the three options to complete the integration whether it is API, E-mail or XML. Whole process of integrating and its testing takes 10 days maximum. {% 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 %} # Sourcing & Employee referrals Integrate your sourcing tool with TalentLyft Sourcing is one of the most popular recruiting methods. With so many passive candidates out there, powerful sourcing software have become inevitable tools of every modern HR professional. ## **Why bother integrating sourcing tools with recruiting tools?** Sourcing is one of the methods for building talent pools with high-quality job candidates. However, it is the very first step of a successful Talent Acquisition strategy. As TalentLyft’s goals are to attract and build relationships with candidates, many employers today find integrating sourcing and recruiting software very useful. Integrate your sourcing tools with TalentLyft’s recruiting and recruitment marketing software and let your users continue building relationships with sourced candidates. 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 %}