--- updatedAt: 2026-06-16T20:13:34.000Z agentTools: projectIndex: https://developer.breezy.hr/llms.txt --- # /company/{id}/position/{id}/candidates Creates a candidate on the specified position and returns the created candidate record. - `origin: sourced` (the default) adds the candidate directly into the position's "Applied" stage, as if manually sourced. `origin: applied` instead runs the candidate through the same path as a public application: `email_address` is then required, the position must be published (otherwise `412`), and if the position's application form has required fields not satisfied by the payload the API returns `202` and emails the candidate a link to complete them before the record is finalized (rather than `200` with the full candidate). - Returns `409` if a candidate already exists on this position. - `stage_actions_enabled` controls whether add-triggered stage actions fire for sourced candidates; they always fire when `origin` is `applied`. - `source`, `work_history`, `education`, `tags`, `social_profiles`, and `custom_attributes` are validated and normalized (e.g. social profile keys must be from an allowed list, `custom_attributes` entries require `name`/`value`, and `secure` custom attributes get an `_enc`-suffixed id). # 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": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } }, "SimpleUser": { "type": "object", "properties": { "_id": { "type": "string" }, "email_address": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string" }, "initial": { "type": "string" } } }, "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" } } }, "CustomAttribute": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "secure": { "type": "boolean" }, "value": { "type": "string", "nullable": true } } }, "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 } } }, "EducationEntry": { "type": "object", "description": "Note: the `start_date` / `end_date` nested shape reflects how the data is stored\nand returned in the candidate object. The `start_year` / `end_year` flat field\nnames used in PUT /education requests differ from the nested response shape.\n", "properties": { "school_name": { "type": "string" }, "field_of_study": { "type": "string", "nullable": true }, "start_date": { "type": "object", "nullable": true, "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "nullable": true } } }, "end_date": { "type": "object", "nullable": true, "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "nullable": true } } } } }, "WorkHistoryEntry": { "type": "object", "description": "Note: the `start_date` / `end_date` nested shape reflects how the data is stored\nand returned in the candidate object. The `start_year` / `start_month` flat field\nnames used in PUT /work-history requests differ from the nested response shape.\n", "properties": { "company_name": { "type": "string" }, "title": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "start_date": { "type": "object", "nullable": true, "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "nullable": true } } }, "end_date": { "type": "object", "nullable": true, "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "nullable": true } } } } }, "SocialProfile": { "type": "object", "properties": { "type": { "type": "string" }, "typeId": { "type": "string" }, "typeName": { "type": "string" }, "url": { "type": "string" } } }, "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." } } }, "Candidate": { "type": "object", "properties": { "_id": { "type": "string" }, "meta_id": { "type": "string" }, "address": { "type": "string", "nullable": true }, "assigned_to": { "nullable": true }, "cover_letter": { "type": "string", "nullable": true }, "creation_date": { "type": "string" }, "education": { "type": "array", "items": { "$ref": "#/components/schemas/EducationEntry" } }, "email_address": { "type": "string", "nullable": true }, "followed_by": {}, "headline": { "type": "string", "nullable": true }, "initial": { "type": "string" }, "name": { "type": "string" }, "origin": { "type": "string", "enum": [ "applied", "sourced", "referral" ] }, "overall_score": { "$ref": "#/components/schemas/OverallScore" }, "phone_number": { "type": "string", "nullable": true }, "profile_photo_url": { "type": "string", "nullable": true }, "questionnaire": { "nullable": true }, "recruited_by": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SimpleUser" } ] }, "referred_by": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SimpleUser" } ] }, "sourced_by": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SimpleUser" } ] }, "resume": { "$ref": "#/components/schemas/Resume" }, "social_profiles": { "type": "array", "items": { "$ref": "#/components/schemas/SocialProfile" } }, "source": { "$ref": "#/components/schemas/Source" }, "stage": { "$ref": "#/components/schemas/Stage" }, "summary": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "updated_date": { "type": "string" }, "work_history": { "type": "array", "items": { "$ref": "#/components/schemas/WorkHistoryEntry" } }, "custom_attributes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomAttribute" } }, "disposition_date": { "type": "string", "nullable": true }, "disposition_reason": { "nullable": true }, "disposition_reasons": { "type": "array", "items": {}, "nullable": true }, "bias_status": { "type": "string", "nullable": true }, "ai_score": { "$ref": "#/components/schemas/AiScore" } } } } }, "paths": { "/company/{companyId}/position/{positionId}/candidates": { "post": { "operationId": "addCandidate", "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": "stage_actions_enabled", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "When `origin` is `sourced`, whether to execute stage actions on add. Always `true` when `origin` is `applied`." } ], "description": "Creates a candidate on the specified position and returns the created candidate record.\n\n- `origin: sourced` (the default) adds the candidate directly into the position's \"Applied\" stage, as if manually sourced. `origin: applied` instead runs the candidate through the same path as a public application: `email_address` is then required, the position must be published (otherwise `412`), and if the position's application form has required fields not satisfied by the payload the API returns `202` and emails the candidate a link to complete them before the record is finalized (rather than `200` with the full candidate).\n- Returns `409` if a candidate already exists on this position.\n- `stage_actions_enabled` controls whether add-triggered stage actions fire for sourced candidates; they always fire when `origin` is `applied`.\n- `source`, `work_history`, `education`, `tags`, `social_profiles`, and `custom_attributes` are validated and normalized (e.g. social profile keys must be from an allowed list, `custom_attributes` entries require `name`/`value`, and `secure` custom attributes get an `_enc`-suffixed id).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "email_address": { "type": "string", "description": "Required when `origin` is `applied`" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "summary": { "type": "string" }, "cover_letter": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "origin": { "type": "string", "enum": [ "sourced", "applied" ], "default": "sourced" }, "source": { "type": "string", "description": "Custom source label (e.g. `LinkedIn`)" }, "work_history": { "type": "array", "items": { "type": "object", "properties": { "company_name": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "start_month": { "type": "integer" }, "start_year": { "type": "integer" }, "end_month": { "type": "integer" }, "end_year": { "type": "integer" } } } }, "education": { "type": "array", "items": { "type": "object", "properties": { "school_name": { "type": "string" }, "field_of_study": { "type": "string" }, "start_year": { "type": "integer" }, "end_year": { "type": "integer" } } } }, "social_profiles": { "type": "object", "description": "Valid keys: facebook, linkedin, twitter, dribbble, instagram, github, behance, angellist, flickr, youtube, skype, globe", "additionalProperties": { "type": "string" } }, "custom_attributes": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "secure": { "type": "boolean" } } } } } } } } }, "responses": { "200": { "description": "Created candidate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Candidate" } } } }, "202": { "description": "Partial candidate created — missing required application form fields, candidate emailed to complete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate candidate (already exists on this position)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } } ````