Ashby/organization

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

01README

Ashby organization: users and interviewer settings, brands, custom fields, webhooks, reports, the audit log, API key info and API versions

02Release Notes

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

03Behaviors8

@keeb/ashby/organization/api-keyv2026.10.29.1api_key.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 api key and record it as this model's state (apiKey.info). Returns details for the API key used to make the request. Requires the `apiKeysRead` permission.

Resources

state(infinite)— Ashby api key state

@keeb/ashby/organization/audit-logv2026.10.29.1audit_log.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(startDate?: string, endDate?: string, actorIds?: array, targetIds?: array, targetTypes?: array, categories?: array, channels?: array, max_items?: number)

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

Argument	Type	Required	Description
startDate?	string	no	ISO 8601 start of the date window (UTC). When omitted, defaults to 24 hours before endDate. When only startDate is supplied, endDate defaults to startDate plus 24 hours (not until now) — use both bounds for a custom span.
endDate?	string	no	ISO 8601 end of the date window (UTC). When omitted with startDate, defaults to startDate plus 24 hours; when both are omitted, defaults to the current time.
actorIds?	array	no	Restricts results to entries whose actor id is one of these values. An empty array is ignored, same as omitting this field. Max 100 items.
targetIds?	array	no	Restricts results to entries whose target object id is one of these values. Combined with other filters using AND (all conditions must match). An empty array is ignored. Max 100 items.
targetTypes?	array	no	Restricts results to entries whose target type is one of these values (e.g. "job", "app_user"). When both targetTypes and categories are supplied, matching uses OR (entries that match either filter). Combined with targetIds and actorIds using AND. An empty array is ignored. Max 100 items.
categories?	array	no	Restricts results to entries in one of categories (e.g. "JobStatusChanged"). Max 100 items. See the Audit Log Vocabulary guide.
channels?	array	no	Restricts results to entries that came through one of these channels. Entries with no channel recorded never match. Combined with other filters using AND. An empty array is ignored. See the Audit Log Vocabulary guide.
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 audit_log_lookup record reports truncated: true.

Resources

state(infinite)— Ashby audit log state

