Ashby/sourcing

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

01README

Ashby sourcing: projects, outreach sequences and templates, sources and tracking links, email senders, the email sync blocklist, communication templates and archive reasons

02Release Notes

Updated: project
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

03Behaviors9

@keeb/ashby/sourcing/archive-reasonv2026.10.29.1archive_reason.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(includeArchived?: boolean, max_items?: number)

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

Argument	Type	Required	Description
includeArchived?	boolean	no	When true, includes archived archive reasons in the response. Defaults to false.
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 archive_reason_lookup record reports truncated: true.

Resources

state(infinite)— Ashby archive reason state

archive_reason_lookup(infinite)— Ashby archive reason lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/sourcing/communication-templatev2026.10.29.1communication_template.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(ownershipFilter?: enum, max_items?: number)

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

Argument	Type	Required	Description
ownershipFilter?	enum	no	Limits results by template ownership: org returns organization templates, personal returns the API user's personal templates, and personalAndOrg returns both. Defaults to personalAndOrg.
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 communication_template_lookup record reports truncated: true.

Resources

state(infinite)— Ashby communication template state

communication_template_lookup(infinite)— Ashby communication template lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/sourcing/email-senderv2026.10.29.1email_sender.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 email sender records and record each as a data artifact (emailSender.list; capped at 500 by default; writes a email_sender_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 email_sender_lookup record reports truncated: true.

Resources

state(infinite)— Ashby email sender state

email_sender_lookup(infinite)— Ashby email sender lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/sourcing/email-sync-blocked-addressv2026.10.29.1email_sync_blocked_address.ts

Global Arguments

Argument	Type	Required	Description
addresses?	array	no	The email addresses to add to the blocklist. A malformed address rejects the whole batch.
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 email sync blocked address from the model's global arguments (emailSyncBlockedAddress.create). Adds email addresses to the candidate email sync blocklist. Requires the `organizationWrite` permission.

fn lookup(max_items?: number)

List email sync blocked address records and record each as a data artifact (emailSyncBlockedAddress.list; capped at 500 by default; writes a email_sync_blocked_address_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 email_sync_blocked_address_lookup record reports truncated: true.

fn delete_action(addresses: array)

emailSyncBlockedAddress.delete: Removes email addresses from the candidate email sync blocklist. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
addresses	array	yes	The email addresses to remove from the blocklist. Matching is exact, and addresses that are not on the list are ignored.

Resources

state(infinite)— Ashby email sync blocked address state

email_sync_blocked_address_lookup(infinite)— Ashby email sync blocked address lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

email_sync_blocked_address_action(infinite)— Ashby email sync blocked address action result, one per action

@keeb/ashby/sourcing/projectv2026.10.29.2project.ts

Global Arguments

Argument	Type	Required	Description
title?	string	no	The project's title.
description?	object	no	The project's description. Omission, null, or empty content leaves it unset.
customFields?	array	no	Initial values. Supply every required field. Supports String, LongText, Boolean, Number, Date, ValueSelect, MultiValueSelect, Url and User fields. Requires Project custom fields availability. Discover definitions using customField.list with hiringProcessMetadata:read; User discovery retains organization:read. Sent by create only; project.update does not accept it.
confidential?	boolean	no	Whether the project is confidential. Defaults to false. Requires confidential project availability. Sent by create only; project.update 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 project from the model's global arguments (project.create). Creates a project. The effective actor becomes the author, including authorized on-behalf-of requests. Confidential projects are available on Plus, Legacy Plus, and Enterprise plans. Authors retain access to projects they create. Supply initial customFields for every active required Project custom field definition.

fn get(projectId: string)

Get a project and record it as this model's state (project.info). Retrieves a project by its UUID. Requires one of the `projectsRead` or `candidatesRead` permissions.

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

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

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

Argument	Type	Required	Description
createdAfter?	number	no	The API will return data after this date, which is the time since the unix epoch in milliseconds
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 project_lookup record reports truncated: true.

fn update()

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

fn sync()

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

fn archive(projectId: string)

project.archive: Archives a project. The effective actor must have permission to edit the project, including authorized on-behalf-of requests. Calling this endpoint on an already archived project succeeds. Candidate memberships, history, authorship, confidentiality, descriptions, and custom-field values are preserved. This endpoint does not permanently delete projects or candidates. Requires the `projectsWrite` permission.

Argument	Type	Required	Description
projectId	string	yes	The project's unique identifier.

fn restore(projectId: string)

project.restore: Restores a project. The effective actor must have permission to edit the project, including authorized on-behalf-of requests. Calling this endpoint on an already active project succeeds. Candidate memberships, history, authorship, confidentiality, descriptions, and custom-field values are preserved. This endpoint does not permanently delete projects or candidates. Requires the `projectsWrite` permission.

Argument	Type	Required	Description
projectId	string	yes	The project's unique identifier.

fn search(title: string)

project.search: Search for projects by title. Requires one of the `projectsRead` or `candidatesRead` permissions.

Argument	Type	Required	Description
title	string	yes	The project's title

fn set_custom_field_value(fieldId?: string, referenceIdentifier?: string, fieldValue?: union, projectId: string)

project.setCustomFieldValue: Updates one custom field on a project, including archived projects. Returns the affected entry, including value: null when already empty. The effective actor must have permission to edit the project. Requires Project custom fields availability; private and API-only field permissions apply. Delegated humans may preserve API-only values but cannot change or clear them.

Argument	Type	Required	Description
fieldId?	string	no	An active Project custom field ID.
referenceIdentifier?	string	no	Beta. This field is in beta and may not be available for all organizations. The reference ID assigned to the object. Use the value exactly as saved.
fieldValue?	union	no	Canonical field value. Null clears an optional field, including when already empty.
projectId	string	yes	The project to edit.

fn set_custom_field_values(projectId: string, values: array)

project.setCustomFieldValues: Updates a nonempty batch of distinct custom fields on a project, including archived projects. Returns affected entries in request order, including value: null for cleared fields. Duplicate field IDs are rejected. The effective actor must have permission to edit the project. Requires Project custom fields availability; private and API-only field permissions apply.

Argument	Type	Required	Description
projectId	string	yes	The project to edit.
values	array	yes	Values to replace, in response order. Omitted fields remain unchanged. Use null to clear an optional field.

Resources

state(infinite)— Ashby project state

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

project_action(infinite)— Ashby project action result, one per action

@keeb/ashby/sourcing/sequencev2026.10.29.1sequence.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(sequenceId: string)

Get a sequence and record it as this model's state (sequence.info). Retrieves a candidate's sourcing sequence enrollment when it is visible to the acting user. Requires the `sourcingRead` permission.

Argument	Type	Required	Description
sequenceId	string	yes	The unique identifier for the sequence enrollment

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

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

Argument	Type	Required	Description
candidateId?	string	no	Only return sequence enrollments for this candidate
syncToken?	string	no	A sync token to retrieve only sequence enrollments updated since the last sync
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 sequence_lookup record reports truncated: true.

fn sync()

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

fn add(sequenceTemplateId: string, candidateId: string, applicationId?: string, from?: object, start: boolean)

sequence.add: Enrolls a candidate in a reusable sourcing sequence. Set start to false to create an editable draft, or true to validate and start the sequence immediately. Requires the `sourcingWrite` permission.

Argument	Type	Required	Description
sequenceTemplateId	string	yes	The reusable sourcing sequence template to use
candidateId	string	yes	The candidate to enroll in the sequence
applicationId?	string	no	The candidate's application to use for token resolution
from?	object	no	The sending address to use for every email stage
start	boolean	yes	Whether to validate and start the sequence immediately after creating it

fn cancel(sequenceId: string, reason?: enum)

sequence.cancel: Cancels a running sourcing sequence (campaign) for a candidate. Requires one of the `candidatesWrite` or `sourcingWrite` permissions.

Argument	Type	Required	Description
sequenceId	string	yes	The id of the sequence to cancel
reason?	enum	no	The reason for cancelling the sequence. Defaults to `booked_meeting`.

fn discard(sequenceId: string)

sequence.discard: Permanently discards a NotStarted sourcing sequence draft owned by the acting user. Drafts created with x-on-behalf-of must be discarded using the same user. Requires the `sourcingWrite` permission.

Argument	Type	Required	Description
sequenceId	string	yes	The unique identifier for the draft sequence enrollment

fn start(sequenceId: string)

sequence.start: Validates and starts an existing NotStarted sourcing sequence draft owned by the acting user. Drafts created with x-on-behalf-of must be started with the same acting user. Requires the `sourcingWrite` permission.

Argument	Type	Required	Description
sequenceId	string	yes	The unique identifier for the draft sequence enrollment

fn update_stage(sequenceId: string, stageId: string, subject?: string, body?: object)

sequence.updateStage: Replaces the supplied subject or HTML body of one email stage in a not-started sourcing sequence. At least one of subject or body is required. The reusable sequence template is not changed. Requires the `sourcingWrite` permission.

Argument	Type	Required	Description
sequenceId	string	yes	The unique identifier for the sequence enrollment
stageId	string	yes	The unique identifier for the email stage to update
subject?	string	no	A plain-text subject that replaces the stage's current subject
body?	object	no	The rich-text body that replaces the stage's current body

Resources

state(infinite)— Ashby sequence state

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

sequence_action(infinite)— Ashby sequence action result, one per action

@keeb/ashby/sourcing/sequence-templatev2026.10.29.1sequence_template.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(sequenceTemplateId: string)

Get a sequence template and record it as this model's state (sequenceTemplate.info). Retrieves metadata for a reusable sourcing sequence template visible to the caller. Archived templates may be returned. Message subjects and bodies are not exposed. Requires the `sourcingRead` permission.

Argument	Type	Required	Description
sequenceTemplateId	string	yes	The unique identifier for the sequence template

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

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

Argument	Type	Required	Description
syncToken?	string	no	An opaque token representing the last completed synchronization. The final page returns a token for the next incremental synchronization.
includeArchived?	boolean	no	Whether to include archived templates. Defaults to false.
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 sequence_template_lookup record reports truncated: true.

fn sync()

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

Resources

state(infinite)— Ashby sequence template state

sequence_template_lookup(infinite)— Ashby sequence template lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/sourcing/sourcev2026.10.29.1source.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(includeArchived?: boolean, max_items?: number)

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

Argument	Type	Required	Description
includeArchived?	boolean	no	Whether archived sources should be included in the 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 source_lookup record reports truncated: true.

Resources

state(infinite)— Ashby source state

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

@keeb/ashby/sourcing/source-tracking-linkv2026.10.29.1source_tracking_link.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(includeDisabled?: boolean, sourceId?: string, syncToken?: string, max_items?: number)

List source tracking link records and record each as a data artifact (sourceTrackingLink.list; capped at 500 by default; writes a source_tracking_link_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
includeDisabled?	boolean	no	When true, includes disabled tracking links. Defaults to false.
sourceId?	string	no	Restrict the response to tracking links associated with this source id.
syncToken?	string	no	A sync token to retrieve only tracking links 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 source_tracking_link_lookup record reports truncated: true.

Resources

state(infinite)— Ashby source tracking link state

source_tracking_link_lookup(infinite)— Ashby source tracking link lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

04Previous Versions1

2026.10.29.1MITOct 29, 2026

Added: project, sequence, sequence_template, source, source_tracking_link, email_sender, email_sync_blocked_address, communication_template, archive_reason

05Stats

100 / 100

Downloads

Archive size

33.6 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 #sourcing #outreach #sequences #projects