Breezy HR

Deletes an assessment by Breezy `_id`. When authenticated with a partner API key, only assessments owned by that partner's `provider_type` may be deleted. Breezy DELETE /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/assessments/{assessmentId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Permanently deletes the specified webhook endpoint so it stops receiving any further event deliveries. Note: the response is a `200` JSON confirmation object (`success`, `message`, `endpoint_id`), not an empty body. Breezy DELETE /v3/company/{companyId}/webhook_endpoint/{endpointId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the companies the authenticated user belongs to, as an array of company summary objects (`_id`, `name`, `friendly_id`, `member_count`, `initial`, `creation_date`, `updated_date`). Breezy GET /v3/companies.

Retrieves the company identified by `companyId` and returns its public profile: `_id`, `name`, `friendly_id`, `member_count`, `initial`, `creation_date`, and `updated_date`. Access requires the company's plan to have the Developer API feature enabled; if it doesn't, the request is rejected with a 403. Breezy GET /v3/company/{companyId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Finds candidates in the company whose email address matches `email_address`, searching company-wide across all positions rather than within a single job. Matching is exact on the normalized (lowercased, trimmed) email address — not a partial or fuzzy text search. Returns an array with one lightweight entry per matching candidate. Breezy GET /v3/company/{companyId}/candidates/search. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the list of position category definitions available to the company, each with an `id` and `name`. The response combines Breezy's standard built-in categories (e.g. Software Development, Sales, Marketing) with any custom categories the company has defined; a custom category is only added if its `id` doesn't already match a built-in one. Breezy GET /v3/company/{companyId}/categories. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the custom attribute definitions configured for the company, filtered by entity `type` (`candidate` or `position`). Each item includes its `id`, `name`, and whether it is `secure`. Breezy GET /v3/company/{companyId}/custom-attributes/{type}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the company's custom field definitions for the given `type` (`candidate` or `position`) — the field metadata (name, data type, options, etc.) configured at the company level, not the values recorded on any specific candidate or position. Each definition's `_id` is the `company_custom_field_id` used when reading or setting that field's value on an individual candidate or position record. Breezy GET /v3/company/{companyId}/custom-fields/{type}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the list of department definitions configured for the company, each with an `id` and `name`. A department's `name` is the value accepted for the `department` field when creating or updating a position. Breezy GET /v3/company/{companyId}/departments. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the ordered list of stages that make up the specified pipeline, as an array of stage objects (e.g. `id`, `name`, `icon`) — not the full pipeline record (name, dates, etc.). `pipelineId` can be an actual pipeline ID, or the special values `default` / `default_pool` for the company's default position pipeline or talent-pool pipeline. Breezy GET /v3/company/{companyId}/pipeline/{pipelineId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the company's configured hiring pipelines as a JSON object keyed by pipeline name (e.g. `default`, `default_pool`), where each value is a Pipeline object. Breezy GET /v3/company/{companyId}/pipelines. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Retrieves a single position by ID, returning its full details (name, type, state, location, department, description, application form configuration, salary range, custom attributes, and team/admin user lists). If the position has a pending approval workflow, the response includes a `pending_approval` object describing the approvers. Breezy GET /v3/company/{companyId}/position/{positionId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Retrieves a single candidate by ID, scoped to the given company and position, and returns the full candidate profile (contact info, source, stage, resume, education, work history, tags, scoring, etc.). Note: `resume.url`, if present, is rewritten to point back to this API's `/resume` sub-endpoint rather than the raw file location. Breezy GET /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the candidate's assessment results from integrated pre-employment testing providers (currently HackerRank, Criteria Corp, and Indeed Assessments), including status, score(s), test link, and report URL for each. Results from providers other than these are silently omitted from the response array. Breezy GET /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/assessments. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the list of background check results requested for the candidate on this position. Each result includes `service_id` (`goodhire` or `checkr`), `id`, `status`, `report_url`, `creation_date`, `updated_date`, and `completion_date`. Background checks run through providers other than GoodHire or Checkr are omitted from the response. Breezy GET /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/background-checks. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the candidate's message and activity thread — messages sent to or from the candidate (including messages posted by external users) and interview/meeting-time proposal events — ordered newest first. Breezy GET /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/conversation. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the custom field values recorded for a candidate on the specified position, as an array of custom field objects. Each object includes the field's `_id`, `name`, `type`, `data_type`, `value`, `secure` flag, `options`, and the parent `company_custom_field_id`. Breezy GET /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/custom-fields. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the files stored for the candidate on this position — resumes and other documents uploaded by the candidate or added by recruiters — ordered most recently uploaded first. Each document's `file_url` is a secured download URL rather than a direct file link. Returns `412` if the candidate is not associated with the specified position. Breezy GET /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/documents. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns a single aggregated bundle of activity and content for a candidate on a given position: tasks, notes (notepad and team notepad), documents, scorecards, questionnaires, interview schedule, stream (pipeline activity), conversation (messages), background checks, assessments, references, offers, e-docs, match score, and custom fields. Breezy GET /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/meta. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the questionnaires sent to this candidate for the given position, including each questionnaire's sections and questions along with the candidate's submitted responses. File-upload question responses have their file URL rewritten to a secure v3 attachment link served through the authenticated API. Breezy GET /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/questionnaires. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the candidate's full activity stream on the position — a chronological array of `StreamActivity` events (e.g. stage moves, notes, interviews, questionnaire activity), each with a `type`, `timestamp`, `first_of_day` flag, and an `object` payload whose shape varies by event type. To add a note to the stream, use the corresponding `POST` on this same endpoint. Breezy GET /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/stream. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

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. Breezy GET /v3/company/{companyId}/position/{positionId}/candidates. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the custom fields configured on the specified position as an array of field objects (`_id`, `name`, `type`, `data_type`, `value`, `requirement`, and, where applicable, `options`). For fields with `data_type: "attachment"`, `value` is an array of attachment objects. Each attachment's `url` is rewritten to include a temporary download token (a `key` query parameter) that is valid for 1 hour. Breezy GET /v3/company/{companyId}/position/{positionId}/custom-fields. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the position's activity stream: a list of state-change events recorded against the position (e.g. transitions between `draft`, `published`, `closed`, and `archived`). Each entry includes the previous and new state (`state_was`/`state_is`), the acting user, a timestamp, and snapshots of the position and company at the time of the event. Breezy GET /v3/company/{companyId}/position/{positionId}/stream. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the list of team members assigned to the specified position, including each member's user profile and the role(s) (e.g. recruiter, hiring manager, interviewer) they hold on that position. Breezy GET /v3/company/{companyId}/position/{positionId}/team. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the positions belonging to the specified company. - Filter by lifecycle state with the `state` query parameter (`published`, `draft`, `archived`, `closed`, `pending`); when `state` is omitted, archived positions are excluded from the results. Breezy GET /v3/company/{companyId}/positions. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Retrieves a single questionnaire belonging to the company by its ID, including its sections and questions (each with its text, type, required flag, and answer options), the associated message template, and questionnaire options such as the default "move to" pipeline stage/status. Breezy GET /v3/company/{companyId}/questionnaire/{questionnaireId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the list of questionnaires configured for the company. Each item includes the questionnaire's `_id`, `name`, `sections`, `questions`, `message_template`, and `options`. Breezy GET /v3/company/{companyId}/questionnaires. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Retrieves a single saved message template for the company by its `templateId`, returning the template's `_id`, `name`, and `body`. Breezy GET /v3/company/{companyId}/template/{templateId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns the list of message templates configured for the company, each item including its `_id`, `name`, and `body`. Returns all templates in a single response (no pagination). Breezy GET /v3/company/{companyId}/templates. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Retrieves a single webhook endpoint's configuration and delivery stats by its ID. The response includes `url`, `description`, `events`, `status`, `enabled`, delivery `stats` (success/failure counts, last delivery timestamps), auto-disable state, and `secret_prefix` — the full signing secret is only ever returned when the endpoint is created, not here. Breezy GET /v3/company/{companyId}/webhook_endpoint/{endpointId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Lists the webhook endpoints configured for the company, along with quota usage. Returns a `data` array of endpoints (`id`, `url`, `description`, `events`, `status`, `enabled`, delivery `stats`, auto-disable info, `secret_prefix`, timestamps) and a `meta` object with `total` and a `quota` breakdown (`current`, `limit`, `available`, `exceeded`) against the per-company webhook limit. Breezy GET /v3/company/{companyId}/webhook_endpoints. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Returns `200 OK` if the API service is running; the response body is the plain-text status message `OK`. Use this as a simple liveness check. It requires no authentication and does not reflect the health of downstream dependencies — the handler always returns 200 without performing any checks. Breezy GET /v3/health. Breezy exempts this operation from the Authorization header.

Invalidates the current access token, signing the user out; returns `204` with no body. **Idempotent:** the endpoint always returns `204`, even if the `Authorization` header is missing or the token was already invalid/expired — there is no error response for this case. **Note on CSRF:** This endpoint uses GET, which can be triggered passively by browsers. Breezy GET /v3/signout. Flagged destructive by Agentic Fabriq: whether this invalidates the Personal Access Token this connection holds, or only a /v3/signin session token, is undocumented and unmeasured -- if it is the former the connection needs a new key pasted.

Returns the profile of the currently authenticated user. Breezy GET /v3/user.

Returns a snapshot of every company the authenticated user belongs to, keyed by each company's `friendly_id`. Breezy GET /v3/user/details.

Free-text search across every candidate in the company, served by the same search index that powers in-app candidate search. This verb always returns the paginated envelope below - one request contract, one response contract. `email_address` is not accepted here and returns `400`. Breezy POST /v3/company/{companyId}/candidates/search. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Upserts an assessment keyed on `(provider_type, external_id)` for the candidate-position. When authenticated with a partner API key, `provider_type` is set from the partner registry and `provider_name` in the body is ignored. Customer tokens may set `provider_name` when no partner key is present. All content blocks are optional except identity fields. Breezy POST /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/assessments. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Sends a message to the candidate within their conversation for this position, delivering it directly to the candidate (e.g. by email), and returns the resulting conversation activity record. `body` (HTML or plain text) is required; `subject` and a file `attachment` may also be included. Breezy POST /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/conversation. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Moves a candidate to a target position and pipeline stage, and returns the updated candidate. `target_position_id` and `target_stage_id` are required. Set `stage_actions_enabled` to `true` to run the target stage's configured automated actions (e.g. emails, questionnaires) on the move; it defaults to `false`. Breezy POST /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/move. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Submits a candidate's answers to a questionnaire that was sent to them, validates them against the questionnaire's questions, and marks the questionnaire completed. Note: `questionnaireId` is the ID of the candidate's specific questionnaire response (as returned by the list-questionnaires endpoint), not the questionnaire template ID. Breezy POST /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/questionnaire/{questionnaireId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Sends an existing questionnaire template to the candidate, attaching it to the candidate's record on the given position and returning the resulting candidate questionnaire (sections, questions, status, etc.). The questionnaire to send is identified by the required `questionnaire_id` query parameter. Breezy POST /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/send-questionnaire. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Adds an internal note to the candidate's activity stream and returns the created stream activity, including the note body and the position/candidate/acting-user context. Notes are internal to your team — they are not sent to or visible by the candidate. A non-empty `body` is required; omitting it returns a 400. Breezy POST /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/stream. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

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. Breezy POST /v3/company/{companyId}/position/{positionId}/candidates. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Creates a new position (job requisition) for the company and returns the newly created position object. `name`, `type`, `description`, and `location.country` are required. `type`, `experience`, and `education` must match Breezy's supported values, and `location.state` is validated against US states or Canadian provinces when `location.country` is `US` or `CA`. Breezy POST /v3/company/{companyId}/positions. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Pauses a webhook endpoint, stopping event deliveries to it, and returns the updated webhook endpoint object. Sets the endpoint's `status` to `paused` and `enabled` to `false`; the endpoint and its configuration are preserved and can be re-enabled later via the resume endpoint. Breezy POST /v3/company/{companyId}/webhook_endpoint/{endpointId}/pause. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Resumes a paused (or auto-disabled) webhook endpoint, setting it back to active and re-enabling event delivery. Resuming also clears any auto-disable state — failure count, auto-disabled reason, and auto-disabled timestamp — so an endpoint that was automatically disabled after repeated delivery failures starts fresh rather than immediately re-tripping. Returns the updated webhook endpoint object. Breezy POST /v3/company/{companyId}/webhook_endpoint/{endpointId}/resume. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Creates a new webhook endpoint for the company and subscribes it to the specified event types, so matching events are delivered to the given URL as they occur. Each company is limited to 10 webhook endpoints — exceeding this quota returns a 429. Breezy POST /v3/company/{companyId}/webhook_endpoints. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Updates an existing position and returns the full updated position object. This is a partial update — include only the fields you want to change; any field not on the position's editable-fields list is silently dropped from the request. Breezy PUT /v3/company/{companyId}/position/{positionId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Updates editable profile fields on an existing candidate within a position, and returns the full updated candidate object. This is a partial update — include only the fields you want to change. Breezy PUT /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Sets a custom attribute on a candidate and returns the updated candidate object. Requires `name` and a string `value`; if a custom attribute with the same name (and `secure` flag) already exists on the candidate, its value is updated, otherwise a new attribute is added. Set `secure: true` to have the value stored encrypted. Breezy PUT /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/custom-attribute. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Updates the value of one custom field on a candidate, identified by the company-level custom field ID, and returns the candidate's complete list of custom fields reflecting the change. Breezy PUT /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/custom-fields/{customFieldId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Adds a new education entry to the candidate's profile and returns the updated Candidate object. The new entry is appended to the candidate's existing education history rather than replacing it. Breezy PUT /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/education. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Records a scorecard rating for the candidate on the specified position, attributed to the authenticated API user. Requires `score`, one of `very_good`, `good`, `neutral`, `poor`, or `very_poor`; only `score` and `note` are persisted, and all other request body properties are silently discarded. Returns `204 No Content` with an empty body on success. Breezy PUT /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/scorecard. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Moves the candidate to a different stage in the position's pipeline, identified by `stage_id`. `stage_id` must match a stage in that position's pipeline (falling back to the company's default pipeline); an unknown stage id fails the request. Every successful move records a stage-change activity and fires the corresponding webhook. Breezy PUT /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/stage. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Appends a new entry to the candidate's work history and returns the full updated [Candidate](#schema/candidate) object. `company_name` is required. Note that the request body uses flat `start_year` / `start_month` / `end_year` / `end_month` fields, but the `work_history` entries in the response are nested as `start_date: { year, month }` / `end_date: { year, month }`. Breezy PUT /v3/company/{companyId}/position/{positionId}/candidate/{candidateId}/work-history. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Sets the value of a single custom field on a position, identified by its custom field ID. Breezy PUT /v3/company/{companyId}/position/{positionId}/custom-fields/{customFieldId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Updates the state (lifecycle status) of a position, moving it between `published`, `draft`, `archived`, and `closed`. Returns no content on success. Setting `state` to `published` can fail with a 400 error if the company has reached its active position limit. Breezy PUT /v3/company/{companyId}/position/{positionId}/state. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.

Updates an existing webhook endpoint and returns the updated resource. Only the fields included in the request body are changed — omitted fields keep their current value. A few notes: - `url` must use HTTPS; private/internal IP ranges are rejected (the same validation applied at creation). Breezy PUT /v3/company/{companyId}/webhook_endpoint/{endpointId}. Company-scoped: call List companies (GET /v3/companies) first to resolve companyId.