Ashby API: Guide for ATS Integration and Automation

Getting Started with Ashby API

Ashby API allows businesses to automate and integrate hiring processes with Ashby's ATS platform. It enables:

• Candidate Management: Add or update candidates.
• Job Applications: Get info about all the jobs and active applications in the organization.
• Interview Management: Manage the candidate interview stage, interview schedule info, etc.

This API is designed to streamline HR operations, reduce manual data entry, and ensure data consistency across your organization’s software systems.

HTTP Basic Authentication

Before interacting with Ashby's API, you must authenticate your requests to ensure they are secure. Ashby uses HTTP Basic Auth for authentication.

You must send your API key with every request. Put your API key as the basic auth username and leave the password blank:

curl https://api.ashbyhq.com/application.list -u API_KEY: -H "Accept: application/json; version=1" --request POST --header 'Content-Type: application/json'

If your API key is missing, the API will respond with a 401 status code. When the provided key is wrong or deactivated, the API will respond with a 403 status code. All three situations will return a human-readable response specific to the situation.

API Key Endpoint Permissions

Each API key has a set of permissions that determine which endpoints it can read or write. If your API key does not have the necessary permissions to access an endpoint, the API will respond with a 403 status code and an error of missing_endpoint_permission. here is a Table of Permissions in the Ashby documentation.

‍

Deep Dive into Ashby API Endpoints

The Ashby API provides a range of endpoints that allow developers to manage various candidate data.

Here are the most commonly used endpoints, along with practical use cases.

1. POST /candidate.list

• Description: Lists all candidates in an organization. Requires the candidatesRead permission.
• cURL Request:

curl --request POST \
     --url https://api.ashbyhq.com/candidate.list \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

• Use Case: Obtain all the candidates in a company from Ashby into your system.

‍

2. POST /candidate.list

• Description: Gets all applications in the organization. Requires the candidatesRead permission.
• cURL Request:

curl --request POST \
     --url https://api.ashbyhq.com/application.list \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

• Use Case: Obtain all the active applications in an organization from Ashby into your system.

‍

3. POST /job.list

• Description: List all open, closed, and archived jobs. Requires the jobsRead permission.
• cURL Request:

curl --request POST \
     --url https://api.ashbyhq.com/job.list \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

• Use Case: Obtain information on all the jobs in an organization from Ashby into your system.

‍

4. POST /interviewStageGroup.list

• Description: List all interview group stages for an interview plan in order. Requires the interviewsRead permission.
• cURL Request:

curl --request POST \
     --url https://api.ashbyhq.com/interviewStageGroup.list \
     --header 'accept: application/json'

• Use Case: Track how long candidates spend in a specific group of stages using Ashby’s systems.

‍

‍

Pagination and Incremental Synchronization

Many of the list endpoints in Ashby's API (for example, candidate.list and job.list) implement pagination and incremental synchronization. Here we describe how to:

1. Implement the client-side logic needed to iterate through multiple pages of results, and
2. Only fetch resources that have been updated since the previous API request.

‍

Full Sync (Fetching All Records)

1. Initial Request:Send a POST request with an optional limit parameter (maximum 100):

{
  "limit": 100
}

2. Response Handling:The response will contain:

{  "success": true,  "results": [...],  "moreDataAvailable": true,  "nextCursor": "cursor_token"}

3. Subsequent Requests:If moreDataAvailable is true, send another request with the nextCursor:

{  "limit": 100,  "cursor": "cursor_token"}

4. Completion:Continue this process until moreDataAvailable is false. The final response will include a syncToken for future incremental syncs.

‍

Incremental Sync (Fetching Updated Records)

To fetch only records updated since your last sync:

1. Initial Request with syncToken:Include the syncToken from your last full sync:

{
  "syncToken": "previous_sync_token"
}

2. Handling Pagination:If moreDataAvailable is true, use the nextCursor in subsequent requests, along with the same syncToken:

{  "cursor": "next_cursor_token",  "syncToken": "previous_sync_token"}

3. Completion:Once moreDataAvailable is false, store the new syncToken provided for future incremental syncs.

Note: Sync tokens can expire. If you receive a sync_token_expired error, initiate a new full sync to obtain a fresh syncToke.

‍

Troubleshooting Guide

