NAV
shell

Introduction

Welcome to the TalentNest API! Our API allows you to perform queries (both safe and destructive) without having to interface with the TalentNest website. You can obtain an API key which will provide you with access to data belonging to your client.

The API is accessible through https://subdomain.talentnest.com/api/v1, where subdomain is the subdomain of your client on the TalentNest website. All API requests must be made via SSL (HTTPS). Non-SSL requests will be ignored. As well, all requests must be authenticated to succeed (see the Authentication section).

The API accepts resources and provides responses using JSON. The format may be specified by the URI extension (ie. https://subdomain.talentnest.com/api/v1/employees.json), but is not required. If transmitting a JSON representation of a resource, the Content‐Type header must be set to application/json.

The API is RESTful. Each request has an associated HTTP verb which must be used. Certain endpoints accept resources as a part of the request.

Authentication

To authorize, use this code:

# Note the trailing colon(:) after the username (API token)
$ curl https://subdomain.talentnest.com/api/v1/employees -u TALENTNEST_API_KEY:

Alternatively, pass your API key within an Authorization header. Make sure to Base64 encode the token with the colon (:) appended.

$ curl https://subdomain.talentnest.com/api/v1/employees -H 'Authorization: Basic VEFMRU5UTkVTVF9BUElfS0VZOg=='

Make sure to replace TALENTNEST_API_KEY with your API key and subdomain with your TalentNest subdomain.

Authentication to TalentNest's API is done with your API key.

Requests are authenticated using HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

Alternatively, you can also pass your API key in an Authorization header.

Authorization: Basic <base64("TALENTNEST_API_KEY:")>

Since we only require an API key within the username portion of the basic auth, simply append a : to your TalentNest API token and then Base64 encode the resulting string.

Pagination

An example pagination response header

HTTP/1.1 200 OK
Status: 200 OK
Link: <https://subdomain.talentnest.com/api/v1/applications?page=1>; rel="first",
  <https://subdomain.talentnest.com/api/v1/applications?page=2>; rel="prev",
  <https://subdomain.talentnest.com/api/v1/applications?page=17>; rel="last",
  <https://subdomain.talentnest.com/api/v1/applications?page=4>; rel="next"
X-Page: 3
X-Per-Page: 50
X-Total: 814

API methods that return a collection of results are always paginated. Paginated results will include a Link (see RFC-5988) response header with the following information.

Link Description
next The corresponding URL is the link to the next page.
prev The corresponding URL is the link to the previous page.
last The corresponding URL is the link to the last page.

Paginated results will also include the following in the response header:

Field Description
X-Page The current page of results returned.
X-Per-Page The number of results per page. Default is 50.
X-Total The total number of results available.

Query string parameters

API methods that return a collection of results accept the following query parameters:

Parameter Description
per_page optional The requested number of results per page. Default is 50 and the allowed Maximum is 100.
page optional The specific page requested.

Endpoints

All API requests should be made to the https://subdomain.talentnest.com base domain (where subdomain is your client's subdomain on TalentNest).

In any case that an endpoint is not constructed properly, or points to an invalid resource, the result will contain an InvalidParameter or ResourceNotFound error JSON object, which may refer to a specific parameter within the endpoint URL. These parameters are of the form :parameter (ie. a name preceded by a colon), as seen in the table below.

Jobs

GET: All Jobs

curl "https://subdomain.talentnest.com/api/v1/jobs"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
  "jobs": [
    {
      "id": 22625,
      "title": "F&I Manager – Automotive",
      "job_status": "Open",
      "opens_at": "2017-09-05",
      "closes_at": null,
      "status_changed_at": "2015-12-16T14:31:30Z",
      "last_application_at": "2017-11-25T13:38:19Z",
      "created_at": "2015-12-16T14:31:18Z",
      "updated_at": "2017-09-08T13:55:24Z",
      "job_url": "https://subdomain.talentnest.com/en/posting/18502/location/22625",
      "apply_url": "https://subdomain.talentnest.com/en/posting/18502/apply/22625",
      "business_unit": {
        "id": 7366,
        "location": {
          "country": "United States",
          "address": null,
          "postal": null,
          "state": "Texas",
          "city": "Austin"
        }
      }
    },
    {
      "id": 23032,
      "title": "Financial Services",
      "job_status": "Closed",
      "opens_at": "2017-01-13",
      "closes_at": null,
      "status_changed_at": "2017-02-03T13:58:05Z",
      "last_application_at": null,
      "created_at": "2017-01-13T19:39:14Z",
      "updated_at": "2017-02-03T13:58:05Z",
      "job_url": "https://subdomain.talentnest.com/en/posting/18801/location/23032",
      "apply_url": "https://subdomain.talentnest.com/en/posting/18801/apply/23032",
      "business_unit": {
        "id": 2009,
        "location": {
          "country": "Canada",
          "address": "3300 Bloor Street West",
          "postal": "M9B 2C5",
          "state": "Ontario",
          "city": "Toronto"
        }
      }
    }
  ]
}

List all jobs.

HTTP Request

GET https://subodmain.talentnest.com/api/v1/jobs

Query string parameters