audit_log_lookup(infinite)— Ashby audit log lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/organization/brandv2026.10.29.1brand.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 brand records and record each as a data artifact (brand.list; capped at 500 by default; writes a brand_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 brand_lookup record reports truncated: true.

Resources

state(infinite)— Ashby brand state

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

@keeb/ashby/organization/custom-fieldv2026.10.29.1custom_field.ts

Global Arguments

Argument	Type	Required	Description
fieldType?	enum	no	The type of field being created. This value is case-sensitive.
objectType?	enum	no	The type of object the field can be associated with.
title?	string	no	The name of the field
description?	string	no	A description for the field
selectableValues?	array	no	Required when the field type is ValueSelect or MultiValueSelect. An array of selectable values for the field.
isDateOnlyField?	boolean	no	Only applies to fields with a fieldType of Date. Whether or not the field includes content other than a date.
isExposableToCandidate?	boolean	no	Determines whether the field can be exposed to a candidate in certain contexts. In order for a custom field to be available in an email template this value must be true.
isPrivate?	boolean	no	Whether the custom field should be private.
isEditableOnlyViaPublicApi?	boolean	no	Whether the custom field's value can only be edited through the API. Supported for Job, Job Posting and Opening custom fields when enabled for the organization.
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 custom field from the model's global arguments (customField.create). Create a new custom field. Requires the `hiringProcessMetadataWrite` permission.

fn get(customFieldId?: string, referenceIdentifier?: string)

Get a custom field and record it as this model's state (customField.info). Get information about a custom field. Requires the `hiringProcessMetadataRead` permission.

Argument	Type	Required	Description
customFieldId?	string	no	The id of the custom field to fetch
referenceIdentifier?	string	no	Beta. This field is in beta and may not be available for all organizations. The reference ID assigned to the custom field, for example cost_center. Use the value exactly as saved.

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

List custom field records and record each as a data artifact (customField.list; capped at 500 by default; writes a custom_field_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 custom fields updated since the last sync. Obtained from a previous list response.
includeArchived?	boolean	no	If true, archived custom fields will 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 custom_field_lookup record reports truncated: true.

fn sync()

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

fn set_reference_identifier(customFieldId: string, referenceIdentifier?: string, expectedReferenceIdentifier?: string)

customField.setReferenceIdentifier (Beta): Assign, change, or remove a custom field's reference ID. Read the current ID with `customField.info` and pass it as `expectedReferenceIdentifier` (`null` if unset). Pass `referenceIdentifier: null` to remove the ID. A removed ID can be reused. If another field holds the ID, `errorInfo.meta.conflictingCustomFieldId` identifies it when this API key can access that field.

Argument	Type	Required	Description
customFieldId	string	yes	The UUID of the custom field definition to update.
referenceIdentifier?	string	no	Beta. This field is in beta and may not be available for all organizations. The new reference ID. Pass null to clear the current reference ID.
expectedReferenceIdentifier?	string	no	The exact current reference ID returned by customField.info or customField.list. Pass null for initial assignment. A mismatch rejects the update to prevent overwriting a concurrent change.

fn set_value(objectId: string, objectType: enum, fieldId?: string, referenceIdentifier?: string, fieldValue?: union)

customField.setValue: Set the value of a custom field for a given object. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
objectId	string	yes	The id of the object the field value is being set on.
objectType	enum	yes	The type of object the field is associated with.
fieldId?	string	no	The unique id of the Custom Field definition for the field
referenceIdentifier?	string	no	Beta. This field is in beta and may not be available for all organizations. The reference ID assigned to the custom field, for example cost_center. Use the value exactly as saved.
fieldValue?	union	no	The value to store in the field. Pass `null` to clear the current value. The accepted non-null type depends on the custom field\

fn set_values(objectId: string, objectType: enum, values: array)

customField.setValues: Set the values of multiple custom fields for a given object in a single call. This is the recommended approach when updating multiple fields on the same object to avoid race conditions that can occur with concurrent `customField.setValue` calls. Requires the `candidatesWrite` permission.

Argument	Type	Required	Description
objectId	string	yes	The id of the object the field values are being set on.
objectType	enum	yes	The type of object the fields are associated with.
values	array	yes	Array of custom field updates to apply

fn update_selectable_values(customFieldId?: string, referenceIdentifier?: string, selectableValues: array)

customField.updateSelectableValues: Update the selectable values for a custom field. Requires the `hiringProcessMetadataWrite` permission.

Argument	Type	Required	Description
customFieldId?	string	no	The id of the custom field to update
referenceIdentifier?	string	no	Beta. This field is in beta and may not be available for all organizations. The reference ID assigned to the custom field, for example cost_center. Use the value exactly as saved.
selectableValues	array	yes	An array of selectable values to merge with the existing values. Only `label`, `value`, and optionally `isArchived` should be provided.

Resources

state(infinite)— Ashby custom field state

custom_field_lookup(infinite)— Ashby custom field lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

custom_field_action(infinite)— Ashby custom field action result, one per action

@keeb/ashby/organization/reportv2026.10.29.1report.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 generate(reportId: string, includeHeadersInData?: boolean, resultStyle?: enum, requestId?: string, waitForCompletion?: boolean, pollIntervalSeconds?: number, timeoutSeconds?: number)

report.generate: Generates a new report or polls the status of an existing report generation. Requires the `reportsRead` permission.

Argument	Type	Required	Description
reportId	string	yes	The ID of the report
includeHeadersInData?	boolean	no	When true (default), column headers are included as the first row in the data array. When false, headers are only in the columnNames property.
resultStyle?	enum	no	How completed report data is returned. "inline" (default) embeds the data in the response; "url" returns a short-lived presigned S3 download URL instead. Requires includeHeadersInData to be true (or omitted) when "url".
requestId?	string	no	Request ID for polling existing report generation status.
waitForCompletion?	boolean	no	Poll until the report is complete or failed (default true). Set false to record the first status.
pollIntervalSeconds?	number	no	Seconds between polls (default 1, as Ashby recommends).
timeoutSeconds?	number	no	Give up polling after this many seconds (default 300).

fn synchronous(reportId: string, includeHeadersInData?: boolean, resultStyle?: enum)

report.synchronous: Retrieves report data synchronously. Requires the `reportsRead` permission.

Argument	Type	Required	Description
reportId	string	yes	The ID of the report
includeHeadersInData?	boolean	no	When true (default), column headers are included as the first row in the data array. When false, headers are only in the columnNames property.
resultStyle?	enum	no	How completed report data is returned. "inline" (default) embeds the data in the response; "url" returns a short-lived presigned S3 download URL instead. Requires includeHeadersInData to be true (or omitted) when "url".

Resources

state(infinite)— Ashby report state

report_action(infinite)— Ashby report action result, one per action

@keeb/ashby/organization/userv2026.10.29.1user.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(userId: string)

Get a user and record it as this model's state (user.info). Retrieves detailed information about a specific user by their ID. Requires the `organizationRead` permission.

Argument	Type	Required	Description
userId	string	yes	The unique identifier for the user

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

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

Argument	Type	Required	Description
includeDeactivated?	boolean	no	Whether to include deactivated users in the results. Defaults to false.
syncToken?	string	no	A sync token to retrieve only users 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 user_lookup record reports truncated: true.

fn sync()

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

fn create_interviewer_pause(userId: string, startsAt?: string, endsAt?: string, comment?: string)

user.createInterviewerPause: Creates an interviewer pause for a user. While paused, the user will not be scheduled for interviews. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
userId	string	yes	The id of the user to pause.
startsAt?	string	no	The start date and time of the pause. Defaults to the current time if not provided.
endsAt?	string	no	The end date and time of the pause. If not provided, the pause is indefinite.
comment?	string	no	An optional comment describing the reason for the pause.

fn delete_interviewer_pause(interviewerPauseId: string)

user.deleteInterviewerPause: Deletes an interviewer pause. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
interviewerPauseId	string	yes	The id of the interviewer pause to delete.

fn interviewer_settings(userId: string)

user.interviewerSettings: Get interviewer settings for a user. Requires the `organizationRead` permission.

Argument	Type	Required	Description
userId	string	yes	The id of the user to get interviewer settings for

fn list_interviewer_pauses(userId: string)

user.listInterviewerPauses: Lists all active or scheduled interviewer pauses for a user. Requires the `organizationRead` permission.

Argument	Type	Required	Description
userId	string	yes	The id of the user to list pauses for.

fn search(email: string)

user.search: Searches for users by email address. Requires the `organizationRead` permission.

Argument	Type	Required	Description
email	string	yes	The email address to search for

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

user.setCustomFieldValue: Set the value of a custom field on an employee. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
userId	string	yes	The id of the employee to set the custom field value for
fieldId?	string	no	The unique id of the Custom Field definition for the field
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	The value to store in the field. Type depends on the custom field type (boolean, string, number, object, etc.) - Location field: An object with the following properties: `{ country: "USA", city: "San Francisco", region: "California" }`. You may provide any combination of these properties and we will attempt to geocode the location. For best results, provide all three properties.

fn set_custom_field_values(userId: string, values: array)

user.setCustomFieldValues: Set the values of multiple custom fields on an employee in a single call. This is the recommended approach when updating multiple fields on the same employee to avoid race conditions that can occur with concurrent `user.setCustomFieldValue` calls. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
userId	string	yes	The id of the employee to set custom field values for
values	array	yes	Array of custom field updates to apply

fn update_interviewer_settings(userId: string, dailyLimit?: number, weeklyLimit?: number)

user.updateInterviewerSettings: Update interviewer settings for a user. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
userId	string	yes	The id of the user to update interviewer settings for
dailyLimit?	number	no	Maximum number of interviews per day for this interviewer
weeklyLimit?	number	no	Maximum number of interviews per week for this interviewer

Resources

state(infinite)— Ashby user state

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

user_action(infinite)— Ashby user action result, one per action

@keeb/ashby/organization/versionv2026.10.29.1version.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 version records and record each as a data artifact (version.list; capped at 500 by default; writes a version_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 version_lookup record reports truncated: true.

Resources

state(infinite)— Ashby version state

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

@keeb/ashby/organization/webhookv2026.10.29.2webhook.ts

Global Arguments

Argument	Type	Required	Description
webhookType?	enum	no	The type of webhook to create. Sent by create only; webhook.update does not accept it.
requestUrl?	string	no	The URL the webhook will send requests to
secretToken?	string	no	The secret token used to sign the webhook request. See our documentation here for more information.
enabled?	boolean	no	Whether or not the webhook setting is enabled. Sent by update only; webhook.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 webhook from the model's global arguments (webhook.create). Creates a webhook setting. Requires the `apiKeysWrite` permission.

fn get(webhookId: string)

Get a webhook and record it as this model's state (webhook.info). Retrieves information about a specific webhook setting by its ID. Requires the `apiKeysRead` permission.

Argument	Type	Required	Description
webhookId	string	yes	The id of the webhook setting to retrieve

fn update()

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

fn delete(id: string)

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

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

fn sync()

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

Resources

state(infinite)— Ashby webhook state

04Previous Versions1

2026.10.29.1MITOct 29, 2026

Added: user, brand, custom_field, webhook, report, audit_log, api_key, version

05Stats

100 / 100

Downloads

Archive size

38.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 #users #custom-fields #webhooks #reports #admin