The unique ids of all applications associated with the candidate

Whether the contact info is the primary email or phone number

The email address or phone number of the candidate

An id assigned to a candidate outside of Ashby.
Used to associate Ashby candidates with their profiles in external systems (BambooHR, Rippling, Gusto, etc.)

The URL of the candidate's profile in Ashby

Candidates

Application form submissions. These match the response from the `applicationForm.submit` endpoint. Use of the expand parameter is required to fetch.

The id of the job posting the candidate applied through

Archive Reason to set when moving to an Interview Stage with type: Archived. Note: You must pass this parameter when moving to an Interview Stage with type: Archived

The timestamp an application was archived

The candidate associated with the application

The id of the candidate to consider for a job

The id of the user the application will be credited to.

Expected start date

The id of the interview plan to place the application in. If none is provided, the default interview plan is used.

The interview stage of the interview plan (either default or provided) to place the application in. If none is provided, the application is placed in the first "Lead" stage. You can also supply the special string "FirstPreInterviewScreen", which will choose the first pre-interview-screen stage on the specified job's interview plan.

The id of the job to consider the candidate for

The openings array will only be included if the `openings` expand parameter is included when the request is made.

The source to set on the application being created.

Applications

Archive Reasons

Candidate Tags

Departments

Interview Plans

The id of the application for this interview schedule

The list of events that make up this interview schedule

The id of the interview stage associated with the interview schedule

Interview Schedules

Interview Stages

Interviews

The HTML content of the Job Posting. The following tags will accept updates. Updates to any other tags will be stripped out or not applied.

An HTML block of the job posting description.

Job Postings

Indicates if the job posting is confidential

An array of custom fields associated with the job

The id of the default interview plan for this job posting. A job cannot be opened without a default interview plan.

The id of the department or team associated with the job

An array of team members associated with the job

An array of interview plan ids associated with the job

An array of job posting ids associated with the job

The id of the author of the latest version

The date when the latest version was created

The type of employment for the latest version

An array of team members associated with the latest version

Indicates if the latest version is a backfill

An array of job ids associated with the latest version

An array of location ids associated with the latest version

The target hire date for the latest version

The target start date for the latest version

The id of the team associated with the latest version

An array of openings associated with the job

Jobs

Locations

Offers

The id of the department or team associated with the opening.

Whether this opening is intended to backfill a previous employee

The ids of the jobs associated with the opening

The ids of the locations associated with the opening.

The state the opening should be created in.

The date (in YYYY-MM-DD format) by which you intend to hire against this opening.

The date (in YYYY-MM-DD format) by which you intend someone hired against this opening will start employment.

Openings

Sources

Users

Ashby

Download Resume By Candidate Id

Retrieve information about the API key being used to make the request.