Parameter Description
per_page The requested number of results per page. Default is 50 and the allowed Maximum is 300.
page The specific page requested.
job_status Filters based on job status. Allowed values are open, paused, closed.
business_unit_id Return jobs belonging to this business unit or any of its sub-units. To exclude sub-unit jobs, add the optional parameter sub_units=false.
created_after Return only jobs that were created after this timestamp. Timestamp must be ISO 8601 format.
updated_after Return only jobs that were updated after this timestamp. Timestamp must be ISO 8601 format.

GET: Specific Job

curl "https://subdomain.talentnest.com/api/v1/jobs/{id}"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
  "job": {
    "id": 23819,
    "title": "Program Manager",
    "job_status": "Open",
    "opens_at": "2017-02-03",
    "closes_at": "2017-02-10",
    "status_changed_at": "2017-02-03T21:46:57Z",
    "last_application_at": null,
    "created_at": "2017-02-03T21:46:16Z",
    "updated_at": "2017-02-03T21:46:16Z",
    "job_url": "https://subdomain.talentnest.com/en/posting/19252/location/23819",
    "apply_url": "https://subdomain.talentnest.com/en/posting/19252/apply/23819",
    "business_unit": {
      "id": 2446,
      "location": {
        "country": "Canada",
        "address": null,
        "postal": null,
        "state": "Alberta",
        "city": "Edmonton"
      }
    },
    "description": "Detailed job description",
    "employment_type": null,
    "posting_type": "External",
    "job_applications_count": 30,
    "completed_applications_count": 25,
    "unreviewed_applications_count": 5,
    "hires_count": 0,
    "vacancies_count": 0,
    "assessment": null
  }
}

HTTP Request

GET https://subodmain.talentnest.com/api/v1/jobs/{id}

URL Parameters

Parameter Description
id The ID of the job to retrieve

GET: Job's Employment Process

curl "https://subdomain.talentnest.com/api/v1/jobs/{id}/employment_process"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
  "employment_process": {
    "steps": [
      {
        "id": 1933,
        "name": "Review Candidate",
        "abbreviation": "RC",
        "step_type": "New Application",
        "sequence": 1,
        "optional": false,
        "rated": false
      },
      {
        "id": 2041,
        "name": "Phone Interview",
        "abbreviation": "PI",
        "step_type": "Interview",
        "sequence": 2,
        "optional": true,
        "rated": true
      },
      {
        "id": 2042,
        "name": "Management Pro",
        "abbreviation": "MPP3",
        "step_type": "Assessment",
        "sequence": 3,
        "optional": true,
        "rated": false
      },
      {
        "id": 2044,
        "name": "Interview",
        "abbreviation": "Int",
        "step_type": "Interview",
        "sequence": 4,
        "optional": true,
        "rated": true
      },
      {
        "id": 1934,
        "name": "Employment Offer",
        "abbreviation": "EO",
        "step_type": "Employment Offer",
        "sequence": 5,
        "optional": false,
        "rated": false
      }
    ]
  }
}

HTTP Request

GET https://subodmain.talentnest.com/api/v1/jobs/{id}/employment_process

URL Parameters

Parameter Description
id The ID of the job to use

Applications

GET: All Job Applications

curl "https://subdomain.talentnest.com/api/v1/applications"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
  "applications": [
    {
      "id": 1765253,
      "candidate_id": 1148,
      "job_id": 25668,
      "job_title": "Parts Manager - Automotive",
      "first_name": "Jake",
      "last_name": "Joseph",
      "email": "jj@talentnest.com",
      "application_step": "Review Candidate",
      "application_status": "Deselected",
      "application_url": "https://subdomain.talentnest.com/en/job/25668/candidate/1148",
      "status_changed_at": "2017-11-29T19:41:33Z",
      "completed_at": "2017-10-28T17:47:15Z",
      "created_at": "2017-09-23T20:31:53Z",
      "updated_at": "2017-12-01T07:00:10Z"
    },
    {
      "id": 1769005,
      "candidate_id": 876140,
      "job_id": 29696,
      "job_title": "General Agent",
      "first_name": "Lori",
      "last_name": "Ham",
      "email": "lori.ham@talentnest.com",
      "application_step": "Review Candidate",
      "application_status": "Deselected",
      "application_url": "https://subdomain.talentnest.com/en/job/29696/candidate/876140",
      "status_changed_at": "2017-11-11T15:16:25Z",
      "completed_at": "2017-09-26T17:20:27Z",
      "created_at": "2017-09-26T17:20:25Z",
      "updated_at": "2017-11-11T15:16:25Z"
    }
  ]
}

Retrieves all job applications

HTTP Request

GET https://subodmain.talentnest.com/api/v1/applications/

Query string parameters

Parameter Description
per_page The requested number of results per page. Default is 50 and the allowed Maximum is 100.
page The specific page requested.
job_id Return only applications belonging to this job.
candidate_id Return only applications belonging to this candidate.
completed_after Return only applications that were completed after this timestamp. Timestamp must be ISO 8601 format.
updated_after Return only applications that were updated after this timestamp. Timestamp must be ISO 8601 format.
application_status Return only applications with this status. Allowed values are active, deselected, hired.
status_changed_after Return only applications whose status was changed after this timestamp. Timestamp must be ISO 8601 format.

GET: Specific Application

