--- updatedAt: 2026-06-16T20:13:34.000Z agentTools: projectIndex: https://developer.breezy.hr/llms.txt --- # /company/{id}/position/{id}/candidates Returns the candidates on a given position within a company, as an array of candidate summaries (id, name, contact info, stage, source, score, resume link, etc.). Pass `stage_id` to restrict the result to one pipeline stage. By default all candidates on the position are returned in a single unpaged response. Supplying `page_size` switches to paged mode: `page_size` is capped at 50 regardless of the value requested, `page` is 1-based (`page=1` is the first page; `page=0` also returns the first page), and `sort` defaults to `updated`. # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "Breezy HR Public API", "version": "3", "description": "The Breezy HR public API (v3) provides programmatic access to your recruiting data.\nAll endpoints are relative to `https://api.breezy.hr/v3`.\n\n## Authentication\n\nPass a **Personal Access Token (PAT)** in the `Authorization` header:\n```\nAuthorization: Bearer breezy_pat_\n```\n\nAlternatively, call `POST /v3/signin` with email and password to receive a session\n`access_token`, then pass it the same way.\n\nBoth header forms are accepted for PATs and session tokens: `Authorization: Bearer `\nand the bare `Authorization: `. The `Bearer` scheme is matched case-insensitively.\n\n## IDs\n\nAll resource IDs are 12–14 character lowercase hex strings (e.g. `a3f9c1d2e4b5`).\nEU-region resources use 14-character IDs ending in `01`.\n\n## Dates\n\nAll date/timestamp fields are ISO 8601 strings.\n\n## Errors\n\nAll error responses use the shape:\n```json\n{ \"error\": { \"type\": \"string\", \"message\": \"string\" } }\n```\n\nEvery `/company/{companyId}/...` endpoint returns `403` with type `companyMembershipRequired`\nwhen the authenticated user is not a member of that company, for example after the user who\ncreated the token was removed from the account.\n" }, "servers": [ { "url": "https://api.breezy.hr/v3", "description": "Production" } ], "security": [ { "TokenAuth": [] } ], "tags": [ { "name": "Candidates", "description": "Candidate management and all sub-resources" } ], "components": { "securitySchemes": { "TokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Personal Access Token (PAT) or session token from POST /v3/signin, passed in the Authorization header either bare or with a Bearer prefix (both forms are accepted). Declared as apiKey rather than http/bearer so that tools do not force the prefix - the bare form is equally valid." } }, "schemas": { "StageType": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "icon": { "type": "string" } } }, "Stage": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Built-in stages have string ids such as `applied`; custom stages have numeric ids." }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/StageType" } } }, "Source": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "OverallScore": { "type": "object", "properties": { "very_good": { "type": "array", "items": { "type": "string" } }, "good": { "type": "array", "items": { "type": "string" } }, "neutral": { "type": "array", "items": { "type": "string" } }, "poor": { "type": "array", "items": { "type": "string" } }, "very_poor": { "type": "array", "items": { "type": "string" } }, "scored_count": { "type": "integer" }, "average_score": { "type": "number", "nullable": true }, "score": { "type": "number", "nullable": true } } }, "Resume": { "type": "object", "nullable": true, "properties": { "file_name": { "type": "string" }, "file_size": { "type": "integer" }, "url": { "type": "string" }, "content_type": { "type": "string" } } }, "AiScore": { "description": "The candidate's latest AI score (Applicant Insight). Absent when the candidate has never been scored.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "score": { "type": "number", "minimum": 0, "maximum": 10, "description": "Overall score from 0 to 10. Present when `status` is `completed`." }, "recommendation": { "type": "string", "description": "The AI recommendation for the candidate. Present when `status` is `completed`." }, "completed_at": { "type": "string", "format": "date-time", "description": "When scoring completed. Present when `status` is `completed`." }, "reason_code": { "type": "string", "description": "Why scoring failed, when known. Present only when `status` is `failed`; for example `insufficient_credits` when the company has run out of AI credits." } } }, "ListCandidate": { "description": "Abbreviated candidate shape returned in list responses.", "type": "object", "properties": { "_id": { "type": "string" }, "meta_id": { "type": "string" }, "assigned_to": { "nullable": true }, "creation_date": { "type": "string" }, "email_address": { "type": "string", "nullable": true }, "headline": { "type": "string", "nullable": true }, "initial": { "type": "string" }, "name": { "type": "string" }, "origin": { "type": "string" }, "phone_number": { "type": "string", "nullable": true }, "profile_photo_url": { "type": "string", "nullable": true }, "resume": { "$ref": "#/components/schemas/Resume" }, "source": { "$ref": "#/components/schemas/Source" }, "stage": { "$ref": "#/components/schemas/Stage" }, "tags": { "type": "array", "items": { "type": "string" } }, "disposition_date": { "type": "string", "nullable": true }, "disposition_reason": { "nullable": true }, "disposition_reasons": { "nullable": true }, "overall_score": { "$ref": "#/components/schemas/OverallScore" }, "updated_date": { "type": "string" }, "bias_status": { "type": "string", "nullable": true }, "ai_score": { "$ref": "#/components/schemas/AiScore" } } } } }, "paths": { "/company/{companyId}/position/{positionId}/candidates": { "get": { "operationId": "listCandidates", "summary": "/company/{id}/position/{id}/candidates", "tags": [ "Candidates" ], "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "positionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "description": "Number of candidates per page, capped at 50. Omit `page_size` to receive the full unpaged list.", "schema": { "type": "integer", "maximum": 50 } }, { "name": "page", "in": "query", "description": "Page number, only used when `page_size` is set. Paging is effectively 1-based - `page=1` returns the first page and `page=2` the second. `page=0` (and an omitted `page`) also returns the first page, so a client that counts from 0 receives the first page twice. This offset is long-standing behavior and is preserved for backward compatibility.", "schema": { "type": "integer", "default": 1 } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "stage_id", "in": "query", "description": "Optional. Only return candidates currently in this pipeline stage. Use the stage `id` values from `GET /company/{companyId}/pipeline/{pipelineId}` - built-in stages are strings such as `applied`, custom stages are numeric ids. Works with and without `page_size`. An unknown stage id returns an empty list; a value that is not a plain token of letters, digits, `_` or `-` returns 400.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "maxLength": 64 } } ], "description": "Returns the candidates on a given position within a company, as an array of candidate summaries (id, name, contact info, stage, source, score, resume link, etc.). Pass `stage_id` to restrict the result to one pipeline stage.\n\nBy default all candidates on the position are returned in a single unpaged response. Supplying `page_size` switches to paged mode: `page_size` is capped at 50 regardless of the value requested, `page` is 1-based (`page=1` is the first page; `page=0` also returns the first page), and `sort` defaults to `updated`.", "responses": { "200": { "description": "List of candidates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ListCandidate" } } } } } } } } } } ````