**Requires the [`apiKeysRead`](authentication#permissions-apikeyinfo) permission.**


apiKey.info

Change the source of an application.

**Requires the [`candidatesWrite`](authentication#permissions-applicationchangesource) permission.**


application.changeSource

Change the stage of an application

**Requires the [`candidatesWrite`](authentication#permissions-applicationchangestage) permission.**


application.changeStage

Consider a candidate for a job

**Requires the [`candidatesWrite`](authentication#permissions-applicationcreate) permission.**


application.create

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.info

Gets all applications schedules in the organization.

**Requires the [`candidatesRead`](authentication#permissions-applicationlist) permission.**


application.list

List all feedback associated with an application.

**Requires the [`candidatesRead`](authentication#permissions-applicationfeedbacklist) permission.**

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.


applicationFeedback.list

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
- `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

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.


applicationFeedback.submit

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`.

**Note: The requests generated from this documentation will not work for this endpoint.**


applicationForm.submit

Lists archive reasons

**Requires the [`hiringProcessMetadataRead`](authentication#permissions-archivereasonlist) permission.**


archiveReason.list

Add a completed assessment to a candidate

**Requires the [`candidatesWrite`](authentication#permissions-assessmentaddcompletedtocandidate) permission.**


assessment.addCompletedToCandidate

Update Ashby about the status of a started assessment

**Requires the [`candidatesWrite`](authentication#permissions-assessmentupdate) permission.**


assessment.update

Adds a tag to a candidate

**Requires the [`candidatesWrite`](authentication#permissions-candidateaddtag) permission.**


candidate.addTag

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.anonymize

Creates a new candidate

**Requires the [`candidatesWrite`](authentication#permissions-candidatecreate) permission.**


candidate.create

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>`


candidate.createNote

Gets a single candidate by id.

**Requires the [`candidatesRead`](authentication#permissions-candidateinfo) permission.**


candidate.info

Lists all candidates in an organization

**Requires the [`candidatesRead`](authentication#permissions-candidatelist) permission.**


candidate.list

Lists all notes on a candidate

**Requires the [`candidatesRead`](authentication#permissions-candidatelistnotes) permission.**


candidate.listNotes

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 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.search

Updates an existing candidate

**Requires the [`candidatesWrite`](authentication#permissions-candidateupdate) permission.**


candidate.update

Uploads a file to attach to the candidate's profile.

**Requires the [`candidatesWrite`](authentication#permissions-candidateuploadfile) permission.**

The `Content-Type` of this request must be `multipart/form-data`.


candidate.uploadFile

Uploads a candidate's resume, parses it, and updates their information.

**Requires the [`candidatesWrite`](authentication#permissions-candidateuploadresume) permission.**

The `Content-Type` of this request must be `multipart/form-data`.

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.


candidate.uploadResume

Creates a candidate tag.

**Requires the [`hiringProcessMetadataWrite`](authentication#permissions-candidatetagcreate) permission.**


candidateTag.create

Lists all candidate tags

**Requires the [`hiringProcessMetadataRead`](authentication#permissions-candidatetaglist) permission.**


candidateTag.list

Create a new custom field

**Requires the [`hiringProcessMetadataWrite`](authentication#permissions-customfieldcreate) permission.**


customField.create

Lists all custom fields

**Requires the [`hiringProcessMetadataRead`](authentication#permissions-customfieldlist) permission.**


customField.list

Set the value of a custom field

**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


customField.setValue

Creates a department

**Requires the [`organizationWrite`](authentication#permissions-departmentcreate) permission.**


department.create

Fetch department details by id

**Requires the [`organizationRead`](authentication#permissions-departmentinfo) permission.**


department.info

Lists all departments

**Requires the [`organizationRead`](authentication#permissions-departmentlist) permission.**


department.list

Retrieve the url of a file associated with a candidate

**Requires the [`candidatesRead`](authentication#permissions-fileinfo) permission.**


file.info

Returns a single feedback form by id

**Requires the [`hiringProcessMetadataRead`](authentication#permissions-feedbackformdefinitioninfo) permission.**


feedbackFormDefinition.info

Lists all feedback forms

**Requires the [`hiringProcessMetadataRead`](authentication#permissions-feedbackformdefinitionlist) permission.**


feedbackFormDefinition.list

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 level or at the job level.


hiringTeam.addMember

Lists the possible hiring team roles in an organization

**Requires the [`organizationRead`](authentication#permissions-hiringteamrolelist) permission.**


hiringTeamRole.list

Fetch interview details by id

**Requires the [`interviewsRead`](authentication#permissions-interviewinfo) permission.**


interview.info

List all interviews

**Requires the [`interviewsRead`](authentication#permissions-interviewlist) permission.**


interview.list

Lists interview events associated with an interview schedule

**Requires the [`interviewsRead`](authentication#permissions-intervieweventlist) permission.**


interviewEvent.list

List all interview plans.

**Requires the [`interviewsRead`](authentication#permissions-interviewplanlist) permission.**


interviewPlan.list

Cancel an interview schedule by id

**Requires the [`interviewsWrite`](authentication#permissions-interviewschedulecancel) permission.**


interviewSchedule.cancel

Create a scheduled interview in Ashby

**Requires the [`interviewsWrite`](authentication#permissions-interviewschedulecreate) permission.**


interviewSchedule.create

Gets all interview schedules in the organization.

**Requires the [`interviewsRead`](authentication#permissions-interviewschedulelist) permission.**


interviewSchedule.list

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.


interviewSchedule.update

List all interview stages for an interview plan in order.

**Requires the [`interviewsRead`](authentication#permissions-interviewstagelist) permission.**


interviewStage.list

Fetch interview stage details by id

**Requires the [`interviewsRead`](authentication#permissions-interviewstageinfo) permission.**


interviewStage.info

Creates a new job

**Requires the [`jobsWrite`](authentication#permissions-jobcreate) permission.**


job.create

Returns details about a single job by id

**Requires the [`jobsRead`](authentication#permissions-jobinfo) permission.**


job.info

List all open, closed, and archived jobs.

**Requires the [`jobsRead`](authentication#permissions-joblist) permission.**

To include draft jobs, `Draft` must be specified in the `status` param.


job.list

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.setStatus

Updates an existing job

**Requires the [`jobsWrite`](authentication#permissions-jobupdate) permission.**


job.update

Searches for jobs by title

**Requires the [`jobsRead`](authentication#permissions-jobsearch) permission.**


job.search

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.**


jobInterviewPlan.info

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.info

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.list

Updates an existing job posting.

**Requires the [`jobsWrite`](authentication#permissions-jobpostingupdate) permission.**

**Note on updating the description**: 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.


jobPosting.update

Creates a location or location hierarchy.

**Requires the [`organizationWrite`](authentication#permissions-locationcreate) permission.**


location.create

Gets details for a single location by id.

**Requires the [`organizationRead`](authentication#permissions-locationinfo) permission.**


location.info

List all locations. Regions are not returned.

**Requires the [`organizationRead`](authentication#permissions-locationlist) permission.**


location.list

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.


offer.create

Returns details about a single offer by id

**Requires the [`offersRead`](authentication#permissions-offerinfo) permission.**


offer.info

Get a list of all offers with their latest version

**Requires the [`offersRead`](authentication#permissions-offerlist) permission.**


offer.list

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.start

Starts an offer process for a candidate.

**Requires the [`offersWrite`](authentication#permissions-offerprocessstart) permission.**


offerProcess.start

Retrieves an opening by its UUID.

**Requires the [`jobsRead`](authentication#permissions-openinginfo) permission.**

opening.info

Lists openings.

**Requires the [`jobsRead`](authentication#permissions-openinglist) permission.**

opening.list

Searches for openings by identifier.

**Requires the [`jobsRead`](authentication#permissions-openingsearch) permission.**

opening.search

Creates an opening.

**Requires the [`jobsWrite`](authentication#permissions-openingcreate) permission.**

Ashby API Integration Profile

How to work with Candidates in Ashby API

Operations on Candidates Collection

See Related Collections

Build every single integration your customers need with AI

Field Name	API Key	Type	Description
Id	id	string	The unique id of the candidate
Created At	createdAt	string	The candidate's name
Name	name	string
Primary Email Address	primaryEmailAddress	object
Value	primaryEmailAddress.value	string	The email address or phone number of the candidate