# Breezy API Documentation

> Breezy API Documentation

## API Reference
- [Webhook Events](https://developer.breezy.hr/reference/webhook-events.md)
- [Webhook Management API](https://developer.breezy.hr/reference/webhook-management-api.md)
- [Webhook Security](https://developer.breezy.hr/reference/webhook-security.md)
- [Customer Guide](https://developer.breezy.hr/reference/customer-guide.md)
- [/signin](https://developer.breezy.hr/reference/signin-1.md): Authenticate with an email and password and receive an `access_token` to send as the `Authorization` header on subsequent requests. If the user already holds a valid token it is returned as-is rather than a new one being issued; tokens are valid for 30 days from last use. Returns `401` if the credentials are incorrect.
- [/signout](https://developer.breezy.hr/reference/signout-1.md): 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. However, this API is stateless and authenticates exclusively via the `Authorization` bearer token header — browsers never automatically attach header-based tokens to passive requests (img tags, prefetch, etc.). CSRF is therefore not applicable here.
- [/health](https://developer.breezy.hr/reference/gethealth.md): 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.
- [/user](https://developer.breezy.hr/reference/getuser.md): Returns the profile of the currently authenticated user.  An optional `user_id` query parameter can be supplied to fetch a different user's profile instead of the caller's own.
- [/user/details](https://developer.breezy.hr/reference/getuserdetails.md): Returns a snapshot of every company the authenticated user belongs to, keyed by each company's `friendly_id`. Each entry includes the company profile, its members, pipelines, positions, message templates, interview guides, questionnaires, scorecards, and tasks, plus EEOC disposition reasons (returned as an empty array if EEOC reporting is disabled for the company) — useful for bootstrapping an integration with all needed IDs in a single call.
- [/companies](https://developer.breezy.hr/reference/listcompanies.md): 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`).
- [/company/{id}](https://developer.breezy.hr/reference/getcompany.md): 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.
- [/company/{id}/departments](https://developer.breezy.hr/reference/listdepartments.md): 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.
- [/company/{id}/categories](https://developer.breezy.hr/reference/listcategories.md): 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. If custom categories can't be retrieved, the endpoint still returns 200 with just the built-in list.
- [/company/{id}/pipelines](https://developer.breezy.hr/reference/listpipelines.md): 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. A Pipeline lists its ordered stages; each stage carries a type and icon, and stages with automations configured also expose the actions that fire when a candidate enters the stage (message templates, message send delays, and questionnaire delays).
- [/company/{id}/pipeline/{id}](https://developer.breezy.hr/reference/getpipeline.md): 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. If `pipelineId` doesn't match a pipeline belonging to the company, the stages of Breezy's built-in default pipeline are returned rather than an error.
- [/company/{id}/questionnaires](https://developer.breezy.hr/reference/listquestionnaires.md): Returns the list of questionnaires configured for the company. Each item includes the questionnaire's `_id`, `name`, `sections`, `questions`, `message_template`, and `options`.
- [/company/{id}/questionnaire/{id}](https://developer.breezy.hr/reference/getquestionnaire.md): 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.
- [/company/{id}/templates](https://developer.breezy.hr/reference/listtemplates.md): 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).
- [/company/{id}/template/{id}](https://developer.breezy.hr/reference/gettemplate.md): Retrieves a single saved message template for the company by its `templateId`, returning the template's `_id`, `name`, and `body`.
- [/company/{id}/custom-attributes/{id}](https://developer.breezy.hr/reference/getcompanycustomattributes.md): 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`.
- [/company/{id}/custom-fields/{id}](https://developer.breezy.hr/reference/getcompanycustomfields.md): 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.
- [/company/{id}/positions](https://developer.breezy.hr/reference/listpositions.md): 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. - Pagination is opt-in: supplying `page_size` returns a paginated page of results (defaulting to page 1, sorted by `updated`); if `page_size` is omitted, all matching positions are returned in a single response.
- [/company/{id}/positions](https://developer.breezy.hr/reference/createposition.md): 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`. If provided, `department` and `category` are checked against the company's configured departments/categories (custom categories are allowed in addition to the built-in list), and `pipeline_id`, `scorecard_id`, and `questionnaire_id` must reference existing company resources — an unrecognized id returns a 404. `salary.currency` must be a supported currency code, and `salary.period` is matched case-insensitively against Breezy's standard salary periods or the company's own custom salary terms. Fields outside the documented schema are dropped before the position is saved.
- [/company/{id}/position/{id}](https://developer.breezy.hr/reference/getposition.md): 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. The `org_type` field distinguishes standard positions (`position`) from candidate pools (`pool`). Returns `404` if the position does not exist.
- [/company/{id}/position/{id}](https://developer.breezy.hr/reference/updateposition.md): 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.  Note: `type`, `education`, `experience`, `category`, and `location.country`/`location.state` are validated against Breezy's configured value lists and return `400` if invalid. `pipeline_id`, `scorecard_id`, and `questionnaire_id`, if provided, are checked for existence and return `404` if the id is not found. `department` and `category` are also checked against the company's configured departments/categories. `salary` (`from`, `to`, `currency`, `period`) is validated and converted into the position's internal `salary_range`; `period` may be one of the legacy period names (`Hourly`, `Daily`, `Weekly`, `Biweekly`, `Monthly`, `Yearly`) or a company-defined salary term.
- [/company/{id}/position/{id}/state](https://developer.breezy.hr/reference/setpositionstate.md): 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.
- [/company/{id}/position/{id}/team](https://developer.breezy.hr/reference/getpositionteam.md): 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.
- [/company/{id}/position/{id}/stream](https://developer.breezy.hr/reference/getpositionstream.md): 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. The full stream is returned as a single array; this endpoint does not support pagination.
- [/company/{id}/position/{id}/custom-fields](https://developer.breezy.hr/reference/getpositioncustomfields.md): 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.
- [/company/{id}/position/{id}/custom-fields/{id}](https://developer.breezy.hr/reference/updatepositioncustomfield.md): Sets the value of a single custom field on a position, identified by its custom field ID.  The submitted `value` is validated against the custom field's configured `data_type`: `string`/`text`/`date` require a string, `dropdown`/`radio` require a string matching one of the field's configured `options.values`, and `currency` requires a number; fields with `data_type: attachment` cannot be updated through this endpoint. On success, returns the full array of the position's custom fields (each with `_id`, `name`, `type`, `data_type`, `value`, `requirement`, and `options`), not just the one that was updated.
- [/company/{id}/candidates/search](https://developer.breezy.hr/reference/searchcandidates.md): 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. Each entry contains only the candidate's `_id`, `name`, and `creation_date`, plus the `position` the candidate is associated with. This is a much smaller shape than the standard candidate list object — the other `ListCandidate` fields (`email_address`, `stage`, `source`, `resume`, `tags`, etc.) are not returned by this endpoint.  The `email_address` query parameter is required; requests without it return `400`.
- [/company/{id}/position/{id}/candidates](https://developer.breezy.hr/reference/listcandidates.md): 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.).  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` defaults to `0`, and `sort` defaults to `updated`.
- [/company/{id}/position/{id}/candidates](https://developer.breezy.hr/reference/addcandidate.md): 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).
- [/company/{id}/position/{id}/candidates/resume](https://developer.breezy.hr/reference/addcandidatebyresume.md): Uploads a resume file, parses it, and creates a new candidate on the given position from the extracted data (name, contact info, work history, education, etc.), returning the created candidate.  Send the resume as `multipart/form-data` with a required `resume` field. The candidate is placed into the pipeline stage identified by the `stage_id` query parameter (defaults to `applied`); set `stage_actions_enabled=true` to trigger that stage's configured automations/webhooks. Returns an error if a candidate already exists on this position, or if the file can't be parsed (corrupted, password-protected, unsupported format, or the parsing service is temporarily unavailable).
- [/company/{id}/position/{id}/candidate/{id}](https://developer.breezy.hr/reference/getcandidate.md): 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. Returns `412` if the candidate exists but is not on the specified position, and `401` if the caller isn't authorized to view the candidate.
- [/company/{id}/position/{id}/candidate/{id}](https://developer.breezy.hr/reference/updatecandidate.md): 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. Only a fixed set of properties is accepted (`name`, `email_address`, `phone_number`, `summary`, `source`, `headline`, `tags`, `address`, `social_profiles`, `custom_attributes`, `cover_letter`); any other properties sent are silently ignored. `email_address` must be a valid email, `tags` must be an array, and each `social_profiles` key must be a supported network name with a valid URL value.
- [/company/{id}/position/{id}/candidate/{id}/meta](https://developer.breezy.hr/reference/getcandidatemeta.md): 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.  Set `include_delayed=1` to also include pending conversation messages that are scheduled for delayed sending but have not yet been sent; by default these are omitted. Returns `412` if the candidate is not on the requested position, and `401` if the acting user lacks permission to view the content.
- [/company/{id}/position/{id}/candidate/{id}/stage](https://developer.breezy.hr/reference/setcandidatestage.md): 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. Moving into a stage with configured actions (e.g., HRIS/onboarding integrations) also triggers those integrations, and moving into a "Hired"-type stage marks the candidate hired. Returns no content (204) on success.
- [/company/{id}/position/{id}/candidate/{id}/scorecard](https://developer.breezy.hr/reference/addcandidatescorecard.md): 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.
- [/company/{id}/position/{id}/candidate/{id}/move](https://developer.breezy.hr/reference/movecandidate.md): 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`.
- [/company/{id}/position/{id}/candidate/{id}/stream](https://developer.breezy.hr/reference/getcandidatestream.md): Returns the candidate's full activity stream on the position — a chronological array of `StreamActivity` events (e.g. stage moves, notes, messages, 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.
- [/company/{id}/position/{id}/candidate/{id}/stream](https://developer.breezy.hr/reference/postcandidatenote.md): 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.
- [/company/{id}/position/{id}/candidate/{id}/conversation](https://developer.breezy.hr/reference/getcandidateconversation.md): 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.  The thread is scoped to the candidate, not to the `positionId` in the path (which only governs access): for a caller who can manage the candidate's other positions, it merges the messages from the same person's applications on those positions.  Supports pagination via the `skip` query parameter (50 records per page). By default, pending/delayed scheduled messages and cancelled messages are excluded; pass `include_delayed=1` to also include the pending/delayed ones (cancelled messages remain excluded).
- [/company/{id}/position/{id}/candidate/{id}/resume](https://developer.breezy.hr/reference/getcandidateresume.md): Downloads the candidate's resume file, streamed directly from storage as a binary response (not JSON), with a `Content-Disposition: attachment` header whose filename is derived from the stored resume URL. Returns `403` when the caller lacks access or no resume is available for the candidate, and `404` when the resume record has no file URL or the file cannot be located in storage.
- [/company/{id}/position/{id}/candidate/{id}/resume](https://developer.breezy.hr/reference/uploadcandidateresume.md): Uploads a resume file and attaches it to the specified candidate, replacing any resume currently on file.  Send the file as `multipart/form-data` with the field name `resume`. Accepted formats are PDF, DOC, DOCX, TXT, RTF, Pages, HTML/HTM, and CFB/AI. On success the endpoint returns an empty `204` response; it only updates the candidate's stored resume (file and URL) and does not re-parse the document to update other candidate profile fields.
- [/company/{id}/position/{id}/candidate/{id}/documents](https://developer.breezy.hr/reference/getcandidatedocuments.md): 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.
- [/company/{id}/position/{id}/candidate/{id}/documents](https://developer.breezy.hr/reference/addcandidatedocument.md): Uploads a file and attaches it to the candidate as a document, returning the created document record.  Send the file as `multipart/form-data` with the field name `document`. On success the response includes the document's file metadata (`file_name`, `file_url`, `file_size`, `creation_date`) along with simplified `position`, `acting_user`, and `candidate` objects. Uploading a document also logs a "document added" company activity entry and updates the candidate's `updated_date` timestamp.
- [/company/{id}/position/{id}/candidate/{id}/questionnaires](https://developer.breezy.hr/reference/getcandidatequestionnaires.md): 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.
- [/company/{id}/position/{id}/candidate/{id}/questionnaire/{id}](https://developer.breezy.hr/reference/submitcandidatequestionnaire.md): 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. Each entry in `responses` is matched to a question by `_id`: checkbox questions use a `responses` array of the selected option text values, while all other question types use a single `response` value. Required questions must be answered, and multiple-choice/dropdown answers must match one of the question's defined options — otherwise the request fails with a 400. Submitting to a questionnaire that is already completed also returns a 400. On success the endpoint returns `204` with no response body.
- [/company/{id}/position/{id}/candidate/{id}/send-questionnaire](https://developer.breezy.hr/reference/sendcandidatequestionnaire.md): 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. By default the candidate is not notified; set `email_candidate=true` to also email them a link to complete the questionnaire.
- [/company/{id}/position/{id}/candidate/{id}/assessments](https://developer.breezy.hr/reference/getcandidateassessments.md): 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.
- [/company/{id}/position/{id}/candidate/{id}/background-checks](https://developer.breezy.hr/reference/getcandidatebackgroundchecks.md): 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.
- [/company/{id}/position/{id}/candidate/{id}/custom-fields](https://developer.breezy.hr/reference/getcandidatecustomfields.md): 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`.
- [/company/{id}/position/{id}/candidate/{id}/custom-fields/{id}](https://developer.breezy.hr/reference/updatecandidatecustomfield.md): 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.  The submitted `value` is validated against the field's configured `data_type`: a string for `string`, `text`, or `date` fields; a string that must match one of the field's `options.values` for `dropdown` or `radio` fields; or a number for `currency` fields. Fields with `data_type` of `attachment` are not supported through this endpoint and return a 400 error.
- [/company/{id}/position/{id}/candidate/{id}/custom-attribute](https://developer.breezy.hr/reference/updatecandidatecustomattribute.md): 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.
- [/company/{id}/position/{id}/candidate/{id}/education](https://developer.breezy.hr/reference/updatecandidateeducation.md): 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. `school_name` is required; `field_of_study`, `start_year`, and `end_year` are optional (the request body's flat `start_year`/`end_year` are stored as the nested `start_date: { year }` / `end_date: { year }` shape seen on education entries in the Candidate response).
- [/company/{id}/position/{id}/candidate/{id}/work-history](https://developer.breezy.hr/reference/updatecandidateworkhistory.md): 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 }`.
- [/company/{id}/position/{id}/candidate/{id}/conversation](https://developer.breezy.hr/reference/sendcandidatemessage.md): 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.
- [/company/{id}/candidates/search](https://developer.breezy.hr/reference/searchcompanycandidates.md): Searches a company's candidates across all positions, accepting the same parameters as the GET form but in a JSON body.  The endpoint has two modes:  - `email_address` — exact match on the normalized (lowercased, trimmed) email address, company-wide. This mode takes precedence when both parameters are supplied and returns a bare array of reduced candidate entries (the `{ total, data }` envelope is not used), identical to the GET email lookup. - `filter_text` — free-text search across the company's candidates via OpenSearch, returning the paginated `{ total, data }` envelope described below. Each entry in `data` is a full candidate list summary (id, name, contact info, stage, source, score, tags, etc.) with the associated `position` attached.  At least one of `email_address` or `filter_text` is required; a request with neither returns `400`. `sort` must be `created` or `updated` (defaults to `updated`); any other value returns `400`. Pagination applies to the free-text mode only: `page_size` defaults to `50` and is capped at `50`, and `page` defaults to `0` and is clamped to a maximum of `19` (20 pages). `archived` defaults to `true` so the search spans the company's full candidate history; set it to `false` to exclude archived candidates.
- [/company/{id}/webhook_endpoints](https://developer.breezy.hr/reference/listwebhookendpoints.md): 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. Results are sorted by creation date descending and capped at 100 endpoints; there is no pagination parameter. Visibility is scoped by the authenticating actor: customer-authenticated requests see all customer-owned endpoints for the company (shared across users and tokens, but excluding partner-owned ones), while partner-authenticated requests see only endpoints owned by that partner integration.
- [/company/{id}/webhook_endpoints](https://developer.breezy.hr/reference/createwebhookendpoint.md): 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. The `secret` field in the response (used to verify payload signatures) is returned only on this create call and cannot be retrieved again afterward, so store it securely.
- [/company/{id}/webhook_endpoint/{id}](https://developer.breezy.hr/reference/getwebhookendpoint.md): 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. Visibility is scoped to the caller: customer-authenticated requests see company-owned webhooks (shared across the company's users/tokens), while partner/integration callers see only the webhooks they own; an endpoint outside the caller's scope returns 404 the same as a nonexistent one.
- [/company/{id}/webhook_endpoint/{id}](https://developer.breezy.hr/reference/updatewebhookendpoint.md): 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). - `events`, if provided, must be a non-empty array of valid event types and fully replaces the existing list. - Setting `enabled: true` clears any auto-disabled state left by repeated delivery failures and resets the consecutive-failure count. It does not otherwise change `status`; use the resume endpoint to fully reactivate a paused endpoint. - The shared secret is never returned here — the full value is shown only once, at creation. The response includes only a `secret_prefix`.
- [/company/{id}/webhook_endpoint/{id}](https://developer.breezy.hr/reference/deletewebhookendpoint.md): 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.
- [/company/{id}/webhook_endpoint/{id}/pause](https://developer.breezy.hr/reference/pausewebhookendpoint.md): 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.
- [/company/{id}/webhook_endpoint/{id}/resume](https://developer.breezy.hr/reference/resumewebhookendpoint.md): 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.