curl "https://subdomain.talentnest.com/api/v1/applications/{id}"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{ 
  "application": {
    "id": 1765253,
    "candidate_id": 1148,
    "job_id": 25668,
    "job_title": "Parts Manager - Automotive",
    "first_name": "Jake",
    "last_name": "Joseph",
    "email": "jj@talentnest.com",
    "application_step": "Management Pro",
    "application_status": "Active",
    "application_url": "https://subdomain.talentnest.com/en/job/25668/candidate/1148",
    "status_changed_at": "2017-10-28T17:47:15Z",
    "completed_at": "2017-10-28T17:47:15Z",
    "created_at": "2017-09-23T20:31:53Z",
    "updated_at": "2017-12-01T07:00:10Z",
    "phone": "4167460444",
    "deselect_reason": null,
    "source": "Company Website",
    "reviewed": true,
    "passed_prescreen": true,
    "golden_eagle": false,
    "employee": false,
    "prescreen_answers": [
      {
        "question": "Are you legally eligible to work in the United States?",
        "answer": "Yes",
        "passed": true
      },
      {
        "question": "Do you have a good driving record and a valid driver’s license?",
        "answer": "Yes",
        "passed": true
      },
      {
        "question": "Would you be able to pass a drug screen? ",
        "answer": "Yes",
        "passed": true
      }
    ],
    "demographic_answers": [
      {
        "question": "If you were referred to our company by someone, who referred you:",
        "answer": "Friend",
        "type": "single"
      },
      {
        "question": "If you were referred by an employee of our company, please list the name here:",
        "answer": "",
        "type": "text"
      },
      {
        "question": "What days of the week are you available to work?",
        "answer": [
          "Tuesday",
          "Friday"
        ],
        "type": "multi"
      },
      {
        "question": "Are you available to work weekends?",
        "answer": "Yes",
        "type": "single"
      },
      {
        "question": "What date are you available to start work?",
        "answer": "",
        "type": "text"
      },
      {
        "question": "Are you available to travel on company business?  ",
        "answer": "Yes",
        "type": "single"
      },
      {
      "question": "What is the highest level of education you have completed?",
      "answer": "Trade School",
      "type": "single"
      },
      {
      "question": "List your computer skills.",
      "answer": "",
      "type": "text"
      }
    ],
    "resume_url": "https://subdomain.talentnest.com/en/documents/79944/download?hash=95ab65073cd38427eeb69e827c4806d32f716c95",
    "cover_url": null,
    "candidate_location": {
      "country": "Canada",
      "address": "3300 Bloor Street West",
      "postal": "M8X 2X3",
      "state": "Ontario",
      "city": "Toronto"
    },
    "future_consideration": false,
    "candidate_tags": [
      "automotive",
      "technician"
    ],
    "current_step":  {
      "id": 5,
      "sequence": 2,
      "step_name": "Management Pro",
      "status": "Completed",
      "rating": null,
      "activated_at": "2017-05-27T15:57:36Z",
      "completed_at": "2017-10-21T21:10:33Z",
      "invited_at": null,
      "deselected_at": null
    },
    "employment_process_history": [
      {
        "id": 13,
        "sequence": 1,
        "step_name": "Review Candidate",
        "status": "Completed",
        "rating": "4.0",
        "activated_at": "2017-05-27T15:54:31Z",
        "completed_at": "2017-05-27T15:57:32Z",
        "invited_at": null,
        "deselected_at": null
      },
      {
        "id": 5,
        "sequence": 2,
        "step_name": "Management Pro",
        "status": "Completed",
        "rating": null,
        "activated_at": "2017-05-27T15:57:36Z",
        "completed_at": "2017-10-21T21:10:33Z",
        "invited_at": null,
        "deselected_at": null
      },
      {
        "id": 8,
        "sequence": 3,
        "step_name": "Interview",
        "status": "Inactive",
        "rating": null,
        "activated_at": null,
        "completed_at": null,
        "invited_at": null,
        "deselected_at": null
      },
      {
        "id": 7,
        "sequence": 4,
        "step_name": "Employment Offer",
        "status": "Inactive",
        "rating": null,
        "activated_at": null,
        "completed_at": null,
        "invited_at": null,
        "deselected_at": null
      }
    ],
    "assessments": [
      {
        "id": 617257,
        "name": "ContactCenterScreen 2.0",
        "url": "https://assessment-report-url...",
        "scores": [
          {
            "type": "sales",
            "score": "2.8",
            "recommendation": "caution"
          },
          {
            "type": "service",
            "score": "3.1",
            "recommendation": "proceed"
          }
        ] 
      },
      {
        "id": 660573,
        "name": "POP Screen",
        "url": "https://assessment-report-url...",
        "scores": [
          {
            "type": "overall",
            "score": "2.38",
            "recommendation": "redirect"
          }
        ] 
      }
    ]
  }
}

Retrieve a specific application by its id.

HTTP Request

GET https://subodmain.talentnest.com/api/v1/applications/{id}

URL Parameters

Parameter Description
id The ID of the application to retrieve

GET: An Application's Notes

curl "https://subdomain.talentnest.com/api/v1/applications/{id}/notes"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
    "notes": [
        {
            "id": 34118320,
            "title": "New application submitted",
            "body": "New application submitted",
            "created_at": "2023-01-31T17:41:59Z",
            "updated_at": "2023-01-31T17:41:59Z"
        },
        {
            "id": 34118408,
            "title": "Test",
            "body": "Had a great interview. ",
            "created_at": "2023-01-31T17:48:09Z",
            "updated_at": "2023-01-31T17:48:09Z"
        },
        {
            "id": 34147229,
            "title": "Review Candidate completed",
            "body": "Review Candidate completed",
            "created_at": "2023-02-02T20:19:05Z",
            "updated_at": "2023-02-02T20:19:05Z"
        },
        {
            "id": 34147230,
            "title": "Phone Interview started",
            "body": "Phone Interview started",
            "created_at": "2023-02-02T20:19:19Z",
            "updated_at": "2023-02-02T20:19:19Z"
        },
        {
            "id": 34147299,
            "title": "Phone Interview completed",
            "body": "Phone Interview completed",
            "created_at": "2023-02-02T20:19:31Z",
            "updated_at": "2023-02-02T20:19:31Z"
        },
        {
            "id": 34147300,
            "title": "Interview started",
            "body": "Interview started",
            "created_at": "2023-02-02T20:19:34Z",
            "updated_at": "2023-02-02T20:19:34Z"
        },
        {
            "id": 34147302,
            "title": "Interview completed",
            "body": "Interview completed",
            "created_at": "2023-02-02T20:19:42Z",
            "updated_at": "2023-02-02T20:19:42Z"
        },
        {
            "id": 34431535,
            "title": "Employment Offer started",
            "body": "Employment Offer started",
            "created_at": "2023-02-14T20:25:13Z",
            "updated_at": "2023-02-14T20:25:13Z"
        },
        {
            "id": 34431537,
            "title": "Employment Offer completed",
            "body": "Employment Offer completed",
            "created_at": "2023-02-14T20:25:16Z",
            "updated_at": "2023-02-14T20:25:16Z"
        },
        {
            "id": 34431538,
            "title": "This candidate has been hired",
            "body": "This candidate has been hired",
            "created_at": "2023-02-14T20:25:16Z",
            "updated_at": "2023-02-14T20:25:16Z"
        },
        {
            "id": 34431557,
            "title": "Onboarding process started",
            "body": "Onboarding process started",
            "created_at": "2023-02-14T20:25:44Z",
            "updated_at": "2023-02-14T20:25:44Z"
        }
    ]
}

Retrieve a notes for a specific application by its application id.

HTTP Request

GET https://subodmain.talentnest.com/api/v1/applications/{id}/notes

URL Parameters

Parameter Description
id The ID of the application to retrieve notes for

POST: Advance Application

curl -X POST "https://subdomain.talentnest.com/api/v1/applications/{id}/advance"
  -H 'Content-Type: application/json'
  -u "TALENTNEST_API_KEY:"

The above command takes a JSON request, structured like this:

{
  "from_step_id": 2041,
  "rating": 5,
  "note": "Great first impression!"
}

The above returns JSON, structured like this:

{
  "application": {
    "id": 3060537,
    "current_step": {
      "id": 2042,
      "sequence": 3,
      "step_name": "POP7",
      "status": "Active",
      "rating": null,
      "activated_at": "2019-01-07T17:04:26Z",
      "completed_at": null,
      "invited_at": null,
      "deselected_at": null
    }
  }
}

Advances this application from the current_step to the next step in the employment process. Only Active applications can be advanced.

The current_step will be Completed and the next step will be Activated. This newly activated step becomes the new current_step. The response contains the new current_step's information.

HTTP Request

POST https://subodmain.talentnest.com/api/v1/applications/{id}/advance

URL Parameters

Parameter Description
id The ID of the application to advance

JSON Body Parameters

Parameter Required Type Description
from_step_id Yes Integer The ID of the application's current_step.
rating No Integer Rating the candidate received at current_step. Range 1 to 5. Applies only to rated steps.
note No String Optional note to store when completing the current_step.

POST: Move Application

curl -X POST "https://subdomain.talentnest.com/api/v1/applications/{id}/move"
  -H 'Content-Type: application/json'
  -u "TALENTNEST_API_KEY:"

The above command takes a JSON request, structured like this:

{
  "from_step_id": 2041,
  "to_step_id": 2044,
  "rating": 5,
  "note": "Completing this step and jumping few steps forward!"
}

The above returns JSON, structured like this:

{
  "application": {
    "id": 3060537,
    "current_step": {
      "id": 2044,
      "sequence": 4,
      "step_name": "Interview",
      "status": "Active",
      "rating": null,
      "activated_at": "2019-03-12T17:04:26Z",
      "completed_at": null,
      "invited_at": null,
      "deselected_at": null
    }
  }
}

Moves this application to an arbitrary step ahead in the employment process. The old current_step will be Completed and the new current_step will be Activated. The response contains the new current_step's information.

Only Active applications can be moved.

The move is not allowed if there are any required steps in-between the two steps.

HTTP Request

POST https://subodmain.talentnest.com/api/v1/applications/{id}/move

URL Parameters

Parameter Description
id The ID of the application to move

JSON Body Parameters

Parameter Required Type Description
from_step_id Yes Integer The ID of the application's current_step.
to_step_id Yes Integer The ID of the step the application should be moved to.
rating No Integer Rating the candidate received at current_step. Range 1 to 5. Applies only to rated steps.
note No String Optional note to store when completing the current_step.

POST: Deselect Application

curl -X POST "https://subdomain.talentnest.com/api/v1/applications/{id}/deselect"
  -H 'Content-Type: application/json'
  -u "TALENTNEST_API_KEY:"

The above command takes a JSON request, structured like this:

{
  "send_deselect_email": true,
  "deselect_reason_id": 1001,
  "note": "Reasons for deselection"
}

