# Ashby Documentation

## Guides
- [Authentication](https://developers.ashbyhq.com/docs/authentication.md)
- [Endpoint Naming](https://developers.ashbyhq.com/docs/endpoint-naming.md)
- [Expansions](https://developers.ashbyhq.com/docs/expansions.md)
- [Introduction](https://developers.ashbyhq.com/docs/introduction.md)
- [Pagination](https://developers.ashbyhq.com/docs/pagination.md)
- [Responses & Errors](https://developers.ashbyhq.com/docs/responses.md)
- [Support](https://developers.ashbyhq.com/docs/support.md)
- [Syncing Records](https://developers.ashbyhq.com/docs/sync.md)
- [Creating a Custom Careers Page](https://developers.ashbyhq.com/docs/creating-a-custom-careers-page.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
- [Dedicated Partner Job Feeds](https://developers.ashbyhq.com/docs/dedicated-partner-job-feeds.md)
- [Getting Started with Ashby](https://developers.ashbyhq.com/docs/getting-started.md)
- [Pagination and Incremental Synchronization](https://developers.ashbyhq.com/docs/pagination-and-incremental-sync.md)
- [Ashby Job Postings API](https://developers.ashbyhq.com/docs/public-job-posting-api.md)
- [Authenticating Webhooks](https://developers.ashbyhq.com/docs/authenticating-webhooks.md)
- [Common Payload Data](https://developers.ashbyhq.com/docs/common-payload-data.md)
- [Related Webhooks](https://developers.ashbyhq.com/docs/related-webhooks.md)
- [Retries](https://developers.ashbyhq.com/docs/retries.md)
- [Setting up Webhooks](https://developers.ashbyhq.com/docs/setting-up-webhooks.md)

## API Reference
- [apiKey.info](https://developers.ashbyhq.com/reference/apikeyinfo.md): Retrieve information about the API key being used to make the request.  **Requires the [`apiKeysRead`](authentication#permissions-apikeyinfo) 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 (e.g., "Strong Hire" for overall recommendation) - **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.md): Application feedback forms support a variety of field types.   **Requires the [`candidatesWrite`](authentication#permissions-applicationfeedbacksubmit) permission.**  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: "<uuid>" }` - `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.
- [applicationFeedbackRequest.create](https://developers.ashbyhq.com/reference/applicationfeedbackrequestcreate.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.md): Submit an application for a job posting.  **Requires the [`candidatesWrite`](authentication#permissions-applicationformsubmit) permission.**  The Content-Type of this request must be `multipart/form-data` or `application/json`.  When using `application/json`, file fields should contain a handle string obtained from [`file.createFileUploadHandle`](https://developers.ashbyhq.com/reference/filecreatefileuploadhandle) with `fileUploadContext` set to `ApplicationForm`. This allows files to be uploaded directly to storage, bypassing the need to send file bytes through the API.  When using `multipart/form-data`, file fields should reference a file part included in the multipart request body (existing behavior).  **Important:** Please ensure that you check the response's `success` field and display any validation errors to candidates if it is `false`. Not doing so will result in applications not being recorded, without any notification to the candidate prompting them to resubmit. For testing purposes, you can simulate a validation failure by submitting the email address `testing-fail-validation@example.com`.  **Note: The requests generated from this documentation will not work for this endpoint.**  The values accepted for each field depend on the type of field that's being filled out: - `Boolean` - A boolean value - `Date` - A date string in the format YYYY-MM-DD - `Email` - A valid email address - `Number` - An integer - `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 }` - `Phone`, `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 - `Location` - An object with the following properties: `{ country: "USA", city: "San Francisco", region: "California" }`. You may provide any combination of these properties and we will attempt to geocode the location. For best results, provide all three properties. - `EducationHistory` - [Early Access] An array of objects with the following properties: `{ schoolName: "University of California, Berkeley", degree: "Bachelor of Science", major: "Computer Science", startDate: "2020-09-01", endDate: "2024-05-15", isCurrent: true }`. Only `schoolName` is required. We will attempt to match the school name to a known school in our database. If `isCurrent` is true, `endDate` must not be provided.
- [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.**
- [application.addHiringTeamMember](https://developers.ashbyhq.com/reference/applicationaddhiringteammember.md): Adds an Ashby user to the hiring team at the application level.   **Requires the [`candidateWrite`](authentication#permissions-applicationaddhiringteammember) permission.**
- [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 (eg 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.  **Requires the [`candidatesWrite`](authentication#permissions-applicationcreate) permission.**  To set values for custom fields on Applications, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
- [application.info](https://developers.ashbyhq.com/reference/applicationinfo.md): Fetch application details by application id or by submitted form instance id (which is return by the `applicationForm.submit` endpoint). If both applicationId and submittedFormInstanceId are provided, we will lookup by 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.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.  **Requires the [`candidatesRead`](authentication#permissions-applicationListCriteriaEvaluations) permission.**  **Note:** This endpoint requires the AI Application Review feature to be enabled for your organization.
- [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.removeHiringTeamMember](https://developers.ashbyhq.com/reference/applicationremovehiringteammember.md): Removes an Ashby user to the hiring team at the application level.   **Requires the [`candidateWrite`](authentication#permissions-applicationremovehiringteammember) 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  **Requires the [`candidatesWrite`](authentication#permissions-applicationupdate) permission.**  To set values for custom fields on Applications, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
- [application.updateHistory](https://developers.ashbyhq.com/reference/applicationupdatehistory.md): Update the history of an application. This endpoint is used to update the history of an application, such as setting the entered stage time or deleting a history event.  **Requires the [`candidatesWrite`](authentication#permissions-applicationupdatehistory) permission and the `Allow updating application history?` setting found in your admin API key permissions configuration.**
- [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.**
- [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.**
- [archiveReason.list](https://developers.ashbyhq.com/reference/archivereasonlist.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.cancel (Implemented by Partner)](https://developers.ashbyhq.com/reference/assessmentcancel.md): (Optional) Cancels 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
- [customField.list (Implemented by Partner)](https://developers.ashbyhq.com/reference/assessmentpartnercustomfieldlist.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 and must be enabled for your integration. Contact Ashby if you wish to use this feature.
- [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.update](https://developers.ashbyhq.com/reference/assessmentupdate.md): Update Ashby about the status of a started assessment.  **Requires the [`candidatesWrite`](authentication#permissions-assessmentupdate) permission.**  `assessment_status` is required unless `cancelled_reason` is provided.
- [Authentication](https://developers.ashbyhq.com/reference/authentication.md)
- [brand.list](https://developers.ashbyhq.com/reference/brandlist.md): Lists all brands for the organization.  **Requires the [`organizationRead`](authentication#permissions-departmentinfo) 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.md): Creates a candidate tag.  **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-candidatetagcreate) 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.**
- [candidate.addEmailMessage](https://developers.ashbyhq.com/reference/candidateaddemailmessage.md): Adds an email message to a candidate's profile.  **Requires the [`candidatesWrite`](authentication#permissions-candidateaddemailmessage) permission.**
- [candidate.addProject](https://developers.ashbyhq.com/reference/candidateaddproject.md): Adds the candidate to a project.  **Requires the [`candidatesWrite`](authentication#permissions-candidateaddproject) 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.  **Requires the [`candidatesWrite`](authentication#permissions-candidateanonymize) permission.**  **Note**: this action cannot be reversed and requires all of a candidate's applications to be in the archived or hired state.
- [candidate.create](https://developers.ashbyhq.com/reference/candidatecreate.md): Creates a new candidate  **Requires the [`candidatesWrite`](authentication#permissions-candidatecreate) permission.**  To set values for custom fields on Candidates, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
- [candidate.createNote](https://developers.ashbyhq.com/reference/candidatecreatenote.md): Creates a note on a candidate.  **Requires the [`candidatesWrite`](authentication#permissions-candidatecreatenote) permission.**  For notes submitted with a type of `text/html`, we support the elements listed below. Any unsupported elements will be stripped out of the note's content before posting.   - Bold `<b>`   - Italic `<i>`   - Underline `<u>`   - Links `<a>`   - Bulleted Lists - `<ul>`, `<li>`   - Ordered Lists - `<ol>`, `<li>`   - Code - `<code>`   - Code Block - `<pre>`
- [candidate.info](https://developers.ashbyhq.com/reference/candidateinfo.md): Gets a single candidate by id.  **Requires the [`candidatesRead`](authentication#permissions-candidateinfo) permission.**
- [candidate.list](https://developers.ashbyhq.com/reference/candidatelist.md): Lists all candidates in an organization.  See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.  **Requires the [`candidatesRead`](authentication#permissions-candidatelist) permission.**
- [candidate.listClientInfo](https://developers.ashbyhq.com/reference/candidatelistclientinfo.md): Lists all client info records for a candidate.  See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.  **Requires the [`candidatesRead`](authentication#permissions-candidatelistclientinfo) permission.**
- [candidate.listFraudChecks](https://developers.ashbyhq.com/reference/candidatelistfraudchecks.md): Fetches a paginated list of fraud checks for a candidate, including the fraud signals detected in each check.  Each fraud check contains a list of fraud signals with their category, name, description, and optional value.  **Field Stability:** - `id` fields are stable and will not change. - `category`, `name`, `description`, and `value` fields on fraud signals are unstable and may change as signals are added, renamed, or recategorized.  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-candidatelistfraudchecks) permission.**  **Note:** This endpoint requires Fraud Detection feature to be enabled for your organization.
- [candidate.listNotes](https://developers.ashbyhq.com/reference/candidatelistnotes.md): Lists all notes on a candidate.  See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.  **Requires the [`candidatesRead`](authentication#permissions-candidatelistnotes) permission.**
- [candidate.listProjects](https://developers.ashbyhq.com/reference/candidatelistprojects.md): Lists all projects on a candidate.  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-candidatelistprojects) permission.**
- [candidate.removeProject](https://developers.ashbyhq.com/reference/candidateremoveproject.md): Removes the candidate from a project.  **Requires the [`candidatesWrite`](authentication#permissions-candidateremoveproject) permission.**
- [candidate.removeTag](https://developers.ashbyhq.com/reference/candidateremovetag.md): Removes a tag from a candidate.  **Requires the [`candidatesWrite`](authentication#permissions-candidateremovetag) permission.**
- [candidate.search](https://developers.ashbyhq.com/reference/candidatesearch.md): Search for candidates by email and / or name.   **Requires the [`candidatesRead`](authentication#permissions-candidatesearch) permission.**  Responses are limited to 100 results. Consider refining your search or using /candidate.list to paginate through all candidates, if you approach this limit. This API is for use cases where you intend to operate on a final small set of candidates, like building a candidate autocomplete.  Note: When multiple search parameters are provided, the parameters are combined with the `AND` operator.
- [candidate.setFraudStatus](https://developers.ashbyhq.com/reference/candidatesetfraudstatus.md): This endpoint allows marking candidates as fraudulent, not fraudulent, or unsure after reviewing their fraud signals via `candidate.listFraudChecks`.  **Requires the [`candidatesWrite`](authentication#permissions-candidatesetfraudstatus) permission.**  **Note:** This endpoint requires the Fraud Detection feature to be enabled for your organization.
- [candidate.update](https://developers.ashbyhq.com/reference/candidateupdate.md): Updates an existing candidate  **Requires the [`candidatesWrite`](authentication#permissions-candidateupdate) permission.**  To set values for custom fields on Candidates, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
- [candidate.uploadFile](https://developers.ashbyhq.com/reference/candidateuploadfile.md): Uploads a file to attach to the candidate's profile.  **Requires the [`candidatesWrite`](authentication#permissions-candidateuploadfile) permission.**  **Recommended: Presigned upload handle** Use `file.createFileUploadHandle` with `fileUploadContext: "CandidateFiles"` to get a presigned URL. Upload the file directly to that URL, then call this endpoint with the returned `fileHandle`. This avoids sending file bytes through the API, improving upload reliability and reducing latency for large files.  **Deprecated: Multipart upload** Send the file as `multipart/form-data` with the file in a `file` field. This mode is deprecated and may be removed in a future API version.
- [candidate.uploadResume](https://developers.ashbyhq.com/reference/candidateuploadresume.md): Uploads a candidate's resume, parses it, and updates their information.  **Requires the [`candidatesWrite`](authentication#permissions-candidateuploadresume) permission.**  **Recommended: Presigned upload handle** Use `file.createFileUploadHandle` with `fileUploadContext: "CandidateResume"` to get a presigned URL. Upload the file directly to that URL, then call this endpoint with the returned `resumeHandle`. This avoids sending file bytes through the API, improving upload reliability and reducing latency for large files.  **Deprecated: Multipart upload** Send the resume as `multipart/form-data` with the file in a `resume` field. This mode is deprecated and may be removed in a future API version.  Note: Existing candidate data always takes precedence over data found by parsing the resume. Resume data only populates candidate data, if it's data that was missing in the candidate model.
- [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.**
- [Endpoint Naming](https://developers.ashbyhq.com/reference/endpoint-naming.md)
- [Expansions](https://developers.ashbyhq.com/reference/expansions.md)
- [Pagination](https://developers.ashbyhq.com/reference/pagination.md)
- [Responses & Errors](https://developers.ashbyhq.com/reference/responses.md)
- [Syncing Records](https://developers.ashbyhq.com/reference/sync.md)
- [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.  **Requires the [`candidatesWrite`](authentication#permissions-customfieldsetvalue) permission.**  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   - Email, LongText, Phone, 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)
- [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.  **Requires the [`candidatesWrite`](authentication#permissions-customfieldsetvalues) permission.**  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   - Email, LongText, Phone, 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)
- [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.archive](https://developers.ashbyhq.com/reference/departmentarchive.md): Archives a department  **Requires the [`organizationWrite`](authentication#permissions-departmentarchive) permission.**
- [department.create](https://developers.ashbyhq.com/reference/departmentcreate.md): Creates a department  **Requires the [`organizationWrite`](authentication#permissions-departmentcreate) permission.**
- [department.move](https://developers.ashbyhq.com/reference/departmentmove.md): Moves a department to another parent  **Requires the [`organizationWrite`](authentication#permissions-departmentmove) permission.**
- [department.restore](https://developers.ashbyhq.com/reference/departmentrestore.md): Restores a department  **Requires the [`organizationWrite`](authentication#permissions-departmentrestore) permission.**
- [department.update](https://developers.ashbyhq.com/reference/departmentupdate.md): Updates a department  **Requires the [`organizationWrite`](authentication#permissions-departmentupdate) 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.**
- [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 forms.  See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.  **Requires the [`hiringProcessMetadataRead`](authentication#permissions-feedbackformdefinitionlist) 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.  Benefits over multipart upload: - **Reliability**: File bytes are uploaded directly to storage, avoiding timeouts and connection resets that can occur when proxying large files through the API. - **Compatibility**: Avoids issues with firewalls or proxies that block or scan multipart payloads containing binary content. - **Simplicity**: The follow-up call to, e.g., `candidate.uploadResume`, `candidate.uploadFile`, or `applicationForm.submit` is a plain `application/json` request rather than `multipart/form-data`.  **Requires the [`candidatesWrite`](authentication#permissions-filecreatefileuploadhandle) permission.**  **Usage flow:**  1. Call `file.createFileUploadHandle` with the file metadata to get a presigned upload URL, form fields, and a handle. 2. Upload the file directly to the returned `url` using a `multipart/form-data` POST request. Include all returned `fields` as form fields, and the file as the last field named `file`. 3. Use the returned `handle` in a follow-up call:    - `candidate.uploadResume` with `{ candidateId, resumeHandle }` to attach a resume to a candidate.    - `candidate.uploadFile` with `{ candidateId, fileHandle }` to attach a file to a candidate.    - `applicationForm.submit` with `Content-Type: application/json`, where file field values in `fieldSubmissions` contain the handle string instead of a multipart file reference.  The presigned URL expires after 10 minutes. The `fileUploadContext` must be one of `CandidateResume`, `CandidateFiles`, or `ApplicationForm`.
- [file.info](https://developers.ashbyhq.com/reference/fileinfo.md): Retrieve the url of a file associated with a candidate  **Requires the [`candidatesRead`](authentication#permissions-fileinfo) permission.**  **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.
- [hiringTeam.addMember](https://developers.ashbyhq.com/reference/hiringteamaddmember.md): Adds an Ashby user to the hiring team at the application or job-level.   **Requires the [`organizationWrite`](authentication#permissions-hiringteamaddmember) permission.**  Hiring team members can be added to a hiring team at the application, job, or opening level.
- [hiringTeam.removeMember](https://developers.ashbyhq.com/reference/hiringteamremovemember.md): Removes an Ashby user from the hiring team at the application or job-level.   **Requires the [`organizationWrite`](authentication#permissions-hiringteamremovemember) permission.**  Hiring team members can be removed from a hiring team at the application, job, or opening level.
- [hiringTeamRole.list](https://developers.ashbyhq.com/reference/hiringteamrolelist.md): Lists the possible hiring team roles in an organization  **Requires the [`organizationRead`](authentication#permissions-hiringteamrolelist) 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.  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.  **Requires the [`interviewsWrite`](authentication#permissions-interviewscheduleupdate) permission.**  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.
- [interviewStageGroup.list](https://developers.ashbyhq.com/reference/interviewstagegrouplist.md): List all interview group stages for an interview plan in order.  **Requires the [`interviewsRead`](authentication#permissions-interviewstagelist) permission.**
- [interviewStage.info](https://developers.ashbyhq.com/reference/interviewstageinfo.md): Fetch interview stage details by id  **Requires the [`interviewsRead`](authentication#permissions-interviewstageinfo) 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.**
- [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.**
- [interviewerPool.addUser](https://developers.ashbyhq.com/reference/interviewerpooladduser.md): Add a user to an interviewer pool.  **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpooladduser) permission.**
- [interviewerPool.archive](https://developers.ashbyhq.com/reference/interviewerpoolarchive.md): Archives an interviewer pool.  **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolarchive) permission.**
- [interviewerPool.create](https://developers.ashbyhq.com/reference/interviewerpoolcreate.md): Create an interviewer pool.  **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolcreate) permission.**
- [interviewerPool.info](https://developers.ashbyhq.com/reference/interviewerpoolinfo.md): Get information about an interviewer pool.  **Requires the [`hiringProcessMetadataRead`](authentication#permissions-interviewerpoolinfo) 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.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.md): Restores an archived interviewer pool.  **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolrestore) permission.**
- [interviewerPool.update](https://developers.ashbyhq.com/reference/interviewerpoolupdate.md): Update an interviewer pool.  **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolupdate) permission.**
- [Introduction](https://developers.ashbyhq.com/reference/introduction.md)
- [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  **Requires the [`jobsRead`](authentication#permissions-jobpostinginfo) permission.**  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).
- [jobPosting.list](https://developers.ashbyhq.com/reference/jobpostinglist.md): Lists all published job postings  **Requires the [`jobsRead`](authentication#permissions-jobpostinglist) permission.**  **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.
- [jobPosting.update](https://developers.ashbyhq.com/reference/jobpostingupdate.md): Updates an existing job posting.  **Requires the [`jobsWrite`](authentication#permissions-jobpostingupdate) permission.**  **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.
- [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.**
- [job.create](https://developers.ashbyhq.com/reference/jobcreate.md): Creates a new job  **Requires the [`jobsWrite`](authentication#permissions-jobcreate) permission.**  To set values for custom fields on Jobs, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
- [job.info](https://developers.ashbyhq.com/reference/jobinfo.md): Returns details about a single job by id  **Requires the [`jobsRead`](authentication#permissions-jobinfo) permission.**
- [job.list](https://developers.ashbyhq.com/reference/joblist.md): List all open, closed, and archived jobs.  See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.  **Requires the [`jobsRead`](authentication#permissions-joblist) permission.**  To include draft jobs, `Draft` must be specified in the `status` param.
- [job.search](https://developers.ashbyhq.com/reference/jobsearch.md): Searches for jobs by title  **Requires the [`jobsRead`](authentication#permissions-jobsearch) permission.**
- [job.setStatus](https://developers.ashbyhq.com/reference/jobsetstatus.md): Sets the status on a job by id.  **Requires the [`jobsWrite`](authentication#permissions-jobsetstatus) permission.**  All jobs are drafts when they're first created. There are a few validations around the stages a job can be transitioned to: - Drafts can be changed to Open or Archived - Open jobs can be changed to Closed - Closed jobs can be changed to Draft or Archived - Archived jobs can be changed to a Draft
- [job.update](https://developers.ashbyhq.com/reference/jobupdate.md): Updates an existing job  **Requires the [`jobsWrite`](authentication#permissions-jobupdate) permission.**  To set values for custom fields on Jobs, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
- [job.updateCompensation](https://developers.ashbyhq.com/reference/jobupdatecompensation.md): Updates an existing job's compensation tiers  **Requires the [`jobsWrite`](authentication#permissions-jobupdate) permission.**
- [location.archive](https://developers.ashbyhq.com/reference/locationarchive.md): Archives a location or location hierarchy.  **Requires the [`organizationWrite`](authentication#permissions-locationarchive) permission.**
- [location.create](https://developers.ashbyhq.com/reference/locationcreate.md): Creates a location or location hierarchy.  **Requires the [`organizationWrite`](authentication#permissions-locationcreate) 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.list](https://developers.ashbyhq.com/reference/locationlist.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.md): Moves a location in location hierarchy.  **Requires the [`organizationWrite`](authentication#permissions-locationmove) permission.**
- [location.restore](https://developers.ashbyhq.com/reference/locationrestore.md): Restores an archived location or location hierarchy.  **Requires the [`organizationWrite`](authentication#permissions-locationrestore) permission.**
- [location.updateAddress](https://developers.ashbyhq.com/reference/locationupdateaddress.md): Update an address of a location or location hierarchy.  **Requires the [`organizationWrite`](authentication#permissions-locationupdateaddress) permission.**
- [location.updateExternalName](https://developers.ashbyhq.com/reference/locationupdateexternalname.md): Update a location's external (candidate-facing) name.  **Requires the [`organizationWrite`](authentication#permissions-locationupdateexternalname) permission.**
- [location.updateName](https://developers.ashbyhq.com/reference/locationupdatename.md): Update location's name.  **Requires the [`organizationWrite`](authentication#permissions-locationupdateName) permission.**
- [location.updateWorkplaceType](https://developers.ashbyhq.com/reference/locationupdateworkplacetype.md): Update location's workplace type.  **Requires the [`organizationWrite`](authentication#permissions-locationupdateworkplacetype) 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. |  **Requires the [`notetakerRead`](authentication#permissions-notetakertranscriptinfo) API key permission.** Configure this in **Admin → API Keys**. See [Managing API Key Permissions](authentication#managing-api-key-permissions).
- [offerProcess.start](https://developers.ashbyhq.com/reference/offerprocessstart.md): Starts an offer process for a candidate.  **Requires the [`offersWrite`](authentication#permissions-offerprocessstart) 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.  **Requires the [`offersWrite`](authentication#permissions-offerapprove) permission.**  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.
- [offer.create](https://developers.ashbyhq.com/reference/offercreate.md): Creates a new Offer  **Requires the [`offersWrite`](authentication#permissions-offercreate) permission.**  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.. |
- [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.   **Requires the [`offersWrite`](authentication#permissions-offerstart) permission.**  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.
- [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.update](https://developers.ashbyhq.com/reference/offerupdate.md): Updates an existing Offer  **Requires the [`offersWrite`](authentication#permissions-offerupdate) permission.**  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.
- [opening.addJob](https://developers.ashbyhq.com/reference/openingaddjob.md): Adds a job to an opening.        **Requires the [`jobsWrite`](authentication#permissions-openingaddjob) permission.**
- [opening.addLocation](https://developers.ashbyhq.com/reference/openingaddlocation.md): Adds a location to an opening.        **Requires the [`jobsWrite`](authentication#permissions-openingaddlocation) permission.**
- [opening.create](https://developers.ashbyhq.com/reference/openingcreate.md): Creates an opening.        **Requires the [`jobsWrite`](authentication#permissions-openingcreate) permission.**  To set values of custom fields on Openings, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
- [opening.info](https://developers.ashbyhq.com/reference/openinginfo.md): Retrieves an opening by its UUID.        **Requires the [`jobsRead`](authentication#permissions-openinginfo) permission.**
- [opening.list](https://developers.ashbyhq.com/reference/openinglist.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.removeJob](https://developers.ashbyhq.com/reference/openingremovejob.md): Removes a job from an opening.        **Requires the [`jobsWrite`](authentication#permissions-openingremovejob) permission.**
- [opening.removeLocation](https://developers.ashbyhq.com/reference/openingremovelocation.md): Removes a location from an opening.        **Requires the [`jobsWrite`](authentication#permissions-openingremovelocation) permission.**
- [opening.search](https://developers.ashbyhq.com/reference/openingsearch.md): Searches for openings by identifier.        **Requires the [`jobsRead`](authentication#permissions-openingsearch) permission.**
- [opening.setArchived](https://developers.ashbyhq.com/reference/openingsetarchived.md): Sets the archived state of an opening.        **Requires the [`jobsWrite`](authentication#permissions-openingsetarchived) permission.**
- [opening.setOpeningState](https://developers.ashbyhq.com/reference/openingsetopeningstate.md): Sets the state of an opening.        **Requires the [`jobsWrite`](authentication#permissions-openingsetopeningstate) permission.**
- [opening.update](https://developers.ashbyhq.com/reference/openingupdate.md): Updates an opening.        **Requires the [`jobsWrite`](authentication#permissions-openingupdate) permission.**  To set values for custom fields on Openings, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.
- [project.info](https://developers.ashbyhq.com/reference/projectinfo.md): Retrieves an project by its UUID.        **Requires the [`jobsRead`](authentication#permissions-projectinfo) permission.**
- [project.list](https://developers.ashbyhq.com/reference/projectlist.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.**
- [project.search](https://developers.ashbyhq.com/reference/projectsearch.md): Search for projects by title.   **Requires the [`candidatesRead`](authentication#permissions-projectsearch) permission.**  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 operate on a final small set of projects, like building a project autocomplete.
- [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.**
- [referral.create](https://developers.ashbyhq.com/reference/referralcreate.md): Creates a referral  **Requires the [`candidatesWrite`](authentication#permissions-referralcreate) 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 → returns `requestId` 2. Poll with both `reportId` and `requestId` every second until `status` is `complete` or `failed`  **Example:** ``` // Step 1: Start generation POST /report.generate { "reportId": "abc-123-def-456" } → { "requestId": "rep_result:12345abc", "status": "in_progress", "reportData": null }  // Step 2: Poll for results POST /report.generate { "reportId": "abc-123-def-456", "requestId": "rep_result:12345abc" } → { "requestId": "rep_result:12345abc", "status": "complete", "reportData": {...} } ```  **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`](ref:reportsynchronous)) - **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`](ref:reportsynchronous) - For synchronous retrieval of existing data, use [`report.synchronous`](ref:reportsynchronous) - 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`](ref:reportgenerate) 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`](ref:reportgenerate)) - Rate limits are shared with [`report.generate`](ref:reportgenerate) 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`](ref:reportgenerate) for async processing - Concurrent limit is released when the HTTP request completes  **Requires the [`reportsRead`](authentication#permissions-reportsynchronous) permission.**
- [sourceTrackingLink.list](https://developers.ashbyhq.com/reference/sourcetrackinglinklist.md): List all source custom tracking links  **Requires the [`hiringProcessMetadataRead`](authentication#permissions-sourcetrackinglinklist) permission.**
- [source.list](https://developers.ashbyhq.com/reference/sourcelist.md): List all sources  **Requires the [`hiringProcessMetadataRead`](authentication#permissions-sourcelist) permission.**
- [Support](https://developers.ashbyhq.com/reference/support.md)
- [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.   **Requires the [`candidatesWrite`](authentication#permissions-surveyrequestcreate) permission.**  **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.
- [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): Create a new survey submission.  **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.**
- [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.deleteInterviewerPause](https://developers.ashbyhq.com/reference/userdeleteinterviewerpause.md): Deletes an interviewer pause.  **Requires the [`organizationWrite`](authentication#permissions-userdeleteinterviewerpause) permission.**
- [user.info](https://developers.ashbyhq.com/reference/userinfo.md): Get an Ashby user by id  **Requires the [`organizationRead`](authentication#permissions-userinfo) permission.**
- [user.interviewerSettings](https://developers.ashbyhq.com/reference/userinterviewersettings.md): Get interviewer settings for a user.  **Requires the [`organizationRead`](authentication#permissions-userinfo) permission.**
- [user.list](https://developers.ashbyhq.com/reference/userlist.md): Get a list of all Ashby users.  See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.  **Requires the [`organizationRead`](authentication#permissions-userlist) permission.**  The `globalRole` property in the response specifies the user's access level in Ashby. For more details on the permissions granted with each role, see our [documentation here](https://docs.ashbyhq.com/user-permissions).
- [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.search](https://developers.ashbyhq.com/reference/usersearch.md): Search for an Ashby user by email address  **Requires the [`organizationRead`](authentication#permissions-usersearch) permission.**
- [user.setCustomFieldValue](https://developers.ashbyhq.com/reference/usersetcustomfieldvalue.md): Set the value of a custom field on an employee.  **Requires the [`organizationWrite`](authentication#permissions-usersetcustomfieldvalue) permission.**  The values accepted in the `fieldValue` param depend on the type of field being updated. See the [`customField.setValue`](#operation/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.
- [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.  **Requires the [`organizationWrite`](authentication#permissions-usersetcustomfieldvalues) permission.**  The values accepted in the `fieldValue` param depend on the type of field being updated. See the [`customField.setValue`](#operation/customFieldSetValue) docs for accepted types.
- [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-userinfo) 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)
- [candidateDelete](https://developers.ashbyhq.com/reference/candidatedeletewebhook.md): Triggered when a candidate is deleted.  Includes the deleted candidate id.
- [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)
- [candidateMerge](https://developers.ashbyhq.com/reference/candidatemergewebhook.md): Triggered when a candidate is merged.  Includes the deleted candidate's id and merged candidate data.
- [candidateStageChange](https://developers.ashbyhq.com/reference/candidatestagechangewebhook.md): Triggered when a candidate changes stages in an application. Also triggered by [candidateHire](ref:candidatehirewebhook)
- [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
- [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)
- [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)
- [jobUpdate](https://developers.ashbyhq.com/reference/jobupdatewebhook.md): Triggered when a job is updated. Also triggered by [interviewPlanTransition](ref:interviewplantransitionwebhook)
- [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
- [ping](https://developers.ashbyhq.com/reference/pingwebhook.md): Called to check that the webhook URL is live
- [pushToHRIS](https://developers.ashbyhq.com/reference/pushtohriswebhook.md): Triggered when a candidate is pushed to an HRIS system
- [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.
- [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.
- [webhook.create](https://developers.ashbyhq.com/reference/webhookcreate.md): Creates a webhook setting.  **Requires the [`apiKeysWrite`](authentication#permissions-webhookcreate) scope.**
- [webhook.delete](https://developers.ashbyhq.com/reference/webhookdelete.md): Deletes a webhook setting.  **Requires the [`apiKeysWrite`](authentication#permissions-webhookcreate) 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.update](https://developers.ashbyhq.com/reference/webhookupdate.md): Updates a webhook setting. One of `enabled`, `requestUrl`, or `secretToken` must be provided.  **Requires the [`apiKeysWrite`](authentication#permissions-webhookcreate) permission.**

## Changelog
- [Improve Interview Plan List Validation](https://developers.ashbyhq.com/changelog/2026-05-21-migrate-interview-plan-list-validation.md)
- [Improve Communication Template List Validation](https://developers.ashbyhq.com/changelog/2026-05-21-migrate-communication-template-list-validation.md)
- [Improve Brand List Validation](https://developers.ashbyhq.com/changelog/2026-05-20-migrate-brand-list-validation.md)
- [Improve Close Reason List Validation](https://developers.ashbyhq.com/changelog/2026-05-20-migrate-close-reason-list-validation.md)
- [Improve Source List Validation](https://developers.ashbyhq.com/changelog/2026-05-20-migrate-source-list-validation.md)