# Ashby Documentation > Documentation for Ashby ## Guides - [Getting Started with Ashby](https://developers.ashbyhq.com/docs/getting-started.md) - [Creating a Custom Careers Page](https://developers.ashbyhq.com/docs/creating-a-custom-careers-page.md) - [Dedicated Partner Job Feeds](https://developers.ashbyhq.com/docs/dedicated-partner-job-feeds.md) - [Ashby Job Postings API](https://developers.ashbyhq.com/docs/public-job-posting-api.md) - [Creating an Assessments Integration](https://developers.ashbyhq.com/docs/creating-an-assessments-integration.md): A guide on how to integrate with Ashby's Assessments Framework - [Pagination and Incremental Synchronization](https://developers.ashbyhq.com/docs/pagination-and-incremental-sync.md) - [Setting up Webhooks](https://developers.ashbyhq.com/docs/setting-up-webhooks.md) - [Common Payload Data](https://developers.ashbyhq.com/docs/common-payload-data.md) - [Authenticating Webhooks](https://developers.ashbyhq.com/docs/authenticating-webhooks.md) - [Retries](https://developers.ashbyhq.com/docs/retries.md) - [Related Webhooks](https://developers.ashbyhq.com/docs/related-webhooks.md) - [Authentication](https://developers.ashbyhq.com/docs/authentication.md) - [Introduction](https://developers.ashbyhq.com/docs/introduction.md) - [Support](https://developers.ashbyhq.com/docs/support.md) - [Endpoint Naming](https://developers.ashbyhq.com/docs/endpoint-naming.md) - [Expansions](https://developers.ashbyhq.com/docs/expansions.md) - [Pagination](https://developers.ashbyhq.com/docs/pagination.md) - [Responses & Errors](https://developers.ashbyhq.com/docs/responses.md) - [Syncing Records](https://developers.ashbyhq.com/docs/sync.md) - [Audit Log Vocabulary](https://developers.ashbyhq.com/docs/audit-log-vocabulary.md) ## API Reference - [Introduction](https://developers.ashbyhq.com/reference/introduction.md) - [apiKey.info](https://developers.ashbyhq.com/reference/apikeyinfo.md): Returns details for the API key used to make the request. **Requires the [`apiKeysRead`](authentication#permissions-apikeyinfo) permission.** - [Authentication](https://developers.ashbyhq.com/reference/authentication.md) - [Support](https://developers.ashbyhq.com/reference/support.md) - [Endpoint Naming](https://developers.ashbyhq.com/reference/endpoint-naming.md) - [Responses & Errors](https://developers.ashbyhq.com/reference/responses.md) - [Pagination](https://developers.ashbyhq.com/reference/pagination.md) - [Syncing Records](https://developers.ashbyhq.com/reference/sync.md) - [Expansions](https://developers.ashbyhq.com/reference/expansions.md) - [application.changeSource](https://developers.ashbyhq.com/reference/applicationchangesource.md): Change the source of an application. **Requires the [`candidatesWrite`](authentication#permissions-applicationchangesource) permission.** - [application.changeStage](https://developers.ashbyhq.com/reference/applicationchangestage.md): Change the stage of an application. **Requires the [`candidatesWrite`](authentication#permissions-applicationchangestage) permission.** - [application.create](https://developers.ashbyhq.com/reference/applicationcreate.md): Consider a candidate for a job (e.g. when sourcing a candidate for a job posting). If you're submitting an application as a job board, use the [`applicationForm.submit`](ref:applicationformsubmit) endpoint instead. See [Creating a custom careers page](https://developers.ashbyhq.com/docs/creating-a-custom-careers-page) for details. To set values for custom fields on Applications, use the [`customField.setValue`](ref:customfieldsetvalue) endpoint. **Requires the [`candidatesWrite`](authentication#permissions-applicationcreate) permission.** - [application.info](https://developers.ashbyhq.com/reference/applicationinfo.md): Fetch application details by application id or by submitted form instance id (which is returned by the `applicationForm.submit` endpoint). If both `applicationId` and `submittedFormInstanceId` are provided, the lookup uses `applicationId`. **Requires the [`candidatesRead`](authentication#permissions-applicationinfo) permission.** - [application.list](https://developers.ashbyhq.com/reference/applicationlist.md): Gets all applications in the organization. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`candidatesRead`](authentication#permissions-applicationlist) permission.** - [application.transfer](https://developers.ashbyhq.com/reference/applicationtransfer.md): Transfer an application to a different job. **Requires the [`candidatesWrite`](authentication#permissions-applicationtransfer) permission.** - [application.update](https://developers.ashbyhq.com/reference/applicationupdate.md): Update an application. To set values for custom fields on Applications, use the [`customField.setValue`](ref:customfieldsetvalue) endpoint. **Requires the [`candidatesWrite`](authentication#permissions-applicationupdate) permission.** - [application.updateHistory](https://developers.ashbyhq.com/reference/applicationupdatehistory.md): Update the history of an application. Used to update stage timestamps and to delete history events. **Also requires the `Allow updating application history?` setting found in your admin API key permissions configuration.** **Requires the [`candidatesWrite`](authentication#permissions-applicationupdatehistory) permission.** - [application.listHistory](https://developers.ashbyhq.com/reference/applicationlisthistory.md): Fetch a paginated list of application history items for an application. This endpoint supports pagination only (not incremental sync). See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for usage examples. **Requires the [`candidatesRead`](authentication#permissions-applicationlisthistory) permission.** - [application.listCriteriaEvaluations](https://developers.ashbyhq.com/reference/applicationlistcriteriaevaluations.md): Fetch a paginated list of AI criteria evaluations for an application. This endpoint returns the AI-generated criteria evaluations that assess how well a candidate meets specific job requirements. Each evaluation contains the outcome, reasoning, and other assessment details. This endpoint supports pagination only (not incremental sync). See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for usage examples. **Note:** This endpoint requires the AI Application Review feature to be enabled for your organization. **Requires the [`candidatesRead`](authentication#permissions-applicationlistcriteriaevaluations) permission.** - [application.delete](https://developers.ashbyhq.com/reference/applicationdelete.md): Deletes an application by id. **Requires the [`candidatesDelete`](authentication#permissions-applicationdelete) permission.** - [application.addHiringTeamMember](https://developers.ashbyhq.com/reference/applicationaddhiringteammember-1.md): Adds an Ashby user to the hiring team at the application level. **Requires the [`candidatesWrite`](authentication#permissions-applicationaddhiringteammember) permission.** - [application.removeHiringTeamMember](https://developers.ashbyhq.com/reference/applicationremovehiringteammember-1.md): Unassigns a hiring team role from an Ashby user at the application level. **Requires the [`candidatesWrite`](authentication#permissions-applicationremovehiringteammember) permission.** - [application.change_stage](https://developers.ashbyhq.com/reference/applicationchange_stage.md): **Deprecated.** Use [`application.changeStage`](ref:applicationchangestage) instead. Change the stage of an application. **Requires the [`candidatesWrite`](authentication#permissions-applicationchange_stage) permission.** - [application.change_source](https://developers.ashbyhq.com/reference/applicationchange_source.md): **Deprecated.** Use [`application.changeSource`](ref:applicationchangesource) instead. Change the source of an application. **Requires the [`candidatesWrite`](authentication#permissions-applicationchange_source) permission.** - [applicationFeedback.list](https://developers.ashbyhq.com/reference/applicationfeedbacklist.md): List all interview scorecards and feedback submissions associated with an application. Each feedback submission contains: - **formDefinition**: The structure of the feedback form with all available fields - **submittedValues**: Responses to the form fields, which depending on the form configuration can include: - Text feedback (e.g., "Candidate showed strong technical skills...") - Numerical scores (e.g., "4" for a 1-4 rating scale) - Structured selections, returned as the stored option value rather than its display label (e.g., "hire", not "Hire"); use the field's `selectableValues` in `formDefinition` to map values to labels - **Interview context**: Links to associated interviews, events, and the submitting user See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`candidatesRead`](authentication#permissions-applicationfeedbacklist) permission.** - [applicationFeedback.submit](https://developers.ashbyhq.com/reference/applicationfeedbacksubmit-1.md): Application feedback forms support a variety of field types. The values accepted for each field depend on the type of field that's being filled out: - `Boolean` - A boolean value - `CompensationRange` - An object in the format `{ type: "compensation-range", minValue: 100000, maxValue: 150000, currencyCode: "USD", interval: "1 YEAR" }`. `currencyCode` must be a valid ISO 4217 code and `interval` must be a valid compensation interval (e.g. `"1 HOUR"`, `"1 YEAR"`). - `Currency` - An object in the format `{ value: 100000, currencyCode: "USD" }`. `currencyCode` must be a valid ISO 4217 code. - `Date` - A date string in the format YYYY-MM-DD - `Email` - A valid email address - `LongText`, `Phone`, `String` - A string - `MultiValueSelect` - An array of strings that exist in the MultiValueSelect field's selectable options - `Number` - An integer - `NumberRange` - An object in the format `{ type: "number-range", minValue: 1, maxValue: 10 }` - `RichText` - We do not support submitting rich text documents via the API but we do support submitting plain text values for these fields. Plain text values must be submitted in the format `{ type: "PlainText", value: "A plain text string" }` - `Score` - An integer between 1 and 4 submitted in the format `{ score: 4 }` - `Url` - A valid URL string. The empty string is also accepted. - `UUID` - A UUID string, or an object in the format `{ value: "" }` - `ValueSelect` - A string that matches the value of one of the ValueSelect field's selectable options The `submittedValues` field in the response contains the submitted feedback in an object where the key is the path of the field and the value is the value submitted for that field. **Requires the [`candidatesWrite`](authentication#permissions-applicationfeedbacksubmit) permission.** - [applicationFeedbackRequest.create](https://developers.ashbyhq.com/reference/applicationfeedbackrequestcreate-1.md): Request feedback on an application without scheduling an interview. The `interviewEventId` returned in the response can be provided to `applicationFeedback.submit` to complete the feedback request. The interview used must be configured to request feedback. **Requires the [`candidatesWrite`](authentication#permissions-applicationfeedbackrequestcreate) permission.** - [applicationForm.submit](https://developers.ashbyhq.com/reference/applicationformsubmit-1.md): Submits a completed application form for a job posting. **Requires the [`candidatesWrite`](authentication#permissions-applicationformsubmit) permission.** - [applicationHiringTeamRole.list](https://developers.ashbyhq.com/reference/applicationhiringteamrolelist.md): Gets all available hiring team roles for applications in the organization. **Requires the [`candidatesRead`](authentication#permissions-applicationhiringteamrolelist) permission.** - [approval.list](https://developers.ashbyhq.com/reference/approvallist.md): Gets all approvals in the organization. You can optionally filter by entity type and entity ID. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`approvalsRead`](authentication#permissions-approvallist) permission.** - [approvalDefinition.update](https://developers.ashbyhq.com/reference/approvaldefinitionupdate.md): Create or update an approval definition for a specific entity that requires approval. The entity requiring approval must be within scope of an approval in Ashby that is marked as being managed by the API. If the provided approval step definitions is an empty list, then approval will be skipped and the entity will proceed to the next stage. **Requires the [`approvalsWrite`](authentication#permissions-approvaldefinitionupdate) permission.** - [archiveReason.list](https://developers.ashbyhq.com/reference/archivereasonlist-1.md): Lists archive reasons. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-archivereasonlist) permission.** - [assessment.addCompletedToCandidate](https://developers.ashbyhq.com/reference/assessmentaddcompletedtocandidate.md): Add a completed assessment to a candidate. **Requires the [`candidatesWrite`](authentication#permissions-assessmentaddcompletedtocandidate) permission.** - [assessment.start (Implemented by Partner)](https://developers.ashbyhq.com/reference/assessmentstart.md): The API for starting an assessment. Implemented by the partner, called by Ashby. - [assessment.list (Implemented by Partner)](https://developers.ashbyhq.com/reference/assessmentlist-implemented-by-partner.md): The API for listing assessments that the partner supports — implemented by the partner, but called by Ashby - [assessment.update](https://developers.ashbyhq.com/reference/assessmentupdate.md): Update Ashby about the status of a started assessment. `assessment_status` is required unless `cancelled_reason` is provided. **Requires the [`candidatesWrite`](authentication#permissions-assessmentupdate) permission.** - [assessment.cancel (Implemented by Partner)](https://developers.ashbyhq.com/reference/assessmentcancel.md): (Optional) Cancels an assessment. Implemented by the partner, called by Ashby. - [customFields.fetch (Implemented by Partner)](https://developers.ashbyhq.com/reference/assessmentpartnercustomfieldsfetch.md): The API for listing custom fields that can be synced to Ashby — implemented by the assessment partner, but called by Ashby. This endpoint is optional. Ashby only calls it for integrations that have custom field sync enabled by Ashby. Contact Ashby if you wish to use this feature. Once enabled, Ashby fetches your custom field definitions in three situations, not in real time as assessments are created: - On demand, when an Ashby admin clicks "Sync Custom Fields" on the integration settings page. - When an admin opens the custom fields settings page and Ashby has no field definitions stored for the integration. - On a schedule, automatically about once an hour. Because syncing is periodic rather than per-assessment, new or changed fields on your side may take up to an hour to appear in Ashby unless an admin syncs manually. - [auditLog.list](https://developers.ashbyhq.com/reference/auditloglist.md): > **Beta** > > **This API is in active development and only available in a closed beta with early design partners.** Lists an organization's audit log entries, newest first. The `targetTypes` and `categories` you can filter on are a fixed, code-defined vocabulary; see the [Audit Log Vocabulary](/docs/audit-log-vocabulary) guide for valid values and filter examples. **Pagination:** follow opaque `cursor` / `nextCursor`; see [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync). Returns audit events for **all** objects in the organization, including confidential jobs and projects, with no confidentiality filtering. **Error codes:** | Code | Description | |---|---| | `invalid_input` | A date bound is not a valid ISO 8601 date, `endDate` is before `startDate`, the explicit span exceeds 18 months, or a `targetTypes` / `categories` value is not in the vocabulary. | | `audit_logs_not_enabled` | Your organization does not have the Audit Logs feature. | | `cursor_invalid` | The provided `cursor` could not be decoded. | | `missing_endpoint_permission` | The API key lacks the `auditLogsRead` scope. Returned with HTTP `403`. | **Requires the [`auditLogsRead`](authentication#permissions-auditloglist) permission.** - [brand.list](https://developers.ashbyhq.com/reference/brandlist.md): Lists all brands for the organization. **Requires the [`organizationRead`](authentication#permissions-brandlist) permission.** - [candidate.addTag](https://developers.ashbyhq.com/reference/candidateaddtag.md): Adds a tag to a candidate. **Requires the [`candidatesWrite`](authentication#permissions-candidateaddtag) permission.** - [candidate.anonymize](https://developers.ashbyhq.com/reference/candidateanonymize.md): Anonymizes a candidate's personally identifiable information. **Requires the [`candidatesWrite`](authentication#permissions-candidateanonymize) permission.** - [candidate.create](https://developers.ashbyhq.com/reference/candidatecreate.md): Creates a new candidate. **Requires the [`candidatesWrite`](authentication#permissions-candidatecreate) permission.** - [candidate.createNote](https://developers.ashbyhq.com/reference/candidatecreatenote.md): Creates a note on a candidate. **Requires the [`candidatesWrite`](authentication#permissions-candidatecreatenote) permission.** - [candidate.info](https://developers.ashbyhq.com/reference/candidateinfo.md): Fetches details about a single candidate by id or external mapping id. **Requires the [`candidatesRead`](authentication#permissions-candidateinfo) permission.** - [candidate.list](https://developers.ashbyhq.com/reference/candidatelist.md): Lists all candidates in the organization with pagination and incremental sync support. Use the `syncToken` parameter to retrieve only candidates updated since your last sync. Use `createdAfter` to filter candidates by creation date. **Requires the [`candidatesRead`](authentication#permissions-candidatelist) permission.** - [candidate.listClientInfo](https://developers.ashbyhq.com/reference/candidatelistclientinfo.md): Lists client information records (IP, user agent) collected for a candidate. **Requires the [`candidatesRead`](authentication#permissions-candidatelistclientinfo) permission.** - [candidate.listNotes](https://developers.ashbyhq.com/reference/candidatelistnotes.md): Lists the notes that have been added to a candidate. **Requires the [`candidatesRead`](authentication#permissions-candidatelistnotes) permission.** - [candidate.search](https://developers.ashbyhq.com/reference/candidatesearch.md): Searches for candidates by email and/or name. **Requires the [`candidatesRead`](authentication#permissions-candidatesearch) permission.** - [candidate.listProjects](https://developers.ashbyhq.com/reference/candidatelistprojects.md): Lists the projects a candidate has been added to. **Requires the [`candidatesRead`](authentication#permissions-candidatelistprojects) permission.** - [candidate.update](https://developers.ashbyhq.com/reference/candidateupdate.md): Updates an existing candidate. **Requires the [`candidatesWrite`](authentication#permissions-candidateupdate) permission.** - [candidate.uploadFile](https://developers.ashbyhq.com/reference/candidateuploadfile.md): Uploads a file for a candidate. Accepts either a multipart/form-data request with a `file` file part, or a JSON body with a `fileHandle` previously created via `file.createFileUploadHandle`. **Requires the [`candidatesWrite`](authentication#permissions-candidateuploadfile) permission.** - [candidate.uploadResume](https://developers.ashbyhq.com/reference/candidateuploadresume.md): Uploads a resume for a candidate. Accepts either a multipart/form-data request with a `resume` file part, or a JSON body with a `resumeHandle` previously created via `file.createFileUploadHandle`. **Requires the [`candidatesWrite`](authentication#permissions-candidateuploadresume) permission.** - [candidate.removeTag](https://developers.ashbyhq.com/reference/candidateremovetag.md): Removes a tag from a candidate. **Requires the [`candidatesWrite`](authentication#permissions-candidateremovetag) permission.** - [candidate.addEmailMessage](https://developers.ashbyhq.com/reference/candidateaddemailmessage.md): Attaches an existing email message (e.g. fetched from a partner provider) to a candidate. **Requires the [`candidatesWrite`](authentication#permissions-candidateaddemailmessage) permission.** - [candidate.listFraudChecks](https://developers.ashbyhq.com/reference/candidatelistfraudchecks.md): Lists the fraud checks performed on a candidate. **Requires the [`candidatesRead`](authentication#permissions-candidatelistfraudchecks) permission.** - [candidate.setFraudStatus](https://developers.ashbyhq.com/reference/candidatesetfraudstatus.md): Updates the manual fraud-review status of a candidate. **Requires the [`candidatesWrite`](authentication#permissions-candidatesetfraudstatus) permission.** - [candidate.pushToHris](https://developers.ashbyhq.com/reference/candidatepushtohris.md): > Beta > > This feature is in beta and may not be available for all organizations. Pushes a candidate's data to an HRIS system (e.g. Workday, BambooHR, ADP). This endpoint triggers the "Add Candidate Data" flow for the specified application and HRIS system. The candidate must have a name, and any offer associated with the application must be in an accepted state (for systems that require it) before pushing. If the candidate has already been pushed to the same system, the push will be retried automatically. For SelfServe integrations, `integrationPartnerId` is required. **Error codes:** | Code | Description | |---|---| | `candidate_hris_push_blocked_by_offer_status` | The candidate's offer is not in a state that permits pushing to this HRIS. | | `candidate_hris_push_failed` | The HRIS did not accept the push (e.g. a data or validation discrepancy reported by the downstream system, or a precondition it requires). The `message` includes detail about the failure (typically the error reported by the HRIS). If any of the data was already applied in the external system, verify there before retrying — this endpoint pushes with re-push enabled, so a blind retry can create a duplicate. | > Retries > > A `generic_internal_error` response does not guarantee the push did not occur — the > candidate mapping and downstream events may already have been created. Do not blindly > retry on this error; check whether the candidate was already pushed first to avoid > duplicate pushes. **Requires the [`candidatesWrite`](authentication#permissions-candidatepushtohris) permission.** - [candidate.removeProject](https://developers.ashbyhq.com/reference/candidateremoveproject-1.md): Removes the candidate from a project. **Requires the [`candidatesWrite`](authentication#permissions-candidateremoveproject) permission.** - [candidate.addProject](https://developers.ashbyhq.com/reference/candidateaddproject-1.md): Adds a candidate to a project. **Requires the [`candidatesWrite`](authentication#permissions-candidateaddproject) permission.** - [candidateTag.list](https://developers.ashbyhq.com/reference/candidatetaglist.md): Lists all candidate tags. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-candidatetaglist) permission.** - [candidateTag.archive](https://developers.ashbyhq.com/reference/candidatetagarchive.md): Archives a candidate tag. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-candidatetagarchive) permission.** - [candidateTag.create](https://developers.ashbyhq.com/reference/candidatetagcreate-1.md): Creates a candidate tag. If a tag already exists with the given title, the existing tag will be returned. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-candidatetagcreate) permission.** - [closeReason.list](https://developers.ashbyhq.com/reference/closereasonlist.md): Lists all close reasons for jobs or openings. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-closereasonlist) permission.** - [communicationTemplate.list](https://developers.ashbyhq.com/reference/communicationtemplatelist.md): List all enabled communication templates. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-communicationtemplatelist) permission.** - [customField.create](https://developers.ashbyhq.com/reference/customfieldcreate.md): Create a new custom field. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-customfieldcreate) permission.** - [customField.info](https://developers.ashbyhq.com/reference/customfieldinfo.md): Get information about a custom field. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-customfieldinfo) permission.** - [customField.list](https://developers.ashbyhq.com/reference/customfieldlist.md): Lists all custom fields. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-customfieldlist) permission.** - [customField.setValue](https://developers.ashbyhq.com/reference/customfieldsetvalue.md): Set the value of a custom field for a given object. **Note:** When updating multiple custom fields on the same object, use [`customField.setValues`](#operation/customFieldSetValues) instead to avoid race conditions. **Note:** To set custom fields on an Employee, use [`user.setCustomFieldValue`](#operation/userSetCustomFieldValue) instead. The values accepted in the `fieldValue` param depend on the type of field that's being updated. See below for more details: - Boolean - A boolean value - Date - An ISO Date string - LongText, String - String - ValueSelect - A string that matches the value of one of the ValueSelect field's options - MultiValueSelect - An array of strings that exist in the MultiValueSelect field's options - Number - A number - Currency - An object with the following properties: - value: A number - currencyCode: A valid ISO 4217 currency code - NumberRange - An object with the following properties: - type: "number-range" - minValue: A number - maxValue: A number - CompensationRange - An object with the following properties: - type: "compensation-range" - minValue: A number - maxValue: A number - currencyCode: A string - interval: A valid interval string - Url - A valid http or https URL (e.g., https://example.com) - UUID - A valid UUID string (e.g., for Employee fields) **Requires the [`candidatesWrite`](authentication#permissions-customfieldsetvalue) permission.** - [customField.setValues](https://developers.ashbyhq.com/reference/customfieldsetvalues.md): Set the values of multiple custom fields for a given object in a single call. This is the recommended approach when updating multiple fields on the same object to avoid race conditions that can occur with concurrent `customField.setValue` calls. **Note:** To set custom fields on an Employee, use [`user.setCustomFieldValues`](#operation/userSetCustomFieldValues) instead. The values accepted in the `fieldValue` param depend on the type of field that's being updated. See the [`customField.setValue`](#operation/customFieldSetValue) docs for the full per-type table. **Requires the [`candidatesWrite`](authentication#permissions-customfieldsetvalues) permission.** - [customField.updateSelectableValues](https://developers.ashbyhq.com/reference/customfieldupdateselectablevalues.md): Update the selectable values for a custom field. This endpoint merges the provided selectable values with the existing values for a custom field. **Merge behavior:** - **New values** (values not present in the existing values) are added to the field - **Existing values** (matching by `value` field) have their `label` updated and `isArchived` status set from the request - **Omitted values** (existing values not included in the request) are marked as archived - Metadata such as substitution tokens are preserved for existing values The `isArchived` field defaults to `false` if not provided. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-customfieldupdateselectablevalues) permission.** - [department.info](https://developers.ashbyhq.com/reference/departmentinfo.md): Fetch department details by id. **Requires the [`organizationRead`](authentication#permissions-departmentinfo) permission.** - [department.list](https://developers.ashbyhq.com/reference/departmentlist.md): Lists all departments. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`organizationRead`](authentication#permissions-departmentlist) permission.** - [department.archive](https://developers.ashbyhq.com/reference/departmentarchive-1.md): Archives a department. **Requires the [`organizationWrite`](authentication#permissions-departmentarchive) permission.** - [department.restore](https://developers.ashbyhq.com/reference/departmentrestore-1.md): Restores a department. **Requires the [`organizationWrite`](authentication#permissions-departmentrestore) permission.** - [department.create](https://developers.ashbyhq.com/reference/departmentcreate-1.md): Creates a department. **Requires the [`organizationWrite`](authentication#permissions-departmentcreate) permission.** - [department.move](https://developers.ashbyhq.com/reference/departmentmove-1.md): Moves a department to another parent. **Requires the [`organizationWrite`](authentication#permissions-departmentmove) permission.** - [department.update](https://developers.ashbyhq.com/reference/departmentupdate-1.md): Updates a department. **Requires the [`organizationWrite`](authentication#permissions-departmentupdate) permission.** - [feedbackFormDefinition.info](https://developers.ashbyhq.com/reference/feedbackformdefinitioninfo.md): Returns a single feedback form by id **Requires the [`hiringProcessMetadataRead`](authentication#permissions-feedbackformdefinitioninfo) permission.** - [feedbackFormDefinition.list](https://developers.ashbyhq.com/reference/feedbackformdefinitionlist.md): Lists all feedback form definitions. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-feedbackformdefinitionlist) permission.** - [file.info](https://developers.ashbyhq.com/reference/fileinfo.md): Retrieve the URL for a file referenced by a public API file handle (candidate files, resumes, offer letters, and signature-request files). **Please note** that running this with Ashby-generated demo data in an Ashby demo account can result in errors. We would recommend manually creating a test candidate in Ashby when trying out this endpoint. **Requires the [`candidatesRead`](authentication#permissions-fileinfo) permission.** - [file.createFileUploadHandle](https://developers.ashbyhq.com/reference/filecreatefileuploadhandle.md): Creates a presigned upload URL that allows uploading a file directly to storage, bypassing the need to send file bytes through the API. The presigned URL expires after 10 minutes. The fileUploadContext must be one of CandidateResume, CandidateFiles, or ApplicationForm. **Requires the [`candidatesWrite`](authentication#permissions-filecreatefileuploadhandle) permission.** - [hiringTeam.addMember](https://developers.ashbyhq.com/reference/hiringteamaddmember-1.md): Adds an Ashby user to the hiring team at the application, job, or opening level. **Requires the [`organizationWrite`](authentication#permissions-hiringteamaddmember) permission.** - [hiringTeam.removeMember](https://developers.ashbyhq.com/reference/hiringteamremovemember-1.md): Removes an Ashby user from the hiring team at the application, job, or opening level. **Requires the [`organizationWrite`](authentication#permissions-hiringteamremovemember) permission.** - [hiringTeamRole.list](https://developers.ashbyhq.com/reference/hiringteamrolelist-1.md): Lists the possible hiring team roles in an organization **Requires the [`organizationRead`](authentication#permissions-hiringteamrolelist) permission.** - [interview.info](https://developers.ashbyhq.com/reference/interviewinfo.md): Fetch interview details by id. **Requires the [`interviewsRead`](authentication#permissions-interviewinfo) permission.** - [interview.list](https://developers.ashbyhq.com/reference/interviewlist.md): List all interviews. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`interviewsRead`](authentication#permissions-interviewlist) permission.** - [interviewBriefing.info](https://developers.ashbyhq.com/reference/interviewbriefinginfo.md): Fetch the briefing data for an interview event. Returns the application, interview, per-interviewer status, and the feedback form definition id needed to render an interviewer-facing briefing or to submit feedback via [`applicationFeedback.submit`](applicationfeedbacksubmit). By default, each interviewer in the response is returned as a `userId` with status flags. Pass `expand: ["interviewers"]` to include the full user and pool details for each interviewer. Other expansions return the application, candidate, job, interview, and feedback form definition inline. **Requires the [`interviewsRead`](authentication#permissions-interviewbriefinginfo) permission.** - [interviewEvent.list](https://developers.ashbyhq.com/reference/intervieweventlist.md): Lists interview events associated with an interview schedule. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`interviewsRead`](authentication#permissions-intervieweventlist) permission.** - [interviewPlan.list](https://developers.ashbyhq.com/reference/interviewplanlist.md): List published interview plans. Draft interview plans are not returned. If `includeArchived` is true, archived interview plans are also included. Job-specific interview plans are only returned when the caller can read the associated job. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`interviewsRead`](authentication#permissions-interviewplanlist) permission.** - [interviewSchedule.cancel](https://developers.ashbyhq.com/reference/interviewschedulecancel.md): Cancel an interview schedule by id. **Requires the [`interviewsWrite`](authentication#permissions-interviewschedulecancel) permission.** - [interviewSchedule.create](https://developers.ashbyhq.com/reference/interviewschedulecreate.md): Create a scheduled interview in Ashby. **Requires the [`interviewsWrite`](authentication#permissions-interviewschedulecreate) permission.** - [interviewSchedule.list](https://developers.ashbyhq.com/reference/interviewschedulelist.md): Gets all interview schedules in the organization. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`interviewsRead`](authentication#permissions-interviewschedulelist) permission.** - [interviewSchedule.update](https://developers.ashbyhq.com/reference/interviewscheduleupdate.md): Update an interview schedule. This endpoint allows you to add, cancel, or update interview events associated with an interview schedule. In order to update an interview event on a schedule, the event's `interviewEventId` must be included when sending your request. `interviewEventId`s are included in the response of the `interviewSchedule.create` endpoint. **Requires the [`interviewsWrite`](authentication#permissions-interviewscheduleupdate) permission.** - [interviewStage.list](https://developers.ashbyhq.com/reference/interviewstagelist.md): List all interview stages for an interview plan in order. **Requires the [`interviewsRead`](authentication#permissions-interviewstagelist) permission.** - [interviewStage.info](https://developers.ashbyhq.com/reference/interviewstageinfo.md): Retrieves detailed information about a specific interview stage by its ID. **Requires the [`interviewsRead`](authentication#permissions-interviewstageinfo) permission.** - [interviewStageGroup.list](https://developers.ashbyhq.com/reference/interviewstagegrouplist.md): List all interview stage groups in the organization in order. **Requires the [`interviewsRead`](authentication#permissions-interviewstagegrouplist) permission.** - [interviewerPool.list](https://developers.ashbyhq.com/reference/interviewerpoollist.md): List all interviewer pools. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-interviewerpoollist) permission.** - [interviewerPool.info](https://developers.ashbyhq.com/reference/interviewerpoolinfo.md): Get information about an interviewer pool. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-interviewerpoolinfo) permission.** - [interviewerPool.create](https://developers.ashbyhq.com/reference/interviewerpoolcreate.md): Create an interviewer pool. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolcreate) permission.** - [interviewerPool.update](https://developers.ashbyhq.com/reference/interviewerpoolupdate.md): Update an interviewer pool. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolupdate) permission.** - [interviewerPool.archive](https://developers.ashbyhq.com/reference/interviewerpoolarchive.md): Archives an interviewer pool. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolarchive) permission.** - [interviewerPool.addUser](https://developers.ashbyhq.com/reference/interviewerpooladduser.md): Add a user to an interviewer pool. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpooladduser) permission.** - [interviewerPool.removeUser](https://developers.ashbyhq.com/reference/interviewerpoolremoveuser.md): Remove a user from an interviewer pool. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolremoveuser) permission.** - [interviewerPool.restore](https://developers.ashbyhq.com/reference/interviewerpoolrestore-1.md): Restores an archived interviewer pool. **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolrestore) permission.** - [job.create](https://developers.ashbyhq.com/reference/jobcreate.md): Creates a new job. **Requires the [`jobsWrite`](authentication#permissions-jobcreate) permission.** - [job.info](https://developers.ashbyhq.com/reference/jobinfo.md): Fetches details of a single job by id. **Requires the [`jobsRead`](authentication#permissions-jobinfo) permission.** - [job.list](https://developers.ashbyhq.com/reference/joblist.md): Lists all jobs. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`jobsRead`](authentication#permissions-joblist) permission.** - [job.setStatus](https://developers.ashbyhq.com/reference/jobsetstatus.md): Sets the status of a job. **Requires the [`jobsWrite`](authentication#permissions-jobsetstatus) permission.** - [job.update](https://developers.ashbyhq.com/reference/jobupdate.md): Updates an existing job. At least one field other than `jobId` must be supplied. **Requires the [`jobsWrite`](authentication#permissions-jobupdate) permission.** - [job.updateCompensation](https://developers.ashbyhq.com/reference/jobupdatecompensation.md): Replaces the compensation tiers on a job. Pass an empty array to clear existing compensation. **Requires the [`jobsWrite`](authentication#permissions-jobupdatecompensation) permission.** - [job.search](https://developers.ashbyhq.com/reference/jobsearch.md): Searches jobs by title or custom requisition id. At least one of `title` or `requisitionId` must be provided. **Requires the [`jobsRead`](authentication#permissions-jobsearch) permission.** - [jobBoard.list](https://developers.ashbyhq.com/reference/jobboardlist.md): List all enabled job boards. **Requires the [`jobsRead`](authentication#permissions-jobboardlist) permission.** - [jobInterviewPlan.info](https://developers.ashbyhq.com/reference/jobinterviewplaninfo-1.md): Returns a job's interview plan, including activities and interviews that need to be scheduled at each stage. **Requires the [`jobsRead`](authentication#permissions-jobinterviewplaninfo) permission.** - [jobPosting.info](https://developers.ashbyhq.com/reference/jobpostinginfo.md): Retrieve an individual job posting. Set `includeUnpublishedJobPostings` to `true` when fetching an unpublished (draft) job posting. This flag is required for draft postings; published postings can be fetched without it. Result fields: - `linkedData` - Object that can be used to populate "rich results" in search engines. [See more info here](https://developers.google.com/search/docs/data-types/job-posting). - `applicationFormDefinition` - See the guide on [Creating a custom careers page](https://developers.ashbyhq.com/docs/creating-a-custom-careers-page). **Requires the [`jobsRead`](authentication#permissions-jobpostinginfo) permission.** - [jobPosting.list](https://developers.ashbyhq.com/reference/jobpostinglist.md): Lists published job postings. By default, only published job postings are returned. Set `includeUnpublishedJobPostings` to `true` to also include unpublished (draft) job postings. **Important**: By default, this endpoint includes all listed and unlisted job postings. Unlisted job postings should not be displayed publicly. If you are using the API to publicly expose job postings, set the `listedOnly` parameter to `true` when calling this API so that you only fetch listed job postings that can be displayed publicly. **Requires the [`jobsRead`](authentication#permissions-jobpostinglist) permission.** - [jobPosting.update](https://developers.ashbyhq.com/reference/jobpostingupdate.md): Updates an existing job posting. Set `includeUnpublishedJobPostings` to `true` when updating an unpublished (draft) job posting. This flag is required for draft postings; published postings can be updated without it. **Note on updating the description**: When job description openings and closings are not suppressed, the `descriptionHtml` field returned in `jobPosting.info` may contain content that is not modifiable through the API. Only the content of the `descriptionParts.descriptionBody` field of the `jobPosting.info` endpoint is modifiable through this call. To completely customize the description, set both suppressDescriptionOpening and suppressDescriptionClosing to true. **Requires the [`jobsWrite`](authentication#permissions-jobpostingupdate) permission.** - [jobPosting.updateCompensation](https://developers.ashbyhq.com/reference/jobpostingupdatecompensation.md): Updates compensation for an existing job posting. Set `includeUnpublishedJobPostings` to `true` when updating an unpublished (draft) job posting. This flag is required for draft postings; published postings can be updated without it. Pass a non-empty `compensationTiers` array to replace the posting's compensation and stop inheriting compensation from the parent job. Pass `null` to reset the posting to inherit compensation from the parent job. **Requires the [`jobsWrite`](authentication#permissions-jobpostingupdatecompensation) permission.** - [jobTemplate.list](https://developers.ashbyhq.com/reference/jobtemplatelist.md): List all active and inactive job templates. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`jobsRead`](authentication#permissions-jobtemplatelist) permission.** - [location.info](https://developers.ashbyhq.com/reference/locationinfo.md): Gets details for a single location by id. **Requires the [`organizationRead`](authentication#permissions-locationinfo) permission.** - [location.archive](https://developers.ashbyhq.com/reference/locationarchive-1.md): Archives a location or location hierarchy. **Requires the [`organizationWrite`](authentication#permissions-locationarchive) permission.** - [location.create](https://developers.ashbyhq.com/reference/locationcreate-1.md): Creates a location or location hierarchy. **Requires the [`organizationWrite`](authentication#permissions-locationcreate) permission.** - [location.restore](https://developers.ashbyhq.com/reference/locationrestore-1.md): Restores an archived location or location hierarchy. **Requires the [`organizationWrite`](authentication#permissions-locationrestore) permission.** - [location.list](https://developers.ashbyhq.com/reference/locationlist-1.md): List all locations. Regions are not returned. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`organizationRead`](authentication#permissions-locationlist) permission.** - [location.move](https://developers.ashbyhq.com/reference/locationmove-1.md): Moves a location in location hierarchy. **Requires the [`organizationWrite`](authentication#permissions-locationmove) permission.** - [location.updateAddress](https://developers.ashbyhq.com/reference/locationupdateaddress-1.md): Update an address of a location or location hierarchy. **Requires the [`organizationWrite`](authentication#permissions-locationupdateaddress) permission.** - [location.updateName](https://developers.ashbyhq.com/reference/locationupdatename-1.md): Update location's name. **Requires the [`organizationWrite`](authentication#permissions-locationupdatename) permission.** - [location.updateWorkplaceType](https://developers.ashbyhq.com/reference/locationupdateworkplacetype-1.md): Update location's workplace type. **Requires the [`organizationWrite`](authentication#permissions-locationupdateworkplacetype) permission.** - [location.updateExternalName](https://developers.ashbyhq.com/reference/locationupdateexternalname-1.md): Update a location's external (candidate-facing) name. **Requires the [`organizationWrite`](authentication#permissions-locationupdateexternalname) permission.** - [notetakerTranscript.info](https://developers.ashbyhq.com/reference/notetakertranscriptinfo.md): Fetches metadata and a pre-signed download URL for an AI Notetaker transcript recording. **Prerequisites:** - Your organization must have the **AI Notetaker add-on**. If your organization does not have the add-on, requests will fail with the `notetaker_transcript_not_enabled` error. The response includes a signed URL with the transcript JSON. Download the file promptly after calling this endpoint. If the URL has expired, call the endpoint again to get a fresh one. On the free tier, transcripts expire after a retention period. Requesting an expired transcript returns the `notetaker_transcript_expired` error. Organizations with unlimited AI Notetaker access are not subject to this expiry. Use the `notetakerTranscriptId` field from [`interviewEvent.list`](ref:intervieweventlist) or [`interviewSchedule.list`](ref:interviewschedulelist) to discover transcript IDs for interview events. **Error codes:** | Code | Description | |---|---| | `notetaker_transcript_not_enabled` | Your organization does not have the AI Notetaker add-on. | | `notetaker_transcript_not_found` | No transcript exists with the given ID, or you do not have access to it. | | `notetaker_transcript_expired` | The transcript has expired. Upgrade to unlimited AI Notetaker to retain transcripts indefinitely. | | `invalid_input` | The provided `notetakerTranscriptId` is not a valid UUID. | Configure API key permissions in **Admin → API Keys**. See [Managing API Key Permissions](authentication#managing-api-key-permissions). **Requires the [`notetakerRead`](authentication#permissions-notetakertranscriptinfo) permission.** - [offer.create](https://developers.ashbyhq.com/reference/offercreate.md): Creates a new Offer Offer forms support a variety of field types. The values accepted for each field depend on the type of field that's being filled out: - `Boolean` - A boolean value. - `Currency` - An object in the format `{ currencyCode: "USD", value: 100000 }` where currencyCode is a valid ISO 4217 currency code and value is an integer. - `Date` - A valid ISO Date string. - `Number` - An integer. - `String` - A string. - `ValueSelect` - A string that matches the value of one of the ValueSelect field's selectable options. - `MultiValueSelect` - An array of strings that exist in the MultiValueSelect field's selectable options. **Error codes:** | Code | Description | |---|---| | `opening_in_use` | The opening is already in use by another offer. | | `opening_state_invalid` | The opening has already been closed or filled by a different application.. | **Requires the [`offersWrite`](authentication#permissions-offercreate) permission.** - [offer.approve](https://developers.ashbyhq.com/reference/offerapprove.md): Approves an offer or a specific approval step within an offer's approval process. This endpoint mimics the behavior of the "Force Approve" function in the Ashby app, where an admin can override approval for a specific step or entire approval process. This endpoint can be used in two ways: 1. **Approve entire offer**: Call without `approvalStepId` and `userId` to approve the entire offer approval process 2. **Approve specific step**: Provide both `approvalStepId` and `userId` to approve a specific step in the approval process When approving a specific step, the step must be the current step in the approval process and the user must be an approver for that step. **Requires the [`offersWrite`](authentication#permissions-offerapprove) permission.** - [offer.info](https://developers.ashbyhq.com/reference/offerinfo.md): Returns details about a single offer by id **Requires the [`offersRead`](authentication#permissions-offerinfo) permission.** - [offer.list](https://developers.ashbyhq.com/reference/offerlist.md): Get a list of all offers with their latest version. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`offersRead`](authentication#permissions-offerlist) permission.** - [offer.start](https://developers.ashbyhq.com/reference/offerstart.md): The offer.start endpoint creates and returns an offer version instance that can be filled out and submitted using the `offer.create` endpoint. In order to create a new offer version for a candidate with an in-progress offer process, you can call the `offer.start` endpoint and then call the `offer.create` endpoint to fill out the newly created offer version form. **Requires the [`offersWrite`](authentication#permissions-offerstart) permission.** - [offer.update](https://developers.ashbyhq.com/reference/offerupdate.md): Updates an existing Offer Offer forms support a variety of field types. The values accepted for each field depend on the type of field that's being filled out: - `Boolean` - A boolean value. - `Currency` - An object in the format `{ currencyCode: "USD", value: 100000 }` where currencyCode is a valid ISO 4217 currency code and value is an integer. - `Date` - A valid ISO Date string. - `Number` - An integer. - `String` - A string. - `ValueSelect` - A string that matches the value of one of the ValueSelect field's selectable options. - `MultiValueSelect` - An array of strings that exist in the MultiValueSelect field's selectable options. Calling this endpoint will create a new version of the offer and retrigger any necessary approval steps. **Requires the [`offersWrite`](authentication#permissions-offerupdate) permission.** - [offer.startApprovalProcess](https://developers.ashbyhq.com/reference/offerstartapprovalprocess.md): Starts the approval process for an offer in a "WaitingOnApprovalStart" state. Once started, the approval is sent to the configured approvers. The offer version ID can be obtained from the offer (e.g. `offer.info` or `offer.list` response's `latestVersion.id`). **Requires the [`offersWrite`](authentication#permissions-offerstartapprovalprocess) permission.** - [offer.setStatus](https://developers.ashbyhq.com/reference/offersetstatus.md): Updates an offer's acceptance status. Ashby derives the offer status from the provided acceptance status; `offerStatus` can't be set independently. **Requires the [`offersWrite`](authentication#permissions-offersetstatus) permission.** - [offer.setDecidedAt](https://developers.ashbyhq.com/reference/offersetdecidedat.md): Updates an offer's decidedAt timestamp. **Requires the [`offersWrite`](authentication#permissions-offersetdecidedat) permission.** - [offerProcess.start](https://developers.ashbyhq.com/reference/offerprocessstart-1.md): Starts an offer process for a candidate. **Requires the [`offersWrite`](authentication#permissions-offerprocessstart) permission.** - [opening.info](https://developers.ashbyhq.com/reference/openinginfo-1.md): Retrieves an opening by its UUID. **Requires the [`jobsRead`](authentication#permissions-openinginfo) permission.** - [opening.create](https://developers.ashbyhq.com/reference/openingcreate-1.md): Creates an opening. To set values of custom fields on Openings, use the [`customField.setValue`](ref:customfieldsetvalue) endpoint. **Requires the [`jobsWrite`](authentication#permissions-openingcreate) permission.** - [opening.update](https://developers.ashbyhq.com/reference/openingupdate-1.md): Updates an opening. To set values for custom fields on Openings, use the [`customField.setValue`](ref:customfieldsetvalue) endpoint. **Requires the [`jobsWrite`](authentication#permissions-openingupdate) permission.** - [opening.setArchived](https://developers.ashbyhq.com/reference/openingsetarchived-1.md): Sets the archived state of an opening. **Requires the [`jobsWrite`](authentication#permissions-openingsetarchived) permission.** - [opening.setOpeningState](https://developers.ashbyhq.com/reference/openingsetopeningstate-1.md): Sets the state of an opening. **Requires the [`jobsWrite`](authentication#permissions-openingsetopeningstate) permission.** - [opening.addJob](https://developers.ashbyhq.com/reference/openingaddjob-1.md): Adds a job to an opening. **Requires the [`jobsWrite`](authentication#permissions-openingaddjob) permission.** - [opening.removeJob](https://developers.ashbyhq.com/reference/openingremovejob-1.md): Removes a job from an opening. **Requires the [`jobsWrite`](authentication#permissions-openingremovejob) permission.** - [opening.addLocation](https://developers.ashbyhq.com/reference/openingaddlocation-1.md): Adds a location to an opening. **Requires the [`jobsWrite`](authentication#permissions-openingaddlocation) permission.** - [opening.removeLocation](https://developers.ashbyhq.com/reference/openingremovelocation-1.md): Removes a location from an opening. **Requires the [`jobsWrite`](authentication#permissions-openingremovelocation) permission.** - [opening.list](https://developers.ashbyhq.com/reference/openinglist-1.md): Lists openings. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`jobsRead`](authentication#permissions-openinglist) permission.** - [opening.search](https://developers.ashbyhq.com/reference/openingsearch-1.md): Searches for openings by identifier. **Requires the [`jobsRead`](authentication#permissions-openingsearch) permission.** - [project.search](https://developers.ashbyhq.com/reference/projectsearch.md): Search for projects by title. Responses are limited to 100 results. Consider refining your search or using /project.list to paginate through all projects, if you approach this limit. This API is for use cases where you intend to operate on a final small set of projects, like building a project autocomplete. **Requires the [`candidatesRead`](authentication#permissions-projectsearch) permission.** - [project.info](https://developers.ashbyhq.com/reference/projectinfo-1.md): Retrieves a project by its UUID. **Requires the [`candidatesRead`](authentication#permissions-projectinfo) permission.** - [project.list](https://developers.ashbyhq.com/reference/projectlist-1.md): Lists projects. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`candidatesRead`](authentication#permissions-projectlist) permission.** - [referral.create](https://developers.ashbyhq.com/reference/referralcreate.md): Creates a referral **Requires the [`candidatesWrite`](authentication#permissions-referralcreate) permission.** - [referralForm.info](https://developers.ashbyhq.com/reference/referralforminfo.md): Fetches the default referral form or creates a default referral form if none exists. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-referralforminfo) permission.** - [report.generate](https://developers.ashbyhq.com/reference/reportgenerate.md): > Beta > > This endpoint is currently in beta and may change without notice. Generates a new report or polls the status of an existing report generation. **Two-step process:** 1. Call with only `reportId` to start generation and receive a `requestId`. 2. Poll with both `reportId` and `requestId` every second until `status` is `complete` or `failed`. **Rate Limiting (Per Organization):** - **Start generation requests** (without `requestId`): 15 requests per minute per organization. - **Concurrent limit**: Maximum 3 report operations at once per organization (shared with `report.synchronous`). - **Polling requests** (with `requestId`): Bypass all limits. **Usage Notes:** - If you receive a 429 error, your organization has hit its limit. Wait and retry or use `report.synchronous`. - For synchronous retrieval of existing data, use `report.synchronous`. - Use this async endpoint for reports that may exceed 30 seconds. **Requires the [`reportsRead`](authentication#permissions-reportgenerate) permission.** - [report.synchronous](https://developers.ashbyhq.com/reference/reportsynchronous.md): > Beta > > This endpoint is currently in beta and may change without notice. Retrieves report data synchronously. **Timeout:** 30 seconds. If a report is timing out, use the asynchronous `report.generate` instead. **Rate Limiting (Per Organization):** - **Request limit**: 15 requests per minute per organization. - **Concurrent limit**: Maximum 3 report operations at once per organization (shared with `report.generate`). - Rate limits are shared with `report.generate` for starting new generations. **Usage Notes:** - If you receive a 429 error, your organization has hit its limit - wait briefly and retry. - For long-running reports, use `report.generate` for async processing. - Concurrent limit is released when the HTTP request completes. **Requires the [`reportsRead`](authentication#permissions-reportsynchronous) permission.** - [sequence.cancel](https://developers.ashbyhq.com/reference/sequencecancel.md): Cancels a running sourcing sequence (campaign) for a candidate. **Requires the [`candidatesWrite`](authentication#permissions-sequencecancel) permission.** - [sequenceTemplate.info](https://developers.ashbyhq.com/reference/sequencetemplateinfo.md): Retrieves metadata for a reusable sourcing sequence template visible to the caller. Archived templates may be returned. Message subjects and bodies are not exposed. Returns sequence_template_not_found when the template does not exist, is not a reusable sourcing template, or is not visible to the caller. **Requires the [`sourcingRead`](authentication#permissions-sequencetemplateinfo) permission.** - [sequenceTemplate.list](https://developers.ashbyhq.com/reference/sequencetemplatelist.md): Lists reusable sourcing sequence templates visible to the caller. Returns template and cadence metadata only; message subjects and bodies are not exposed. Archived templates are excluded unless the includeArchived option is true. Use that option when maintaining a complete synchronized catalog. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`sourcingRead`](authentication#permissions-sequencetemplatelist) permission.** - [source.list](https://developers.ashbyhq.com/reference/sourcelist-1.md): List all sources **Requires the [`hiringProcessMetadataRead`](authentication#permissions-sourcelist) permission.** - [sourceTrackingLink.list](https://developers.ashbyhq.com/reference/sourcetrackinglinklist-1.md): List all source custom tracking links **Requires the [`hiringProcessMetadataRead`](authentication#permissions-sourcetrackinglinklist) permission.** - [surveyFormDefinition.info](https://developers.ashbyhq.com/reference/surveyformdefinitioninfo.md): Returns details about a single survey form definition by id. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-surveyformdefinitioninfo) permission.** - [surveyFormDefinition.list](https://developers.ashbyhq.com/reference/surveyformdefinitionlist.md): Lists all survey form definitions. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`hiringProcessMetadataRead`](authentication#permissions-surveyformdefinitionlist) permission.** - [surveyRequest.create](https://developers.ashbyhq.com/reference/surveyrequestcreate.md): This endpoint generates a survey request and returns a survey URL. You can send this URL to a candidate to allow them to complete a survey. **Note that calling this endpoint will not automatically email the survey to the candidate.** It simply creates the request and gives you a URL to share with a candidate. **Requires the [`candidatesWrite`](authentication#permissions-surveyrequestcreate) permission.** - [surveyRequest.list](https://developers.ashbyhq.com/reference/surveyrequestlist.md): Lists all survey requests. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`candidatesRead`](authentication#permissions-surveyrequestlist) permission.** - [surveySubmission.create](https://developers.ashbyhq.com/reference/surveysubmissioncreate.md): Creates a survey submission for a candidate and application. **Requires the [`candidatesWrite`](authentication#permissions-surveysubmissioncreate) permission.** - [surveySubmission.list](https://developers.ashbyhq.com/reference/surveysubmissionlist.md): Lists all survey submissions of a given `surveyType`. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`candidatesRead`](authentication#permissions-surveysubmissionlist) permission.** - [takeHomeAssignment.list](https://developers.ashbyhq.com/reference/takehomeassignmentlist.md): > Beta > > This endpoint is in beta and may not be available for all organizations. Lists take-home assignments visible to the caller, including candidate submission metadata and reviewer feedback status, and links each assignment to its interview definition through `interviewId`. Pass `expand: ["interview"]` to include that definition. See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples. **Requires the [`interviewsRead`](authentication#permissions-takehomeassignmentlist) permission.** - [takeHomeAssignment.info](https://developers.ashbyhq.com/reference/takehomeassignmentinfo.md): > Beta > > This endpoint is in beta and may not be available for all organizations. Retrieves a single take-home assignment by id and links it to its interview definition through `interviewId`. Pass `expand: ["interview"]` to include that definition. Returns `take_home_assignment_not_found` if the id does not exist or is not visible to the caller. **Requires the [`interviewsRead`](authentication#permissions-takehomeassignmentinfo) permission.** - [user.info](https://developers.ashbyhq.com/reference/userinfo.md): Retrieves detailed information about a specific user by their ID. **Requires the [`organizationRead`](authentication#permissions-userinfo) permission.** - [user.list](https://developers.ashbyhq.com/reference/userlist.md): Lists all users in the organization with pagination support. By default, only active (enabled) users are returned. Use `includeDeactivated: true` to include deactivated users. Supports incremental sync via `syncToken` to efficiently retrieve only users updated since the last sync. **Requires the [`organizationRead`](authentication#permissions-userlist) permission.** - [user.search](https://developers.ashbyhq.com/reference/usersearch.md): Searches for users by email address. Returns an array containing the user if found, or an empty array if no user with the given email exists. **Requires the [`organizationRead`](authentication#permissions-usersearch) permission.** - [user.interviewerSettings](https://developers.ashbyhq.com/reference/userinterviewersettings.md): Get interviewer settings for a user. **Requires the [`organizationRead`](authentication#permissions-userinterviewersettings) permission.** - [user.updateInterviewerSettings](https://developers.ashbyhq.com/reference/userupdateinterviewersettings.md): Update interviewer settings for a user. Either limit can be provided, or both can be provided. If only one is provided, the other will remain unchanged. If a limit is provided but set to null, it will be unset. **Requires the [`organizationWrite`](authentication#permissions-userupdateinterviewersettings) permission.** - [user.createInterviewerPause](https://developers.ashbyhq.com/reference/usercreateinterviewerpause.md): Creates an interviewer pause for a user. While paused, the user will not be scheduled for interviews. A user can only have one interviewer pause at a time (whether active or scheduled). Attempting to create a pause when one already exists will return an error. **Requires the [`organizationWrite`](authentication#permissions-usercreateinterviewerpause) permission.** - [user.listInterviewerPauses](https://developers.ashbyhq.com/reference/userlistinterviewerpauses.md): Lists all active or scheduled interviewer pauses for a user. **Requires the [`organizationRead`](authentication#permissions-userlistinterviewerpauses) permission.** - [user.deleteInterviewerPause](https://developers.ashbyhq.com/reference/userdeleteinterviewerpause.md): Deletes an interviewer pause. **Requires the [`organizationWrite`](authentication#permissions-userdeleteinterviewerpause) permission.** - [user.setCustomFieldValue](https://developers.ashbyhq.com/reference/usersetcustomfieldvalue.md): Set the value of a custom field on an employee. The values accepted in the `fieldValue` param depend on the type of field being updated. See the [customField.setValue](https://developers.ashbyhq.com/reference/customfieldsetvalue) docs for accepted types. **Note:** When updating multiple custom fields on the same employee, use [`user.setCustomFieldValues`](#operation/userSetCustomFieldValues) instead to avoid race conditions. **Requires the [`organizationWrite`](authentication#permissions-usersetcustomfieldvalue) permission.** - [user.setCustomFieldValues](https://developers.ashbyhq.com/reference/usersetcustomfieldvalues.md): Set the values of multiple custom fields on an employee in a single call. This is the recommended approach when updating multiple fields on the same employee to avoid race conditions that can occur with concurrent `user.setCustomFieldValue` calls. The values accepted in the `fieldValue` param depend on the type of field being updated. See the [customField.setValue](https://developers.ashbyhq.com/reference/customfieldsetvalue) docs for accepted types. **Requires the [`organizationWrite`](authentication#permissions-usersetcustomfieldvalues) permission.** - [webhook.info](https://developers.ashbyhq.com/reference/webhookinfo.md): Retrieves information about a specific webhook setting by its ID. **Requires the [`apiKeysRead`](authentication#permissions-webhookinfo) permission.** - [webhook.create](https://developers.ashbyhq.com/reference/webhookcreate-1.md): Creates a webhook setting. **Requires the [`apiKeysWrite`](authentication#permissions-webhookcreate) permission.** - [webhook.update](https://developers.ashbyhq.com/reference/webhookupdate-1.md): Updates a webhook setting. One of `enabled`, `requestUrl`, or `secretToken` must be provided. **Requires the [`apiKeysWrite`](authentication#permissions-webhookupdate) permission.** - [webhook.delete](https://developers.ashbyhq.com/reference/webhookdelete-1.md): Deletes a webhook setting. **Requires the [`apiKeysWrite`](authentication#permissions-webhookdelete) permission.** - [applicationSubmit](https://developers.ashbyhq.com/reference/applicationsubmitwebhook.md): Triggered when a candidate submits an application or when a candidate is manually added to Ashby. This webhook is not triggered for bulk imports or integration syncs. - [applicationUpdate](https://developers.ashbyhq.com/reference/applicationupdatewebhook.md): Triggered when there's an update to an application. This includes: - Changes to application fields (source, custom fields, etc.) - Job transfers (when an application is moved to a different job) - Also triggered by [candidateHire](ref:candidatehirewebhook) and [candidateStageChange](ref:candidatestagechangewebhook) - [candidateHire](https://developers.ashbyhq.com/reference/candidatehirewebhook.md): Triggered when a candidate is hired (including candidates that are hired on confidential jobs). Includes the application and most recent accepted offer (if one exists). Also triggers [applicationUpdate](ref:applicationupdatewebhook) and [candidateStageChange](ref:candidatestagechangewebhook) - [candidateStageChange](https://developers.ashbyhq.com/reference/candidatestagechangewebhook.md): Triggered when a candidate changes stages in an application. Also triggered by [candidateHire](ref:candidatehirewebhook) - [candidateDelete](https://developers.ashbyhq.com/reference/candidatedeletewebhook.md): Triggered when a candidate is deleted. Includes the deleted candidate id. - [candidateMerge](https://developers.ashbyhq.com/reference/candidatemergewebhook.md): Triggered when a candidate is merged. Includes the deleted candidate's id and merged candidate data. - [interviewPlanTransition](https://developers.ashbyhq.com/reference/interviewplantransitionwebhook.md): Triggered when a job's interview plan is switched to a different plan. Sends interview plan data and ids for the interview stage mappings. Also triggers [jobUpdate](ref:jobupdatewebhook) - [interviewScheduleCreate](https://developers.ashbyhq.com/reference/interviewschedulecreatewebhook.md): The webhook is called when an interview schedule is created. Also triggers [interviewScheduleUpdate](ref:interviewscheduleupdatewebhook) - [interviewScheduleUpdate](https://developers.ashbyhq.com/reference/interviewscheduleupdatewebhook.md): The webhook is called when an interview schedule is updated, including when interviews that are part of the schedule are scheduled, updated, or cancelled. Also triggered by [interviewScheduleCreate](ref:interviewschedulecreatewebhook) - [jobCreate](https://developers.ashbyhq.com/reference/jobcreatewebhook.md): Triggered when a job is created - [jobUpdate](https://developers.ashbyhq.com/reference/jobupdatewebhook.md): Triggered when a job is updated. Also triggered by [interviewPlanTransition](ref:interviewplantransitionwebhook) - [jobPostingUpdate](https://developers.ashbyhq.com/reference/jobpostingupdatewebhook.md): Triggered when a job posting is updated. Also triggered by [jobPostingPublish](ref:jobpostingpublishwebhook) and [jobPostingUnpublish](ref:jobpostingunpublishwebhook) - [jobPostingPublish](https://developers.ashbyhq.com/reference/jobpostingpublishwebhook.md): Triggered when a job posting is published. Also triggers [jobPostingUpdate](ref:jobpostingupdatewebhook) - [jobPostingUnpublish](https://developers.ashbyhq.com/reference/jobpostingunpublishwebhook.md): Triggered when a job posting is unpublished. Also triggers [jobPostingUpdate](ref:jobpostingupdatewebhook) - [offerCreate](https://developers.ashbyhq.com/reference/offercreatewebhook.md): Triggered when a new offer process is created for a candidate - [offerDelete](https://developers.ashbyhq.com/reference/offerdeletewebhook.md): Triggered when an offer process is deleted - [offerUpdate](https://developers.ashbyhq.com/reference/offerupdatewebhook.md): Triggered when an offer is updated - [openingCreate](https://developers.ashbyhq.com/reference/openingcreatewebhook.md): Triggered when a opening is created - [pushToHRIS](https://developers.ashbyhq.com/reference/pushtohriswebhook.md): Triggered when a candidate is pushed to an HRIS system - [ping](https://developers.ashbyhq.com/reference/pingwebhook.md): Called to check that the webhook URL is live - [surveySubmit](https://developers.ashbyhq.com/reference/surveysubmitwebhook.md): The webhook is triggered when a candidate submits a non-anonymous survey. It will not fire for anonymous survey submissions. Depending on the type of survey that was submitted, survey responses may be included in the webhook payload: - **Questionnaires**, **Candidate Data Consent** - Survey responses will be included in the payload. - **Candidate Experience** - If the submission is not anonymous, survey responses will be included in the payload. If the submission is anonymous, the webhook will not trigger. - **Diversity Surveys**, **EEOC Surveys** - Survey responses will never be included in the payload. If survey responses are included in the payload, the `submittedValues` field will contain the submitted answers in an object where each key is the path of the field and the value is the value submitted for that field. - [signatureRequestUpdate](https://developers.ashbyhq.com/reference/signaturerequestupdatewebhook.md): Triggered on updates to requests for e-signatures: when requests are sent, cancelled, completed, or deleted. Depending on the type of request, additional context will be included in the webhook payload: - **Offers** - `"relatedEntityType"` is `"offer"` and `"offerId"` is included. - **Applications** - `"relatedEntityType"` is `"application"` and `"applicationId"` is included. - [jobPostingDelete](https://developers.ashbyhq.com/reference/jobpostingdeletewebhook.md): Triggered when a job posting is deleted. Includes the deleted job posting id and its associated job id. - [takeHomeAssignmentAssigned](https://developers.ashbyhq.com/reference/takehomeassignmentassignedwebhook.md): > Beta: This webhook may not be available for all organizations. The webhook is called when a take-home assignment enters Waiting On Submission. - [takeHomeAssignmentCancelled](https://developers.ashbyhq.com/reference/takehomeassignmentcancelledwebhook.md): > Beta: This webhook may not be available for all organizations. The webhook is called when a take-home assignment is cancelled. - [takeHomeAssignmentCompleted](https://developers.ashbyhq.com/reference/takehomeassignmentcompletedwebhook.md): > Beta: This webhook may not be available for all organizations. The webhook is called when a take-home assignment is completed. - [takeHomeAssignmentSubmitted](https://developers.ashbyhq.com/reference/takehomeassignmentsubmittedwebhook.md): > Beta: This webhook may not be available for all organizations. The webhook is called when a candidate submits a take-home assignment and it enters Waiting On Feedback. ## Changelog - [Add createdBefore Filter to Candidate and Application List Endpoints](https://developers.ashbyhq.com/changelog/2026-07-09-add-created-before-filter-to-list-endpoints.md) - [Return Take-Home Submission File Details](https://developers.ashbyhq.com/changelog/2026-07-17-return-take-home-submission-files.md) - [Include Non-Shared Take Homes in Interview List](https://developers.ashbyhq.com/changelog/2026-07-16-include-non-shared-take-homes-in-interview-list.md) - [Add Sequence Template Discovery](https://developers.ashbyhq.com/changelog/2026-07-14-add-sequence-template-discovery.md) - [Link Take-Home Assignments to Interviews](https://developers.ashbyhq.com/changelog/2026-07-15-link-take-home-assignments-to-interviews.md)