The above returns JSON, structured like this:

{
  "application": {
    "id": 3060537,
    "application_status": "Deselected"
  }
}

Deselects the application at the current step. Only Active applications can be deselected.

The current_step will be Deselected and the application will also be marked as Deselected. If optional parameters are provided, TalentNest can process a deselection reason and custom note.

HTTP Request

POST https://subodmain.talentnest.com/api/v1/applications/{id}/deselect

URL Parameters

Parameter Description
id The ID of the application to advance

JSON Body Parameters

Parameter Required Type Description
send_deselect_email No Boolean True or False to send a system deselection email to the candidate. Default: False
deselect_reaason_id No Integer Optional reason ID for why the candidate was deselected.
note No String Optional note to store why the candidate was deselected.

GET: Specific Step for Application

curl "https://subdomain.talentnest.com/api/v1/applications/{id}/step/{step_id}"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
  "step": {
    "id": 2042,
    "application_id": 3060537,
    "sequence": 3,
    "step_name": "POP7",
    "status": "Active",
    "rating": null,
    "activated_at": "2022-01-07T17:04:26Z",
    "completed_at": null,
    "invited_at": null,
    "deselected_at": null
  }
}

Retrieve a specific step of an application.

HTTP Request

GET https://subodmain.talentnest.com/api/v1/applications/{id}/step/{step_id}

URL Parameters

Parameter Description
id The ID of the application
step_id The ID of the step to retrieve

PUT: Activate Step for Application

curl -X PUT "https://subdomain.talentnest.com/api/v1/applications/{id}/step/{step_id}/activate"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
  "step": {
    "id": 2042,
    "application_id": 3060537,
    "sequence": 3,
    "step_name": "Phone Interview",
    "status": "Active",
    "rating": null,
    "activated_at": "2019-01-07T17:04:26Z",
    "completed_at": null,
    "invited_at": null,
    "deselected_at": null
  }
}

Activate a specific step of an application.

HTTP Request

PUT https://subodmain.talentnest.com/api/v1/applications/{id}/step/{step_id}/activate

URL Parameters

Parameter Description
id The ID of the application
step_id The ID of the step to activate

PUT: Complete Step for Application

curl -X PUT "https://subdomain.talentnest.com/api/v1/applications/{id}/step/{step_id}/complete"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
  "step": {
    "id": 2042,
    "application_id": 3060537,
    "sequence": 3,
    "step_name": "Phone Interview",
    "status": "Completed",
    "rating": null,
    "activated_at": "2019-01-07T17:04:26Z",
    "completed_at": "2019-01-08T13:07:36Z",
    "invited_at": null,
    "deselected_at": null
  }
}

Complete a specific step of an application.

HTTP Request

PUT https://subodmain.talentnest.com/api/v1/applications/{id}/step/{step_id}/complete

URL Parameters

Parameter Description
id The ID of the application
step_id The ID of the step to complete

Business Units

Business Units form the hierarchy of your company within TalentNest.

Attribute Description
parent_id The ID that this business unit belongs to.
major_unit_id if available If major divisions are setup, the ID of the major division that this business unit belongs to.

GET: All Business Units

curl "https://subdomain.talentnest.com/api/v1/business_units"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
  "business_units": [
    {
      "id": 2,
      "name": "XYZ Corp",
      "description": "XYZ Corp is a world leader in widgets.",
      "parent_id": null,
      "major_unit_id": null,
      "location": {
        "country": "Canada",
        "address": "3300 Bloor Street West",
        "postal": "M8X 2X3",
        "state": "Ontario",
        "city": "Toronto"
      }
    },
    {
      "id": 4,
      "name": "Finance",
      "description": null,
      "parent_id": 2,
      "major_unit_id": null,
      "location": {
        "country": "Canada",
        "address": "3300 Bloor Street West",
        "postal": "M8X 2X3",
        "state": "Ontario",
        "city": "Toronto"
      }
    },
    {
      "id": 5,
      "name": "Accounting",
      "description": null,
      "parent_id": 4,
      "major_unit_id": 4,
      "location": {
        "country": "Canada",
        "address": null,
        "postal": null,
        "state": null,
        "city": null
      }
    }
  ]
}

HTTP Request

GET https://subodmain.talentnest.com/api/v1/business_units/

GET: Specific Business Unit

{ 
  "business_unit": {
    "id": 2,
    "name": "XYZ Corp",
    "description": "XYZ Corp is a world leader in widgets.",
    "parent_id": null,
    "major_unit_id": null,
    "location": {
      "country": "Canada",
      "address": "3300 Bloor Street West",
      "postal": "M8X 2X3",
      "state": "Ontario",
      "city": "Toronto"
    }
  }
}

HTTP Request

GET https://subodmain.talentnest.com/api/v1/business_units/{id}

URL Parameters

Parameter Description
id The ID of the business unit to retrieve

Candidates

GET: All Candidates

curl "https://subdomain.talentnest.com/api/v1/candidates"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{ 
  "candidates": [
    {
      "id": 11,
      "first_name": "Sakul",
      "middle_initial": "N",
      "last_name": "Noteab",
      "email": "snn@talentnest.com",
      "primary_phone": "4161234444",
      "created_at": "2010-05-11T20:08:44Z",
      "updated_at": "2021-04-29T20:31:30Z"
    },
    {
      "id": 12,
      "first_name": "Duncan",
      "middle_initial": null,
      "last_name": "Reith",
      "email": "dunr@talentnest.com",
      "primary_phone": "14164444444",
      "created_at": "2010-05-26T19:39:48Z",
      "updated_at": "2014-06-25T18:27:08Z"
    }
  ]
}

