Ashby/candidates

@keeb/ashby/candidatesv2026.10.29.2· MIT· 2d agoBEHAVIORS

01README

Ashby candidates and applications: candidates, tags, applications and their history, feedback, application forms, referrals, assessments and file uploads

02Release Notes

Updated: candidate, application
sync now sends read parameters configured as global arguments (jobPosting includeUnpublishedJobPostings, offer excludeFormDefinition) instead of recording unpublished/filtered records as not_found; global arguments accepted by only create or only update now say so

03Behaviors11

@keeb/ashby/candidates/applicationv2026.10.29.2application.ts

Global Arguments

Argument	Type	Required	Description
candidateId?	string	no	The id of the candidate to consider for a job. Sent by create only; application.update does not accept it.
jobId?	string	no	The id of the job to consider the candidate for. Sent by create only; application.update does not accept it.
interviewPlanId?	string	no	The id of the interview plan to place the application in. If none is provided, the default interview plan is used. Sent by create only; application.update does not accept it.
interviewStageId?	union	no	The interview stage of the interview plan 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 selects the first pre-interview-screen stage on the job\
sourceId?	string	no	The source to set on the application being created.
creditedToUserId?	string	no	The id of the user the application will be credited to.
createdAt?	string	no	An ISO date string to set the application's `createdAt` timestamp. Defaults to the time the call was made when not provided.
applicationHistory?	array	no	An array of objects representing the application history. When provided, the application is created with the supplied history events. Sent by create only; application.update does not accept it.
sendNotifications?	boolean	no	Whether users subscribed to the application should be notified that the application was updated. Defaults to `true`. Sent by update only; application.create does not accept it.
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a application from the model's global arguments (application.create). Consider a candidate for a job (e.g. when sourcing a candidate for a job posting). Requires the `candidatesWrite` permission.

fn get(applicationId?: string, submittedFormInstanceId?: string, expand?: array)

Get a application and record it as this model's state (application.info). Fetch application details by application id or by submitted form instance id (which is returned by the `applicationForm.submit` endpoint). If both `applicationId` and `submittedFormInstanceId` are provided, the lookup uses `applicationId`. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
applicationId?	string	no	The id of the application to fetch.
submittedFormInstanceId?	string	no	The id of the application's submitted form instance to fetch. Either `applicationId` or `submittedFormInstanceId` must be provided. When both are supplied, the lookup uses `applicationId`.
expand?	array	no	Choose to expand the result and include additional data for related objects.

fn lookup(syncToken?: string, createdAfter?: number, createdBefore?: number, status?: string, jobId?: string, expand?: array, max_items?: number)

