NAV Navbar
shell
  • Introduction
  • Authentication
  • Pagination
  • Endpoints
  • Jobs
  • Applications
  • Business Units
  • Interacting with the API
  • Response Codes
  • Webhooks
  • 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 "http://subdomain.talentnest.com/api/v1/jobs"
      -u "TALENTNEST_API_KEY:"
    

    The above command returns JSON structured like this:

    [
      {
        "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 100.
    page The specific page requested.
    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: A Specific Job

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

    The above command returns JSON structured like this:

    {
      "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: A Job's Employment Process

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

    The above command returns JSON structured like this:

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

    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 "http://subdomain.talentnest.com/api/v1/applications"
      -u "TALENTNEST_API_KEY:"
    

    The above command returns JSON structured like this:

    [
      {
        "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.
    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: A Specific Application

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

    The above command returns JSON structured like this:

    {
      {
        "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",
        "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"
        ],
        "employment_process_history": [
          {
            "activated_at": "2017-05-27T15:54:31Z",
            "completed_at": "2017-05-27T15:57:32Z",
            "deselected_at": null,
            "invited_at": null,
            "rating": "4.0",
            "status": "Completed",
            "step_name": "Review Candidate"
          },
          {
            "activated_at": null,
            "completed_at": null,
            "deselected_at": null,
            "invited_at": null,
            "rating": null,
            "status": "Inactive",
            "step_name": "Employment Offer"
          },
          {
            "activated_at": null,
            "completed_at": null,
            "deselected_at": null,
            "invited_at": null,
            "rating": null,
            "status": "Inactive",
            "step_name": "Interview"
          },
          {
            "activated_at": "2017-05-27T15:57:36Z",
            "completed_at": "2017-10-21T21:10:33Z",
            "deselected_at": null,
            "invited_at": null,
            "rating": null,
            "status": "Completed",
            "step_name": "Management Pro"
          }
        ],
      }
    }
    

    HTTP Request

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

    URL Parameters

    Parameter Description
    id The ID of the application to retrieve

    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 "http://subdomain.talentnest.com/api/v1/business_units"
      -u "TALENTNEST_API_KEY:"
    

    The above command returns JSON structured like this:

    [
      {
        "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: A Specific 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

    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 -- Requet 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
    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.

    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 evey time a job candidate has been successfully hired in TalentNest.