---
title: "Get Job Application Data from Breezy ATS API"
description: "Learn how to retrieve job application and candidate data using the Breezy ATS API. This guide covers endpoints, examples, common pitfalls, FAQs, and faster integration using Knit."
source_url: "https://www.getknit.dev/blog/get-job-application-data-from-breezy-ats-api"
page_type: "blog"
---

_This is an educational blog post from Knit's blog: “Get Job Application Data from Breezy ATS API”._

# Get Job Application Data from Breezy ATS API

### Introduction

This article is part of an ongoing series that breaks down the [**Breezy ATS API**](https://www.getknit.dev/integration/breezy-hr) 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](https://www.getknit.dev/blog/breezy-api-directory-7VGL6y) guide linked earlier.

### Pre-requisites

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

*   Access to the [Breezy ATS API](https://developers.getknit.dev/docs/breezy-usecases) 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`

#### 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](https://www.getknit.dev/integration/breezy-hr) 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.


## Related pages

- [How Knit works](https://md.getknit.dev/how-knit-works)
- [Unified API product](https://md.getknit.dev/products/unified-api)