List application records and record each as a data artifact (application.list; capped at 500 by default; writes a application_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
syncToken?	string	no	A sync token to retrieve only applications updated since the last sync. Obtained from a previous list response.
createdAfter?	number	no	Unix timestamp (milliseconds). When provided, only applications created at or after this time are returned. Must not be later than createdBefore or in the future.
createdBefore?	number	no	Unix timestamp (milliseconds). When provided, only applications created at or before this time are returned. Must not be in the future.
status?	string	no	Filter applications by status. Comparison is case-insensitive against `Hired`, `Archived`, `Active`, `Lead`.
jobId?	string	no	Only return applications for the job with the supplied id.
expand?	array	no	Choose to expand the result and include additional data for related objects.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the application_lookup record reports truncated: true.

fn update()

Apply the model's global arguments to the stored application (application.update). Run create or get first.

fn delete(id: string)

Delete the application (application.delete). An already-absent application is recorded as not_found rather than failing.

Argument	Type	Required	Description
id	string	yes	The id of the application

fn sync()

Sync the stored application from Ashby (application.info); records status not_found when it is gone.

fn add_hiring_team_member(applicationId: string, teamMemberId: string, roleId: string)

application.addHiringTeamMember: Adds an Ashby user to the hiring team at the application level. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
applicationId	string	yes	The application to assign the user a role on.
teamMemberId	string	yes	The id of the user to assign the role to.
roleId	string	yes	The id of the hiring team role to assign.

fn change_source(applicationId: string, sourceId?: string)

application.changeSource: Change the source of an application. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
applicationId	string	yes	The id of the application to update the source of.
sourceId?	string	no	The source to set on the application. Pass `null` to unset an application's source.

fn change_stage(applicationId: string, interviewStageId: string, archiveReasonId?: string, archiveEmail?: object)

application.changeStage: Change the stage of an application. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
applicationId	string	yes	The id of the application to update the stage of.
interviewStageId	string	yes	The interview stage to move the application to.
archiveReasonId?	string	no	Archive Reason to set when moving to an Interview Stage with type `Archived`. Required when moving to an `Archived` stage.
archiveEmail?	object	no

fn list_criteria_evaluations(applicationId: string, max_items?: number)

application.listCriteriaEvaluations: Fetch a paginated list of AI criteria evaluations for an application. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
applicationId	string	yes	The id of the application to fetch criteria evaluations for.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the result reports truncated: true.

fn list_history(applicationId: string, max_items?: number)

application.listHistory: Fetch a paginated list of application history items for an application. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
applicationId	string	yes	The id of the application to fetch.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the result reports truncated: true.

fn remove_hiring_team_member(applicationId: string, teamMemberId: string, roleId: string)

application.removeHiringTeamMember: Unassigns a hiring team role from an Ashby user at the application level. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
applicationId	string	yes	The application to unassign the user a role from.
teamMemberId	string	yes	The id of the user to unassign the role from.
roleId	string	yes	The id of the hiring team role to unassign.

fn transfer(applicationId: string, jobId: string, interviewPlanId: string, interviewStageId: string, startAutomaticActivities?: boolean)

application.transfer: Transfer an application to a different job. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
applicationId	string	yes	The id of the application to transfer.
jobId	string	yes	The id of the job to transfer the application to.
interviewPlanId	string	yes	The id of the interview plan to transfer the application to.
interviewStageId	string	yes	The interview stage of the interview plan to transfer the application to.
startAutomaticActivities?	boolean	no	Whether to start any automatic activities set on the target interview stage. Defaults to `true` when omitted.

fn update_history(applicationId: string, applicationHistory: array)

application.updateHistory: Update the history of an application. Used to update stage timestamps and to delete history events. Also requires the `Allow updating application history?` setting found in your admin API key permissions configuration.

Argument	Type	Required	Description
applicationId	string	yes	The id of the application whose history to update.
applicationHistory	array	yes	The updated array of application history events. This array should contain all history events for the application, not just the events being updated.

Resources

state(infinite)— Ashby application state

application_lookup(infinite)— Ashby application lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

application_action(infinite)— Ashby application action result, one per action

@keeb/ashby/candidates/application-feedbackv2026.10.29.1application_feedback.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn lookup(applicationId?: string, syncToken?: string, createdAfter?: number, includeVisibilityConditions?: boolean, max_items?: number)

List application feedback records and record each as a data artifact (applicationFeedback.list; capped at 500 by default; writes a application_feedback_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
applicationId?	string	no	The id of the application you'd like to fetch feedback for
syncToken?	string	no	A sync token to retrieve only feedback updated since the last sync. Obtained from a previous list response.
createdAfter?	number	no	Unix timestamp (milliseconds). When provided, only feedback created at or after this time is returned.
includeVisibilityConditions?	boolean	no	This feature is in beta and may not be available for all organizations. When true, each form field's visibilityCondition tree is included. Defaults to false on this endpoint to keep responses small.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the application_feedback_lookup record reports truncated: true.

fn submit(feedbackForm: object, formDefinitionId: string, applicationId: string, userId?: string, interviewEventId?: string)

applicationFeedback.submit: Submit feedback for an application using the field paths and types from its feedback form. Use `feedbackFormDefinition.info` to read a form's fields. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
feedbackForm	object	yes	The application feedback form data containing field submissions
formDefinitionId	string	yes	The feedback form to submit. For interview feedback, this must be the form assigned to the interview.
applicationId	string	yes	The application to submit feedback for. For interview feedback, this must match the interview's application.
userId?	string	no	The id of the user the feedback will be credited to. If omitted, the feedback will be credited to the API key user.
interviewEventId?	string	no	The interview event to submit feedback for. Requires userId to identify the interviewer. If their feedback already exists, it is updated; otherwise it is created. Omit this to create a separate feedback submission.

Resources

state(infinite)— Ashby application feedback state

application_feedback_lookup(infinite)— Ashby application feedback lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

application_feedback_action(infinite)— Ashby application feedback action result, one per action

@keeb/ashby/candidates/application-feedback-requestv2026.10.29.1application_feedback_request.ts

Global Arguments

Argument	Type	Required	Description
applicationId?	string	no	The id of the application you are requesting feedback for
interviewId?	string	no	The id of the interview associated with this feedback request
interviewerUserId?	string	no	The user you are requesting feedback from
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a application feedback request from the model's global arguments (applicationFeedbackRequest.create). 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. Requires the `candidatesWrite` permission.

Resources

state(infinite)— Ashby application feedback request state

@keeb/ashby/candidates/application-formv2026.10.29.1application_form.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn submit(jobPostingId: string, applicationForm: object, utmData?: object, tagIds?: array, allowSubmissionForUnpublishedJobPosting?: boolean)

applicationForm.submit: Submits a completed application form for a job posting. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
jobPostingId	string	yes	The id of the job posting to submit the application for
applicationForm	object	yes	The application form data containing field submissions
utmData?	object	no	Optional UTM tracking data
tagIds?	array	no	Optional array of tag ids to apply to the candidate
allowSubmissionForUnpublishedJobPosting?	boolean	no	If false, applications for unpublished job postings will be rejected. Defaults to true.

Resources

state(infinite)— Ashby application form state

application_form_action(infinite)— Ashby application form action result, one per action

@keeb/ashby/candidates/application-hiring-team-rolev2026.10.29.1application_hiring_team_role.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn lookup(max_items?: number)

List application hiring team role records and record each as a data artifact (applicationHiringTeamRole.list; capped at 500 by default; writes a application_hiring_team_role_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the application_hiring_team_role_lookup record reports truncated: true.

Resources

state(infinite)— Ashby application hiring team role state

application_hiring_team_role_lookup(infinite)— Ashby application hiring team role lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/candidates/assessmentv2026.10.29.1assessment.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn add_completed_to_candidate(candidateId: string, partnerId: string, assessment: object, timestamp: number)

assessment.addCompletedToCandidate: Add a completed assessment to a candidate. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate to whom to add the completed assessment
partnerId	string	yes	The id of the partner adding the assessment
assessment	object	yes	The completed assessment to add
timestamp	number	yes	The timestamp in milliseconds since the unix epoch when the assessment was completed

fn update_action(assessment_id: string, timestamp: number, assessment_status?: object, assessment_profile_url?: object, assessment_result?: object, cancelled_reason?: object, metadata?: array)

assessment.update: Update Ashby about the status of a started assessment. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
assessment_id	string	yes	Identifier of the assessment being updated
timestamp	number	yes	The timestamp in milliseconds since the unix epoch when the assessment update occurred
assessment_status?	object	no	The current status of the assessment. Setting this with a value of "Started" will signal Ashby to store the timestamp the assessment started. Required when `cancelled_reason` is not set.
assessment_profile_url?	object	no	The url back to the assessment/candidate on the partner's website. This value should always be of type url. Required when `assessment_result` is set.
assessment_result?	object	no	The result of the assessment. Sending an update with this field will signal to Ashby that the assessment is complete.
cancelled_reason?	object	no	The reason the assessment was cancelled. This field will signal to Ashby that the assessment is cancelled.
metadata?	array	no	Any other metadata about the assessment (e.g. ETA until complete). All assessment data should have unique identifiers.

Resources

state(infinite)— Ashby assessment state

assessment_action(infinite)— Ashby assessment action result, one per action

@keeb/ashby/candidates/candidatev2026.10.29.2candidate.ts

Global Arguments

Argument	Type	Required	Description
name?	string	no	The first and last name of the candidate to be created
email?	string	no	Primary, personal email of the candidate to be created
phoneNumber?	string	no	Primary, personal phone number of the candidate to be created
linkedInUrl?	string	no	Url to the candidate's LinkedIn profile. Must be a valid Url.
githubUrl?	string	no	Url to the candidate's Github profile. Must be a valid Url.
website?	string	no	Url of the candidate's website. Must be a valid Url. Sent by create only; candidate.update does not accept it.
alternateEmailAddresses?	array	no	Array of alternate email addresses to add to the candidate's profile. Sent by create only; candidate.update does not accept it.
sourceId?	string	no	The source to set on the candidate being created
creditedToUserId?	string	no	The id of the user the candidate will be credited to
location?	object	no	The location of the candidate
createdAt?	string	no	An ISO date string to set the candidate's `createdAt` timestamp. When this value isn't provided, the `createdAt` timestamp defaults to the time the call was made.
websiteUrl?	string	no	Url of the candidate's website. Must be a valid Url. Sent by update only; candidate.create does not accept it.
alternateEmail?	string	no	An alternate email address to add to the candidate's profile. Sent by update only; candidate.create does not accept it.
socialLinks?	array	no	An array of social links to set on the candidate. This value replaces existing socialLinks that have been set on the candidate. If this value is submitted along with linkedInUrl, gitHubUrl or websiteUrl fields, those values will be ignored. Sent by update only; candidate.create does not accept it.
sendNotifications?	boolean	no	Whether or not users who are subscribed to the candidate should be notified that the candidate was updated. Default is true. Sent by update only; candidate.create does not accept it.
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a candidate from the model's global arguments (candidate.create). Creates a new candidate. Requires the `candidatesWrite` permission.

fn get(id?: string, externalMappingId?: string)

Get a candidate and record it as this model's state (candidate.info). Fetches details about a single candidate by id or external mapping id. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
id?	string	no	The id of the candidate to fetch
externalMappingId?	string	no	An id assigned to a candidate outside of Ashby. Used to associate Ashby candidates with their profiles in external systems (BambooHR, Rippling, Gusto, etc.)

fn lookup(syncToken?: string, createdAfter?: number, createdBefore?: number, max_items?: number)

List candidate records and record each as a data artifact (candidate.list; capped at 500 by default; writes a candidate_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
syncToken?	string	no	A sync token to retrieve only candidates updated since the last sync. Obtained from a previous list response.
createdAfter?	number	no	Unix timestamp (milliseconds). When provided, only candidates created at or after this time are returned. Must not be later than createdBefore or in the future.
createdBefore?	number	no	Unix timestamp (milliseconds). When provided, only candidates created at or before this time are returned. Must not be in the future.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the candidate_lookup record reports truncated: true.

fn update()

Apply the model's global arguments to the stored candidate (candidate.update). Run create or get first.

fn sync()

Sync the stored candidate from Ashby (candidate.info); records status not_found when it is gone.

fn add_email_message(candidateId: string, emailProviderEmailId: string, subject: string, from: string, to: string, body: string, userId?: string, sentAt?: string, cc?: string, messageUrl?: string, messageIdHeader?: string, threadId?: string, isPrivate?: boolean)

candidate.addEmailMessage: Attaches an existing email message (e.g. fetched from a partner provider) to a candidate. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The candidate to attach this email to
emailProviderEmailId	string	yes	Unique identifier for this message in the partner system. Must be unique per API key.
subject	string	yes	The email subject line
from	string	yes	The sender email address
to	string	yes	The recipient email address
body	string	yes	The html body of the email
userId?	string	no	The Ashby user ID to associate with this email. Defaults to the API key user.
sentAt?	string	no	When the email was sent. Defaults to the current time.
cc?	string	no	CC recipients
messageUrl?	string	no	URL to view the message in the partner application
messageIdHeader?	string	no	RFC 5322 message identifier
threadId?	string	no	Thread identifier to group this message with others. Defaults to emailProviderEmailId.
isPrivate?	boolean	no	Whether the email should be marked as private. Private emails require "Allow access to non-offer private fields?" API key permission to create and view. Defaults to false.

fn add_project(candidateId: string, projectId: string)

candidate.addProject: Adds a candidate to a project. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate
projectId	string	yes	The id of the project

fn add_tag(candidateId: string, tagId: string)

candidate.addTag: Adds a tag to a candidate. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The unique id of the candidate to add the tag to
tagId	string	yes	The unique id of the tag to add to the candidate

fn anonymize(candidateId: string)

candidate.anonymize: Anonymizes a candidate's personally identifiable information. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate to anonymize

fn create_note(candidateId: string, note: union, sendNotifications?: boolean, isPrivate?: boolean, createdAt?: string)

candidate.createNote: Creates a note on a candidate. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate
note	union	yes	The note to add to the candidate. Either a plain string, or an object `{ type, value }` where `type` is `text/plain` or `text/html`.
sendNotifications?	boolean	no	Whether or not users who are subscribed to the candidate should be notified that the note was posted. Default is false.
isPrivate?	boolean	no	Whether the note should be marked as private. Private notes require "Allow access to non-offer private fields?" API key permission to create and view. Default is false.
createdAt?	string	no	An ISO date string to set the note's `createdAt` timestamp

fn get_recent_email_messages(candidateId: string, direction?: enum, sentAfter?: string, watermark?: string, max_items?: number)

candidate.getRecentEmailMessages (Beta): Returns recent email messages for a candidate, newest first. A request without a `cursor` starts a point-in-time snapshot containing at most 200 matching messages. Requires the `emailsRead` permission.

Argument	Type	Required	Description
candidateId	string	yes	The unique identifier of the candidate
direction?	enum	no	Only return messages sent or received by the organization
sentAfter?	string	no	Only return messages sent after this ISO 8601 timestamp
watermark?	string	no	An opaque token from the candidateRecentEmailMessagesUpdated webhook. Pass it unchanged. Only a request with this watermark is guaranteed to include the up-to-date email change that triggered the webhook. Start a new request with this watermark and omit cursor. The watermark applies only to this candidate and is valid for starting the first page for one hour from the webhook delivery attempt.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the result reports truncated: true.

fn list_client_info(candidateId: string, syncToken?: string, max_items?: number)

candidate.listClientInfo: Lists client information records (IP, user agent) collected for a candidate. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate to fetch client info for
syncToken?	string	no	An opaque token representing the last time the data was successfully synced from the API. A new, updated one is returned after successfully fetching the last page of data.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the result reports truncated: true.

fn list_fraud_checks(candidateId: string, max_items?: number)

candidate.listFraudChecks: Lists the fraud checks performed on a candidate. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate to fetch fraud checks for
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the result reports truncated: true.

fn list_notes(candidateId: string, syncToken?: string, max_items?: number)

candidate.listNotes: Lists the notes that have been added to a candidate, ordered from newest to oldest. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate to fetch notes for
syncToken?	string	no	Accepted for backward compatibility. This endpoint does not currently support incremental synchronization.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the result reports truncated: true.

fn list_projects(candidateId: string, max_items?: number)

candidate.listProjects: Lists the projects a candidate has been added to. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate to fetch projects for
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the result reports truncated: true.

fn push_to_hris(applicationId: string, externalSystem: enum, integrationPartnerId?: string)

candidate.pushToHris (Beta): Pushes a candidate's data to an HRIS system (e.g. Workday, BambooHR, ADP). Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
applicationId	string	yes	The ID of the application whose candidate should be pushed to the HRIS.
externalSystem	enum	yes	The HRIS system to push the candidate to. Note: HiBob uses the value "bob".
integrationPartnerId?	string	no	The ID of the integration partner. Required for SelfServe integrations.

fn remove_project(candidateId: string, projectId: string)

candidate.removeProject: Removes the candidate from a project. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate
projectId	string	yes	The id of the project

fn remove_tag(candidateId: string, tagId: string)

candidate.removeTag: Removes a tag from a candidate. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate to remove the tag from
tagId	string	yes	The id of the tag to remove from the candidate

fn search(email?: string, name?: string, limit?: number)

candidate.search: Searches for candidates by email and/or name. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
email?	string	no	The candidate's email
name?	string	no	The candidate's name
limit?	number	no	The maximum number of candidates to return. Defaults to 100 and cannot exceed 100.

fn search_suggestions(email?: string, name?: string, limit?: number)

candidate.searchSuggestions: Searches for candidates by email and/or name and returns a minimal suggestion shape for typeahead use cases. Requires the `candidatesRead` permission.

Argument	Type	Required	Description
email?	string	no	The candidate's email
name?	string	no	The candidate's name
limit?	number	no	The maximum number of candidate suggestions to return. Defaults to 10 and cannot exceed 100.

fn set_fraud_status(candidateId: string, fraudStatus: enum)

candidate.setFraudStatus: Updates the manual fraud-review status of a candidate. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate to set the fraud status for
fraudStatus	enum	yes	The fraud status to set for the candidate

fn upload_file(candidateId: string, fileHandle?: string)

candidate.uploadFile: Uploads a file for a candidate. Accepts either a multipart/form-data request with a `file` file part, or a JSON body with a `fileHandle` previously created via `file.createFileUploadHandle`. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate
fileHandle?	string	no	A handle returned by `file.createFileUploadHandle` after uploading a file to the presigned URL.

fn upload_resume(candidateId: string, resumeHandle?: string)

candidate.uploadResume: Uploads a resume for a candidate. Accepts either a multipart/form-data request with a `resume` file part, or a JSON body with a `resumeHandle` previously created via `file.createFileUploadHandle`. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
candidateId	string	yes	The id of the candidate
resumeHandle?	string	no	A handle returned by `file.createFileUploadHandle` after uploading a resume file to the presigned URL.

Resources

state(infinite)— Ashby candidate state

candidate_lookup(infinite)— Ashby candidate lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

candidate_action(infinite)— Ashby candidate action result, one per action

@keeb/ashby/candidates/candidate-tagv2026.10.29.1candidate_tag.ts

Global Arguments

Argument	Type	Required	Description
title?	string	no	The tag's title. If a tag already exists with that title, the existing tag will be returned.
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a candidate tag from the model's global arguments (candidateTag.create). Creates a candidate tag. Requires the `hiringProcessMetadataWrite` permission.

fn lookup(includeArchived?: boolean, syncToken?: string, max_items?: number)

List candidate tag records and record each as a data artifact (candidateTag.list; capped at 500 by default; writes a candidate_tag_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
includeArchived?	boolean	no	Whether archived candidate tags should be included in the response
syncToken?	string	no	A sync token to retrieve only candidate tags updated since the last sync. Obtained from a previous list response.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the candidate_tag_lookup record reports truncated: true.

fn archive(tagId: string)

candidateTag.archive: Archives a candidate tag. Requires the `hiringProcessMetadataWrite` permission.

Argument	Type	Required	Description
tagId	string	yes	The candidate tag's unique id

Resources

state(infinite)— Ashby candidate tag state

candidate_tag_lookup(infinite)— Ashby candidate tag lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

candidate_tag_action(infinite)— Ashby candidate tag action result, one per action

@keeb/ashby/candidates/filev2026.10.29.1file.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn get(fileHandle: string)

Get a file and record it as this model's state (file.info). Retrieve the URL for a file referenced by a public API file handle (candidate files, resumes, offer letters, and signature-request files). Requires the `candidatesRead` permission.

Argument	Type	Required	Description
fileHandle	string	yes	A file handle retrieved from the public API

fn create_file_upload_handle(fileUploadContext: enum, filename: string, contentType: string, contentLength: number)

file.createFileUploadHandle: Creates a presigned upload URL that allows uploading a file directly to storage, bypassing the need to send file bytes through the API. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
fileUploadContext	enum	yes	The context for the file upload. Use CandidateResume for resume uploads, CandidateFiles for general file uploads, and ApplicationForm for file fields in application form submissions.
filename	string	yes	The name of the file being uploaded, including extension
contentType	string	yes	The MIME type of the file being uploaded
contentLength	number	yes	The size of the file in bytes

fn upload(path: string, fileUploadContext: enum, filename?: string, contentType?: string)

Upload a local file to Ashby storage (file.createFileUploadHandle, then the presigned POST) and record its handle. Pass the handle to the candidate model's upload_resume / upload_file or to application_form submit.

Argument	Type	Required	Description
path	string	yes	Local path of the file to upload.
fileUploadContext	enum	yes	CandidateResume for candidate upload_resume, CandidateFiles for candidate upload_file, ApplicationForm for application form file fields.
filename?	string	no	Name Ashby records for the file. Defaults to the basename of path.
contentType?	string	no	MIME type. Defaults to a guess from the file extension.

Resources

state(infinite)— Ashby file state

file_action(infinite)— Ashby file action result, one per action

@keeb/ashby/candidates/referralv2026.10.29.1referral.ts

Global Arguments

Argument	Type	Required	Description
id?	string	no	The id of the referral form, from /referralForm.info
creditedToUserId?	string	no	The id of the user submitting the referral
fieldSubmissions?	array	no	The field submissions for the referral form
createdAt?	string	no	An ISO date string to set the referral's createdAt timestamp to. When this value isn't provided, the createdAt timestamp defaults to the time the referral was created.
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a referral from the model's global arguments (referral.create). Creates a referral Requires the `candidatesWrite` permission.

fn lookup(applicationId?: string, syncToken?: string, createdAfter?: number, includeVisibilityConditions?: boolean, max_items?: number)

List referral records and record each as a data artifact (referral.list; capped at 500 by default; writes a referral_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
applicationId?	string	no	The id of the application you'd like to fetch referrals for
syncToken?	string	no	A sync token to retrieve only referrals updated since the last sync. Obtained from a previous list response.
createdAfter?	number	no	Unix timestamp (milliseconds). When provided, only referrals created at or after this time are returned.
includeVisibilityConditions?	boolean	no	This feature is in beta and may not be available for all organizations. When true, each form field's visibilityCondition tree is included. Defaults to false on this endpoint to keep responses small.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the referral_lookup record reports truncated: true.

fn delete(id: string)

Delete the referral (referral.delete). An already-absent referral is recorded as not_found rather than failing.

Argument	Type	Required	Description
id	string	yes	The id of the referral

Resources

state(infinite)— Ashby referral state

referral_lookup(infinite)— Ashby referral lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/candidates/referral-formv2026.10.29.1referral_form.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn get()

Get a referral form and record it as this model's state (referralForm.info). Fetches the default referral form or creates a default referral form if none exists. Requires the `hiringProcessMetadataRead` permission.

Resources

state(infinite)— Ashby referral form state

04Previous Versions1

2026.10.29.1MITOct 29, 2026

Added: candidate, candidate_tag, application, application_feedback, application_feedback_request, application_form, application_hiring_team_role, referral, referral_form, assessment, file

05Stats

100 / 100

Downloads

Archive size

63.0 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Docs keep secrets in a vault1/1earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License2/2earned
Verified public repository2/2earned

Repository

https://github.com/keeb/swamp-ashby

06Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64 windows · x86_64

07Labels

#ashby #ats #recruiting #candidates #applications #referrals