Getting started

TalentLyft Developer API

Whether you’re using TalentLyft or you’re a maker of a tool that supports the recruiting pipeline, TalentLyft’s robust API makes integrations simple.

The API provides our customers and partners with a platform to integrate their services or applications they’re using, building their own apps and creating fully customizable career sites. It exposes TalentLyft functionality and allows to connect and build software enhancing it.

The API offers the best recruiting services to our customers and the Partners API provides our partners with a platform to integrate these services into our marketplace. Marketplace services include Sourcing & Employee referrals, Job Boards, Assessments, Video Interviews, Background checks, HRIS & Onboarding.

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.

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.

{
"Message": "Validation Failed",
"Errors": [
{
"Message": "This is a model-wide error"
},
{
"Field": "Url",
"Message": "'Url' should not be empty."
}
]
}

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.

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 Pagesobject that contains pagination links a client can use to traverse the data without having to construct a query. The link relations for thePagesfield 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 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.

{
"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 Types

To access the TalentLyft API, you'll need an access token. How you get this token depends on if your app is for your own usage or for the public's usage.

  • Use the given Access Token if you're using the API to access data in your own TalentLyft account.

  • Use OAuth if you're building a publicly-available app that accesses other people's TalentLyft data.

Access Tokens

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.

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 <Access Token>.

For more info on the bearer token framework please see the official spec.

Oauth

You should use OAuth if You are requesting access to other people's TalentLyft accounts/data (for example, through an integration you've built).

Never ask users for their Access Token

Asking your users for their Access Tokens rather than implementing OAuth is against our terms of service and may result in your API access being revoked.

Scopes

Note that TalentLyft uses OAuth scopes to protect its API endpoints. OAuth scopes, or permissions, let you specify exactly how your application needs to access an TalentLyft customers’s account.

You should only specify the scopes you need to satisfy your use case and no more. Scopes are the most common reason that partner apps aren't approved when it comes to reviews.

Scope

Description

jobs_candidates.read

View jobs and candidates

events.read

View events

candidates.write

Create and update candidates

jobs.write

Create and update jobs

departments.read_write

Create and update departments

employees.read_write

Create and update employees

members.read_write

Create and update account users

webhooks.read_write

Webhooks & notificiations