Ashby, an all-in-one applicant tracking system (ATS), helps recruiting teams of all sizes gather, organize, and analyze large quantities of job applications. In addition, the software helps recruiting teams manage the full candidate life cycle to help organizations land target candidates more easily and with greater success.

Ashby also offers APIs, which empowers developers to access any of the data stored in the platform—as well as add information to the system. 

Perhaps no object (and associated fields) is more valuable in Ashby than candidates. To help you retrieve either all candidates or individual ones, we’ll walk you through the process of using a Python script to connect to the relevant API endpoint and fetch the candidates in Ashby. 

Authentication in Ashby

You'll need to include a specific header in your requests. This header should be in the format <code class="blog_inline-code">Authorization: Basic {API-KEY}</code>. Moreover, all interactions with Ashby's API require another header field, specifically <code class="blog_inline-code">Content-Type: application/json</code>. 

How to GET candidates from Ashby‍

The script below fetches candidates from the Ashby API. It does this by first encoding the API key in Base64 format and preparing the headers for the request. Then, it hits the endpoint <code class="blog_inline-code">'https://api.ashbyhq.com/candidate.list'</code> repeatedly until there's no more data available. The next cursor is extracted from the response and included in the next request. Finally, all the candidates are printed out. 

Here’s how the script should look (in addition to the header):

import requests
import base64
import json
API_KEY = 'your_ashby_api_key'
BASE_64 = base64.b64encode(bytes(API_KEY, 'utf-8')).decode('utf-8')
headers = {
    'Authorization': 'Basic ' + BASE_64 + ':' + BASE_64,
    'Content-Type': 'application/json',
}
url = 'https://api.ashbyhq.com/candidate.list'
next_cursor = None
more_data_available = True
candidates = []
while more_data_available:
    data = {'cursor': next_cursor} if next_cursor else None
    response = requests.post(url, headers=headers, json=data)
    response_json = response.json()
    candidates.extend(response_json['results'])
    more_data_available = response_json['moreDataAvailable']
    next_cursor = response_json['nextCursor']
for candidate in candidates:
    print(candidate)
    

Note: Remember to replace 'your_ashby_api_key' with your actual API key. 

Here’s an example of an individual item returned by this API Endpoint:

{
    "id": "1",
    "name": "John Doe",
    "primaryEmailAddress": {
        "value": "johndoe@example.com",
        "type": "work",
        "isPrimary": true
    },
    "emailAddresses": [
        {
            "value": "johndoe@example.com",
            "type": "work",
            "isPrimary": true
        },
        {
            "value": "johndoe2@example.com",
            "type": "home",
            "isPrimary": false
        }
    ],
    "phoneNumbers": [
        {
            "value": "1234567890",
            "type": "mobile",
            "isPrimary": true
        },
        {
            "value": "0987654321",
            "type": "home",
            "isPrimary": false
        }
    ],
    "socialLinks": [
        {
            "url": "https://www.linkedin.com/in/johndoe",
            "type": "LinkedIn",
            "isPrimary": true
        },
        {
            "url": "https://www.twitter.com/johndoe",
            "type": "Twitter",
            "isPrimary": false
        }
    ],
    "tags": [
        {
            "id": "1",
            "title": "Engineer",
            "isArchived": false
        },
        {
            "id": "2",
            "title": "Experienced",
            "isArchived": false
        }
    ],
    "position": "Software Engineer",
    "company": "ABC Corp",
    "school": "XYZ University",
    "applicationIds": [
        "app1",
        "app2",
        "app3"
    ]
}

Related: Tips for conducting API integration testing

Want to connect to more ATS platforms?

Merge, the leading unified API solution, lets you connect your product to Ashby and dozens of other ATSs, such as Lever, Greenhouse, and Jobvite, through its ATS Unified API. This allows your product to offer more capabilities and richer analytics, as well as simply sync the data your clients need with little friction.

To learn how you can fetch candidates—along with a variety of other types of data—from dozens of ATS solutions, you can schedule a demo with one of our integration experts.