Error Responses

Ashby employs a unique approach where many errors return an HTTP 200 status code with a success: false flag in the response body. This design choice emphasizes application-level error handling.

Example of an error response:

{
  "success": false,
  "errors": ["requested_job_not_found"]
}

In this example, the error indicates that the specified job could not be found.

‍

Common Error Codes and Their Meanings

While Ashby does not provide an exhaustive list of error codes, some commonly encountered errors include:

• requested_job_not_found The specified job ID does not exist.
• missing_endpoint_permission The API key lacks permission to access the requested endpoint.
• sync_token_expired The provided sync token has expired; a full sync is required.
• job_posting_not_published Attempted to submit an application for an unpublished job posting.

These error codes are returned within the errors array in the response body.

Authentication Errors

Authentication-related issues are communicated through standard HTTP status codes:

• 401 Unauthorized: Occurs when the API key is missing
• 403 Forbidden: Triggered when the provided API key is invalid, deactivated, or lacks necessary permissions

These responses include human-readable messages detailing the authentication problem

‍

Get Started With with Ashby API Using Bindbee

Integrating with Ashby shouldn’t feel like a battle.But for most teams, it ends up being a major time sink—draining valuable engineering resources.

Why put your developers through the grind when Bindbee can get you live with Ashby in just minutes?

Setting up Ashby connector with Bindbee

• Sign up with Bindbee and navigate to the dashboard.
• Create a Connector:
  • Click on Create Connector from the dashboard.
  • Select HRIS as the type of integration. Enter customer details and give your connector a unique ID (e.g., Employment_Hero_Integration).
• Generate a Magic Link:
  • After setting up the connector, click Create Link to generate a magic link. This will allow the customer to authenticate the connection with Ashby.
  • Open the link and enter the necessary credentials. This step establishes the connection between Ashby and Bindbee.
• Sync the Connector:
  • Once the connection is made, the connector will begin syncing data from BambooHR. This may take a few minutes depending on the size of the data. You can track the sync status in the connector section.
• Access the Synced Data:
  • After syncing, go to the Employee section in the Bindbee dashboard and select Get Employees to retrieve employee data from BambooHR.
• Get the API Key and Connector Token:
  • Copy the API key and the x-connector-token from the Bindbee dashboard, which you will need to make authenticated API requests.

Retrieving Employee Data with Bindbee

Once the Ashby data has been synced, you can retrieve employee data on to your application via the Bindbee API.

Here’s a step-by-step process for accessing synced data from BambooHR through Bindbee’s unified API:

1. Request Setup:

Use the Bindbee API to send a request for employee data. You’ll need both your Bindbee API token and the x-connector-token.

2.Example  cURL Request:

curl --request GET \
  --url https://api.bindbee.com/hris/v1/employees \
  --header 'Authorization: Bearer YOUR_BINDBEE_API_KEY' \
  --header 'x-connector-token: YOUR_CONNECTOR_TOKEN'

This request will return a list of employee objects, including details like the employee’s first name, last name, job title, department, and contact information.

3. Sample Response:

{
  "items": [
    {
      "id": "018b18ef-c487-703c-afd9-0ca478ccd9d6",
      "first_name": "Kunal",
      "last_name": "Tyagi",
      "job_title": "Chief Technology Officer",
      "department": "Engineering",
      "work_email": "kunal@bindbee.dev"
    }
  ]
}

‍

Bulk Employee Data Retrieval

For retrieving large datasets, Bindbee simplifies the process by allowing you to fetch bulk employee data from BambooHR.

The pagination feature helps manage large responses by returning results in pages.

• Pagination Parameters:
  • Use the cursor and page_size parameters to navigate through the results. By default, Bindbee returns 50 records per page.
  • Example of a paginated request:

url = "https://api.bindbee.com/hris/v1/employees?cursor=MDE4YjE4ZWYtYzk5Yy03YTg2LTk5NDYtN2I3YzlkNTQzM2U1&page_size=50"
response = requests.get(url, headers=headers)

• Querying for Specific Employee Data:
  • You can further refine your request by filtering based on specific fields, such as manager_id, remote_id, or company_id to get employees under a particular manager or company.

‍

Say hello to Bindbee.

Book a demo with our experts today.