Retrieves all candidates

HTTP Request

GET https://subodmain.talentnest.com/api/v1/candidates/

Query string parameters

Parameter Description
per_page The requested number of results per page. Default is 50 and the allowed Maximum is 100.
page The specific page requested.
created_after Return only candidates whose record was created after this timestamp. Timestamp must be ISO 8601 format.
updated_after Return only candidates that were updated after this timestamp. Timestamp must be ISO 8601 format.

GET: Specific Candidate

curl "https://subdomain.talentnest.com/api/v1/candidates/{id}"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{ 
  "candidate": {
    "id": 12,
    "first_name": "Duncan",
    "middle_initial": null,
    "last_name": "Reith",
    "email": "dunr@talentnest.com",
    "primary_phone": "14164444444",
    "created_at": "2010-05-26T19:39:48Z",
    "updated_at": "2014-06-25T18:27:08Z",
    "location": {
      "country": "Canada",
      "address": "155 Rexdale Boulevard",
      "postal": "M9W 5Z8",
      "state": "Ontario",
      "city": "Toronto"
    },
    "resume_url": "https://subdomain.talentnest.com/resume...",
    "num_of_applications": 3
  }
}

Retrieve a specific candidate by its id.

HTTP Request

GET https://subodmain.talentnest.com/api/v1/candidates/{id}

URL Parameters

Parameter Description
id The ID of the candidate to retrieve

POST: Email Candidate

curl -X POST "https://subdomain.talentnest.com/api/v1/candidates/{id}/email"
  -H 'Content-Type: application/json'
  -u "TALENTNEST_API_KEY:"

The above command takes a JSON request, structured like this:

{
  "subject": "Test subject",
  "body":"Test body <br> <a href='https://talentnest.com'>https://talentnest.com</a>"
}

The above command returns JSON structured like this:

{
   "from":"notifications@talentnest.com",
   "to":"<candidate-email>",
   "subject":"<sanitized-subject>",
   "body":"<sanitized-body>"
}

Sends an email using the client's brand directly to a specific candidate specified id.

HTTP Request

POST https://subodmain.talentnest.com/api/v1/candidates/{id}/email

URL Parameters

Parameter Description
id The ID of the candidate to email

JSON Body Parameters

Parameter Required Type Description
subject Yes Text Subject line for email.
body Yes Text Body of email. Some HTML is allowed, no javascript.
dry_run No Boolean Set to True to simulate sending an email. An email will not be sent in this case. Default: False

Employees

GET: All Employees

curl "https://subdomain.talentnest.com/api/v1/employees"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

 {
   "employees": [
     {
       "id": 122345,
       "employee_number": null,
       "business_unit_id": 56,
       "manager_id": null,
       "hired_on": "2020-05-14",
       "started_on": "2020-05-14",
       "verified_on": "2020-08-07",
       "termination_date": "2020-07-17",
       "user": {
         "first_name": "Nadia",
         "middle_initial": "J",
         "last_name": "Smith",
         "email": "nadiasmith@talentnest.com",
         "primary_phone": "14167460444",
         "location": {
           "country": "Canada",
           "address": " 3300 Bloor Street West",
           "postal": "M8X 2X2",
           "state": "Ontario",
           "city": "Toronto"
         }
       },
       "current_position": null
     },
     {
       "id": 122354,
       "employee_number": null,
       "business_unit_id": 871,
       "manager_id": null,
       "hired_on": "2020-07-08",
       "started_on": "2020-07-08",
       "verified_on": "2020-08-07",
       "termination_date": "2020-07-16",
       "user": {
         "first_name": "Vanessa",
         "middle_initial": null,
         "last_name": "Squid",
         "email": "vsquid@talentnest.com",
         "primary_phone": "14167460444",
         "location": {
           "country": "Canada",
           "address": " 3300 Bloor Street West",
           "postal": "M8X 2X2",
           "state": "Ontario",
           "city": "Toronto"
         }
       },
       "current_position": null
     },
     {
       "id": 125458,
       "employee_number": null,
       "business_unit_id": 128,
       "manager_id": null,
       "hired_on": "2020-08-06",
       "started_on": "2020-08-06",
       "verified_on": "2020-08-06",
       "termination_date": null,
       "user": {
         "first_name": "Jake",
         "middle_initial": null,
         "last_name": "Williams",
         "email": "jake.williams@talentnest.com",
         "primary_phone": "14167460444",
         "location": null
       },
       "current_position": {
         "id": 115427,
         "status_id": 388,
         "job_title": "Full-Time Customer Support",
         "started_on": "2020-08-06",
         "ended_on": null,
         "position_end_reason_id": null,
         "business_unit_id": 10228,
         "application_id": 5179944
       },
       "other_position": {
         "id": 102427,
         "status_id": 312,
         "job_title": "Full-Time Front Desk",
         "started_on": "2020-01-31",
         "ended_on": "2020-08-06",
         "position_end_reason_id": 41,
         "business_unit_id": 10228,
         "application_id": 5079944
       }
     }
   ]
}

Retrieves all employees

