Use HTTP Basic Auth to authenticate with our API. You must send your API key with every request. Put your API key as the basic auth username and leave the password blank:

curl https://api.ashbyhq.com/application.list -u API_KEY: -H "Accept: application/json; version=1" --request POST --header 'Content-Type: application/json'

If your API key is missing, the API will respond with a 401 status code. When the provided key is wrong or deactivated, the API will respond with a 403 status code. All three situations will return a human-readable response specific to the situation.

API Key Endpoint Permissions

Each API key has a set of permissions that determine which endpoints it can read or write. If your API key does not have the necessary permissions to access an endpoint, the API will respond with a 403 status code and an error of missing_endpoint_permission.

Table of Permissions

API permissions are organized by module. You can grant an API key read or write access to each module. The following table lists the endpoints that are covered by read and write permission for each module:

Module	Read Endpoints	Write Endpoints
Jobs	job.info job.list job.search jobBoard.list jobInterviewPlan.info jobPosting.info jobPosting.list jobTemplate.list opening.info opening.list opening.search	job.create job.setStatus job.update job.updateCompensation jobPosting.update opening.addJob opening.addLocation opening.create opening.removeJob opening.removeLocation opening.setArchived opening.setOpeningState opening.update
Candidates	application.info application.list application.listCriteriaEvaluations application.listHistory applicationFeedback.list applicationHiringTeamRole.list candidate.info candidate.list candidate.listClientInfo candidate.listNotes candidate.listProjects candidate.search file.info project.info project.list project.search surveyRequest.list surveySubmission.list	application.addHiringTeamMember application.change_source application.change_stage application.changeSource application.changeStage application.create application.removeHiringTeamMember application.transfer application.update application.updateHistory applicationFeedback.submit applicationForm.submit assessment.addCompletedToCandidate assessment.update candidate.addProject candidate.addTag candidate.anonymize candidate.create candidate.createNote candidate.update candidate.uploadFile candidate.uploadResume customField.setValue referral.create sequence.cancel surveyRequest.create surveySubmission.create
Interviews	interview.info interview.list interviewEvent.list interviewPlan.list interviewSchedule.list interviewStage.info interviewStage.list interviewStageGroup.list	interviewSchedule.cancel interviewSchedule.create interviewSchedule.update
Hiring Process	archiveReason.list candidateTag.list closeReason.list communicationTemplate.list customField.info customField.list feedbackFormDefinition.info feedbackFormDefinition.list interviewerPool.info interviewerPool.list referralForm.info source.list sourceTrackingLink.list surveyFormDefinition.info surveyFormDefinition.list	candidateTag.create customField.create interviewerPool.addUser interviewerPool.archive interviewerPool.create interviewerPool.removeUser interviewerPool.restore interviewerPool.update
Organization	department.info department.list hiringTeamRole.list location.info location.list user.info user.interviewerSettings user.list user.search	department.archive department.create department.move department.restore department.update hiringTeam.addMember hiringTeam.removeMember location.archive location.create location.move location.restore location.updateAddress location.updateName location.updateRemoteStatus location.updateWorkplaceType user.updateInterviewerSettings
Offers	offer.info offer.list	offer.approve offer.create offer.start offer.update offerProcess.start
API Keys	apiKey.info webhook.info	webhook.create webhook.delete webhook.update
Approvals	approval.list	approvalDefinition.update
Reports	report.generate report.synchronous

Confidential Job and Project Access

By default, API keys cannot access confidential job and project information. This includes job/project data, job considerations, and candidates for confidential jobs and projects. To grant an API key access to confidential job and project information, you must select the "Allow access to confidential jobs and projects?" permission in the Ashby web app.

Private Fields Access

By default, API keys cannot access information stored in private fields on candidates, except on offers. To grant an API key access to private field information on other modules, you must select the "Allow access to non-offer private fields?" permission in the Ashby web app.

Managing API Key Permissions

An Ashby Admin can manage permissions for existing API keys in the Ashby web app:

Permissions for Merge Integrations

If you access Ashby data using the Merge ATS API, you will need to grant your API key the necessary permissions for Merge to access the data you need. You can find a mapping between Merge Common Models and the Ashby endpoints they use in the Merge documentation for Ashby here.