Ashby/offers
@keeb/ashby/offersv2026.10.29.2
01README
Ashby offers: offer processes, offer versions, approvals and decisions
02Release Notes
- Updated: offer
- 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
03Behaviors
@keeb/ashby/offers/offerv2026.10.29.2offer.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| offerProcessId? | string | The id of the offer process associated with the offer you're creating. This value is the id included in the response of the `offerProcess.start` API. Sent by create only; offer.update does not accept it. |
| offerFormId? | string | The id of the form associated with the offer. This value is the id included in the response of the `offer.start` API. Sent by create only; offer.update does not accept it. |
| offerForm? | object | The offer form submission |
| excludeFormDefinition? | boolean | If true, omit the form definition from the response. Also sent by sync. |
| apiKey? | string | 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 | 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 | Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it. |
fn create()
Create a offer from the model's global arguments (offer.create). Creates a new Offer Requires the `offersWrite` permission.
fn get(offerId: string, excludeFormDefinition?: boolean, expand?: object)
Get a offer and record it as this model's state (offer.info). Returns details about a single offer by id. Requires the `offersRead` permission.
| Argument | Type | Description |
|---|---|---|
| offerId | string | The id of the offer to fetch |
| excludeFormDefinition? | boolean | If true, omit the form definition from the response. |
| expand? | object | Additional data to include in the response. |
fn lookup(syncToken?: string, createdAfter?: number, offerStatus?: array, acceptanceStatus?: array, applicationId?: string, approvalStatus?: array, max_items?: number)
List offer records and record each as a data artifact (offer.list; capped at 500 by default; writes a offer_lookup record with the coverage of the walk and the sync token)
| Argument | Type | Description |
|---|---|---|
| syncToken? | string | A sync token to retrieve only offers updated since the last sync. Obtained from a previous list response. |
| createdAfter? | number | The API will return data after this date, expressed as milliseconds since the Unix epoch. |
| offerStatus? | array | When supplied, only offers with provided offer-status(es) will be returned. Array must contain at least one value. |
| acceptanceStatus? | array | When supplied, only offers with provided acceptance-status(es) will be returned. Array must contain at least one value. |
| applicationId? | string | If provided, only returns the offers for the application with the supplied id |
| approvalStatus? | array | When supplied, only offers whose latest version has one of the provided approval status(es) will be returned. Array must contain at least one value. This filter currently matches imported offers only; it does not yet match approvals made in Ashby. |
| max_items? | number | 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 offer_lookup record reports truncated: true. |
fn update()
Apply the model's global arguments to the stored offer (offer.update). Run create or get first.
fn sync()
Sync the stored offer from Ashby (offer.info); records status not_found when it is gone. Sends the model's excludeFormDefinition too.
fn approve(offerVersionId: string, approvalStepId?: string, userId?: string, comment?: string, excludeFormDefinition?: boolean)
offer.approve: Approves an offer or a specific approval step within an offer's approval process. Requires the `offersWrite` permission.
| Argument | Type | Description |
|---|---|---|
| offerVersionId | string | The id of the offer version that needs approval. This can be obtained as the `entityId` from the `approval.list` endpoint. |
| approvalStepId? | string | The id of the specific approval step to approve. If provided, `userId` must also be provided. If omitted, the entire offer approval process will be approved. This can be obtained from the `approval.list` endpoint. |
| userId? | string | The id of the user approving the step. Required if `approvalStepId` is provided. Must be an approver for the specified approval step. |
| comment? | string | An optional comment to record with the approval. Only supported when `approvalStepId` and `userId` are provided. |
| excludeFormDefinition? | boolean | If true, omit the form definition from the response. |
fn reject(offerVersionId: string, approvalStepId: string, userId: string, comment?: string, excludeFormDefinition?: boolean)
offer.reject: Rejects the current step in an offer's approval process. Requires the `offersWrite` permission.
| Argument | Type | Description |
|---|---|---|
| offerVersionId | string | The id of the offer version to reject. This can be obtained as the `entityId` from the `approval.list` endpoint. |
| approvalStepId | string | The id of the current approval step. This can be obtained from the `approval.list` endpoint. |
| userId | string | The id of a user who is an approver for the current approval step. |
| comment? | string | An optional comment to record with the rejection. |
| excludeFormDefinition? | boolean | If true, omit the form definition from the response. |
fn set_decided_at(offerId: string, decidedAt: string, excludeFormDefinition?: boolean)
offer.setDecidedAt: Updates an offer's decidedAt timestamp. Requires the `offersWrite` permission.
| Argument | Type | Description |
|---|---|---|
| offerId | string | The id of the offer whose decided at timestamp should be updated. |
| decidedAt | string | The time the offer was accepted or declined. |
| excludeFormDefinition? | boolean | If true, omit the form definition from the response. |
fn set_status(offerId: string, acceptanceStatus: enum, excludeFormDefinition?: boolean)
offer.setStatus: Updates an offer's acceptance status. Requires the `offersWrite` permission.
| Argument | Type | Description |
|---|---|---|
| offerId | string | The id of the offer whose status should be updated. |
| acceptanceStatus | enum | The offer acceptance status. Ashby derives the offer status from this value. |
| excludeFormDefinition? | boolean | If true, omit the form definition from the response. |
fn start(offerProcessId: string)
offer.start: The offer.start endpoint creates and returns an offer version instance that can be filled out and submitted using the `offer.create` endpoint. Requires the `offersWrite` permission.
| Argument | Type | Description |
|---|---|---|
| offerProcessId | string | The ID of the offer process to start. This value is the id included in the response of the `offerProcess.start` API. |
fn start_approval_process(offerVersionId: string, note?: string, excludeFormDefinition?: boolean)
offer.startApprovalProcess: Starts the approval process for an offer in a "WaitingOnApprovalStart" state. Once started, the approval is sent to the configured approvers. Requires the `offersWrite` permission.
| Argument | Type | Description |
|---|---|---|
| offerVersionId | string | The id of the offer version whose approval process should be started |
| note? | string | Optional note to attach to the approval request |
| excludeFormDefinition? | boolean | If true, omit the form definition from the response. |
Resources
state(infinite)— Ashby offer state
offer_lookup(infinite)— Ashby offer lookup coverage — whether the walk exhausted the collection, and the sync token for the next one
offer_action(infinite)— Ashby offer action result, one per action
@keeb/ashby/offers/offer-processv2026.10.29.1offer_process.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiKey? | string | 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 | 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 | Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it. |
fn start(applicationId: string)
offerProcess.start: Starts an offer process for a candidate. Requires the `offersWrite` permission.
| Argument | Type | Description |
|---|---|---|
| applicationId | string | The id of the application to start an offer process for |
Resources
state(infinite)— Ashby offer process state
offer_process_action(infinite)— Ashby offer process action result, one per action
04Previous Versions
2026.10.29.1MIT
- Added: offer, offer_process
05Stats
A
100 / 100
Downloads
0
Archive size
19.8 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-ashby06Platforms
07Labels