HTTP Request

GET https://subodmain.talentnest.com/api/v1/employees

Query string parameters

Parameter Description
per_page The requested number of results per page. Default is 50 and the allowed Maximum is 100.
page The specific page requested.
business_unit_id Return employees belonging to this business unit or any of its sub-units. To exclude sub-unit employees, add the optional parameter sub_units=false.
hired_after Return only employees that have a hired date after this timestamp. Timestamp must be ISO 8601 format.

GET: A specific Employee

curl "https://subdomain.talentnest.com/api/v1/employees/{id}"
  -u "TALENTNEST_API_KEY:"


curl "https://subdomain.talentnest.com/api/v1/employees/{email}"
  -u "TALENTNEST_API_KEY:"

The above command returns JSON structured like this:

{
  "employee": {
    "id": 113246,
    "employee_number": null,
    "business_unit_id": 119,
    "manager_id": null,
    "hired_on": "2020-07-08",
    "started_on": "2020-07-08",
    "verified_on": "2020-07-08",
    "termination_date": "2020-07-24",
    "user": {
      "first_name": "Dan",
      "middle_initial": null,
      "last_name": "Cooper",
      "email": "dcooper@talentnest.com",
      "primary_phone": "14167460444",
      "location": {
          "country": "Canada",
          "address": " 3300 Bloor Street West",
          "postal": "M8X 2X2",
          "state": "Ontario",
          "city": "Toronto"
        }
    },
    "current_position": null,
    "other_positions": [
      {
        "id": 123455,
        "status_id": 500,
        "job_title": "Associate",
        "started_on": "2020-07-08",
        "ended_on": "2020-07-24",
        "position_end_reason_id": 23,
        "business_unit_id": 119,
        "application_id": 5032461
      }
    ]
  }
}

Retrieve a specific employee by id or email.

HTTP Request

GET https://subodmain.talentnest.com/api/v1/employees/{id}

GET https://subodmain.talentnest.com/api/v1/employees/{email}

URL Parameters

Parameter Description
id The ID of the employee to retrieve
email The email address of the employee to retrieve

GET: Employee Statuses

curl "https://subdomain.talentnest.com/api/v1/employees/statuses"
  -u "TALENTNEST_API_KEY:"

The above returns JSON, structured like this:

{
  "statuses": [
    {
      "id": 123,
      "status": "Active",
      "description": "Employment status for current employees."
    },
    {
      "id": 145,
      "status": "On Leave",
      "description": "Empoyment status for employees on leave"
    },
    {
      "id": 157,
      "status": "Terminated",
      "description": null
    },
    {
      "id": 176,
      "status": "Part-Time",
      "description": null
    },
    {
      "id": 135,
      "status": "Contract",
      "description": null
    }
  ]
}

Employee Statuses are client-defined phrases used to identify an employee's current status (e.g. Active or On Leave). Employee Statuses may contain translations.

HTTP Request

GET https://subodmain.talentnest.com/api/v1/employees/statuses

GET: Employees for a Specific Status

curl "https://subdomain.talentnest.com/api/v1/employees/statuses/{id}"
  -u "TALENTNEST_API_KEY:"

The above returns JSON, structured like this:

{
  "statuses": [
    {
      "id": 123,
      "status": "Active",
      "description": "Employment status for current employees.",
      "employee_ids": [
          1234,
          4567,
          5482,
          7614,
          7751,
          7757,
          8015
      ]
    }
  ]
}

Returns details for a specific employee status and a list of employee IDs that have this status.

HTTP Request

POST https://subodmain.talentnest.com/api/v1/employees/statuses/{id}

URL Parameters

Parameter Description
id The ID of the employee status to return

GET: Position End (Termination) Reasons

curl "https://subdomain.talentnest.com/api/v1/position_end_reasons"
  -u "TALENTNEST_API_KEY:"

The above returns JSON, structured like this:

{
  "position_end_reasons": [
    {
      "id": 55,
      "reason": "Voluntary Termination",
      "description": "Voluntary Termination"
    },
    {
      "id": 56,
      "reason": "Performance",
      "description": "Involuntary Termination"
    },
    {
      "id": 58,
      "reason": "Job Abandonment",
      "description": "Involuntary Termination"
    },
    {
      "id": 66,
      "reason": "Other Employment",
      "description": "Voluntary Termination"
    },
    {
      "id": 76,
      "reason": "Did Not Like Role",
      "description": "Voluntary Termination"
    },
    {
      "id": 88,
      "reason": "Medical - Personal or Family",
      "description": "Voluntary Termination"
    }
  ]
}

Returns a list of position end (termination) reasons and their associated IDs. If ther are translations, those will be returned as well.

HTTP Request

POST https://subodmain.talentnest.com/api/v1/position_end_reasons

POST: Terminate an Employee

curl -X POST "https://subdomain.talentnest.com/api/v1/employees/{id}/terminate"
  -H 'Content-Type: application/json'
  -u 'TALENTNEST_API_KEY'

The above command takes a JSON request, structured like this:

{
  "position_end_reason_id": 55,
  "termination_date": "2020-08-06"
}

The above returns JSON, structured like this:

{
  "employee": {
    "id": 109125,
    "employee_number": null,
    "business_unit_id": 257,
    "manager_id": null,
    "hired_on": "2020-03-23",
    "started_on": "2020-03-23",
    "verified_on": "2020-03-23",
    "termination_date": "2020-08-06",
    "user": {
      "first_name": "Sam",
      "middle_initial": null,
      "last_name": "Edwards",
      "email": "sedwards@talentnest.com",
      "primary_phone": "14167460444",
      "location": {
        "country": "Canada",
        "address": " 3300 Bloor Street West",
        "postal": "M8X 2X2",
        "state": "Ontario",
        "city": "Toronto"
      }
    },
    "current_position": null,
    "other_positions": [
      {
        "id": 2341231,
        "status_id": 372,
        "job_title": "Outbound Call Center Agent",
        "started_on": "2020-03-23",
        "ended_on": "2020-08-06",
        "position_end_reason_id": 55,
        "business_unit_id": 257,
        "application_id": 432425
      }
    ]
  }
}

Terminates an employee with optional position end (termination) reason and termination date.

HTTP Request

POST https://subodmain.talentnest.com/api/v1/employees/{id}/terminate

URL Parameters

Parameter Description
id The ID of the employee to terminate

JSON Body Parameters

Parameter Required Type Description
position_end_reason_id No Integer The ID of the position end (termination) reason.
termination_date No Date The date that the employee was terminated in ISO 8601 format. If a date is not provide, the current date will be used.

Interacting with the API

Five HTTP verbs are supported by the API: GET, POST, PUT, PATCH and DELETE, though not every verb is accepted by every type of resource.

Verb Description
GET Requests a representation of the specified resource; requests using GET can only retrieve data
POST Submits data to a new resource
PUT Uploads data to an existing resource, overriding the existing data
PATCH Applies a partial modification to a resource
DELETE Deletes the specified resource

Response Codes

The HTTP response code can be used to determine if the API request has succeeded. The API returns the following codes with the given circumstances:

Code Meaning
200 OK -- Request was successful
201 Created -- POST request completed sucessfully
400 Bad Request -- The request was invalid or malformed
401 Unauthorized -- Your API key is invalid
403 Forbidden -- API Authentication failed
404 Not Found -- The resource requested does not exist
405 Method Not Allowed -- The resource requested does not support the request's HTTP verb

In all cases other than 401 Unauthorized, a JSON response will accompany the status code.

For 200 OK and 201 Created, the response will contain either the data requested for a GET request, the data deleted for a DELETE request, or the current state of the resource after a POST, PUT or PATCH request.

For all other status codes, the response will contain error details, which includes the error name, error description, and more specific details as applicable.

You should not receive 500 Internal Server Errors from the API. Please contact TalentNest support if this occurs.

Webhooks

TalentNest webhooks are events that you can subscribe to. When that event occurs, TalentNest will automatically notify you with a JSON POST request to a client specified target URL.

To subscribe to an event, contact us at support@talentnest.com.

Available Webhooks

X-Event-Name: applicant_hired
Event Description
new_application Notification when a candidate applies to a job.
applicant_hired Notification when a candidate job application is hired.

The name of the event will be sent as the X-Event-Name header.

Encryption

X-Event-Signature: sha256 417a453d456ff29aabcdd5b68afdfbf8b2d160b8dd4818fdf34dc4940d509703

To compute the HMAC digest in Ruby:

digest = OpenSSL::Digest.new('sha256')
signature = OpenSSL::HMAC.hexdigest(digest, secret_key, body)

To compute the HMAC digest in PHP:

<?php
  // Requires PHP >= 5.1.2 and PECL hash >= 1.1
  $signature = hash_hmac('sha256', $body, $secret_key);
?>

The reqeusts from TalentNest to your system will be signed. The secret key is assigned when the webhook subscription is created. The algorithm used for creating the signature is HMAC SHA256 on the body of the request and the signature itself is sent as the X-Event-Signature header.

The X-Event-Signature header contains: the SHA algorithm used to generate the signature, a space, and the signature. To verify the request came from TalentNest, compute the HMAC digest using your secret key and the body and compare it to the signature portion (after the space) contained in the header. If they match, you can be sure the web hook was sent from TalentNest.

New Application Webhook

{
  "application_id": 1765253,
  "job": {
    "id": 25668,
    "name": "Parts Manager - Automotive",
    "employment_type": "Full time"
  },
  "candidate": {
    "email": "jj@talentnest.com",
    "first_name": "Jake",
    "last_name": "Joseph",
    "phone": "416-123-5555",
    "language_preference": "en",
    "location": {
      "address": "3300 Bloor Street West",
      "city": "Toronto",
      "state": "Ontario",
      "postal": "M8X 2X3",
      "country": "Canada"
    }
  }
}

The New Application webhook will be sent every time a candidate successfully applies to a job in TalentNest.

Applicant Hired Webhook

{
  "employee_id": 3234124,
  "employee_number": null,
  "business_unit_id": 422342,
  "business_unit_name": "Marketing Department",
  "job_title": "Manager - Social Media",
  "hired_on": "2017-12-12",
  "manager_id": 98644,
  "first_name": "Samantha",
  "last_name": "Murphy",
  "email": "samantha.murphy@talentnest.com",
  "phone": "416-555-555",
  "location": {
    "address": "3300 Bloor St. West",
    "city": "Toronto",
    "state": "Ontario",
    "postal": "M8X 2X2",
    "country": "Canada"
  }
}

The Applicant Hired webhook will be sent every time a job candidate has been successfully hired in TalentNest.

shell