Get Job Application Data from Breezy ATS API

Introduction

This article is part of an ongoing series that breaks down the Breezy ATS API in a practical, use-case–driven way. In this piece, the focus is narrow and execution-oriented: pulling job application (candidate) data from the Breezy ATS API.

If you’re building recruitment analytics, syncing candidate data into an internal HR system, or powering downstream workflows like onboarding or background checks, this is a foundational API flow you’ll rely on.

If you want a broader view of the Breezy API, including authentication, rate limits, and other core concepts, refer to the full Breezy API guide linked earlier.

Get Job Application Data from Breezy ATS API

Pre-requisites

Before you start, make sure the basics are in place:

• Access to the Breezy ATS API with a valid API key
• Company ID and Position ID (required for most candidate retrieval operations)
• A Python environment set up with required libraries such as requests

ATS Endpoints

• Retrieve candidates for a given position
  GET https://api.breezy.hr/v3/company/{company_id}/position/{position_id}/candidates
• Retrieve all candidates with a specific email address
  GET https://api.breezy.hr/v3/company/{company_id}/candidates/search

Step-by-Step Process

1. Retrieve All Candidates for a Position

import requests

def get_candidates_for_position(api_key, company_id, position_id):
    url = f"https://api.breezy.hr/v3/company/{company_id}/position/{position_id}/candidates"
    headers = {"Authorization": api_key}
    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Error: {response.status_code}, {response.json()}")

# Example usage
api_key = "your_api_key"
company_id = "your_company_id"
position_id = "your_position_id"

candidates = get_candidates_for_position(api_key, company_id, position_id)
print(candidates)

2. Retrieve a Candidate by Email

import requests

def get_candidate_by_email(api_key, company_id, email):
    url = f"https://api.breezy.hr/v3/company/{company_id}/candidates/search"
    headers = {"Authorization": api_key}
    params = {"email_address": email}

    response = requests.get(url, headers=headers, params=params)

    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Error: {response.status_code}, {response.json()}")

# Example usage
api_key = "your_api_key"
company_id = "your_company_id"
email = "candidate_email@example.com"

candidate = get_candidate_by_email(api_key, company_id, email)
print(candidate)

This approach is useful when you’re reconciling candidate records across systems or handling inbound workflows triggered by email-based identifiers.

FAQs

1. What is the maximum page size when retrieving candidates?
   The maximum page size supported by the API is 50 records per request.
2. What does a 401 error usually indicate?
   A 401 error almost always points to an invalid, missing, or improperly formatted API key in the request headers.
3. Can candidates be sorted by last updated date?
   Yes. You can use the sort query parameter with the value updated to order results accordingly.
4. Is a position ID mandatory to retrieve candidates?
   Yes. When retrieving candidates tied to a role, a valid position ID is required.
5. What happens if the searched email address doesn’t exist?
   The API will return an empty list, not an error.
6. Can API requests be made without a company ID?
   No. The company ID is mandatory for all Breezy ATS API requests.
7. How is pagination handled?
   Pagination is managed using the page_size and page query parameters to fetch results incrementally.

Pitfalls to Watch Out For

1. Ignoring API rate limits can quickly lead to throttling or temporary access blocks.
2. Skipping HTTP status checks can cause silent failures and broken downstream logic.
3. Using an incorrect or expired API key will result in consistent authentication errors.
4. Not implementing pagination can lead to incomplete or misleading datasets.
5. Sending unvalidated email addresses increases unnecessary API calls and noise.
6. Assuming uniform candidate data structures can break parsing logic as fields vary by stage or source.
7. Failing to track API changes or updates can result in reliance on deprecated endpoints.

Knit for Breezy ATS API Integration

If your goal is to move fast and avoid long-term maintenance overhead, Knit provides a cleaner path. Instead of managing Breezy authentication, pagination, and edge cases yourself, you integrate with Knit once and let it handle the complexity.

Knit abstracts away API quirks, manages authentication flows, and keeps integrations resilient as APIs evolve, allowing teams to focus on product logic.