openapi: 3.1.0
info:
title: Nash AI Functions Job API
version: 1.0.0
description: LLM-backed domain tools
servers:
- url: https://api.sandbox.usenash.com
description: Sandbox API
- url: https://api.sandbox.ap-southeast-2.usenash.com
description: Sandbox API (Australia)
- url: https://api.usenash.com
description: Production API
- url: https://api.ap-southeast-2.usenash.com
description: Production API (Australia)
tags:
- name: Job
description: Job
x-nash-topic: wismo
paths:
/v1/jobs:
get:
tags:
- Job
summary: List/Search Jobs
description: List jobs (deliveries) with filters, sorting, and pagination. Returns a slim payload suitable for discovery; use GET /v1/jobs/<id> for full details.
operationId: list_jobs_v1_jobs_get
parameters:
- name: limit
in: query
required: false
schema:
title: Limit
maximum: 100
minimum: 1.0
type: integer
default: 25
example: 25
example: 25
- name: offset
in: query
required: false
schema:
title: Offset
minimum: 0.0
type: integer
default: 0
example: 0
example: 0
- name: sortBy
in: query
description: Sort field (e.g. created_at, pickup_start_time)
required: false
schema:
title: Sortby
type: string
description: Sort field (e.g. created_at, pickup_start_time)
default: created_at
- name: sortDirection
in: query
description: ASC or DESC
required: false
schema:
title: Sortdirection
type: string
description: ASC or DESC
default: DESC
- name: startDate
in: query
description: Defaults to 3 days ago.
required: false
schema:
title: Startdate
anyOf:
- type: string
format: date-time
- type: 'null'
description: Defaults to 3 days ago.
default: null
- name: endDate
in: query
description: Defaults to 7 days from now so in-flight and scheduled deliveries are included.
required: false
schema:
title: Enddate
anyOf:
- type: string
format: date-time
- type: 'null'
description: Defaults to 7 days from now so in-flight and scheduled deliveries are included.
default: null
- name: deliveryStatuses
in: query
description: Comma-separated delivery statuses (e.g. created,accepted_by_courier,delivered)
required: false
schema:
title: Deliverystatuses
anyOf:
- type: string
- type: 'null'
description: Comma-separated delivery statuses (e.g. created,accepted_by_courier,delivered)
default: null
- name: providerNames
in: query
description: Comma-separated provider names
required: false
schema:
title: Providernames
anyOf:
- type: string
- type: 'null'
description: Comma-separated provider names
default: null
- name: courierNames
in: query
description: Comma-separated courier names
required: false
schema:
title: Couriernames
anyOf:
- type: string
- type: 'null'
description: Comma-separated courier names
default: null
- name: tags
in: query
description: Comma-separated job tags
required: false
schema:
title: Tags
anyOf:
- type: string
- type: 'null'
description: Comma-separated job tags
default: null
- name: packageTags
in: query
description: Comma-separated package tags
required: false
schema:
title: Packagetags
anyOf:
- type: string
- type: 'null'
description: Comma-separated package tags
default: null
- name: pickupStoreLocationIds
in: query
description: Comma-separated
required: false
schema:
title: Pickupstorelocationids
anyOf:
- type: string
- type: 'null'
description: Comma-separated
default: null
- name: dropoffStoreLocationIds
in: query
description: Comma-separated
required: false
schema:
title: Dropoffstorelocationids
anyOf:
- type: string
- type: 'null'
description: Comma-separated
default: null
- name: search
in: query
description: Free-form search across IDs, external identifiers, short reference codes, addresses, and courier/customer names. For an exact match on a single field, use the dedicated filter (e.g. short_reference_code).
required: false
schema:
title: Search
anyOf:
- type: string
- type: 'null'
description: Free-form search across IDs, external identifiers, short reference codes, addresses, and courier/customer names. For an exact match on a single field, use the dedicated filter (e.g. short_reference_code).
default: null
- name: shortReferenceCode
in: query
description: Exact match on the 7-digit short reference code shown on delivery cards. Codes are non-unique; multiple jobs may be returned. When provided, the default date window is widened to 90 days so older jobs are discoverable.
required: false
schema:
title: Shortreferencecode
anyOf:
- type: string
- type: 'null'
description: Exact match on the 7-digit short reference code shown on delivery cards. Codes are non-unique; multiple jobs may be returned. When provided, the default date window is widened to 90 days so older jobs are discoverable.
default: null
- name: customerName
in: query
description: Fuzzy, case-insensitive substring match on the end customer's name (pickup or dropoff full name) over the denormalized task. Use this to locate a delivery when the caller only knows the customer's name. Matches names only — not business names, addresses, or courier names (use `search` for broader free-form matching). When provided, the default date window is widened to 90 days so older deliveries are discoverable.
required: false
schema:
title: Customername
anyOf:
- type: string
- type: 'null'
description: Fuzzy, case-insensitive substring match on the end customer's name (pickup or dropoff full name) over the denormalized task. Use this to locate a delivery when the caller only knows the customer's name. Matches names only — not business names, addresses, or courier names (use `search` for broader free-form matching). When provided, the default date window is widened to 90 days so older deliveries are discoverable.
default: null
- name: isBatch
in: query
description: Filter to batch jobs only
required: false
schema:
title: Isbatch
anyOf:
- type: boolean
- type: 'null'
description: Filter to batch jobs only
default: null
- name: hasNotes
in: query
description: Filter to jobs with notes
required: false
schema:
title: Hasnotes
anyOf:
- type: boolean
- type: 'null'
description: Filter to jobs with notes
default: null
- name: city
in: query
description: Comma-separated pickup/dropoff cities
required: false
schema:
title: City
anyOf:
- type: string
- type: 'null'
description: Comma-separated pickup/dropoff cities
default: null
- name: state
in: query
description: Comma-separated pickup/dropoff states
required: false
schema:
title: State
anyOf:
- type: string
- type: 'null'
description: Comma-separated pickup/dropoff states
default: null
- name: country
in: query
description: Comma-separated pickup/dropoff countries
required: false
schema:
title: Country
anyOf:
- type: string
- type: 'null'
description: Comma-separated pickup/dropoff countries
default: null
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JobsListResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
post:
tags:
- Job
summary: Create Job
description: Create a new delivery job with pickup and dropoff details. A job represents a post-dispatch delivery request. Set quote_request_only=true to get price quotes without dispatching.
operationId: create_job_v1_jobs_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobInputSerializer'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnedJobMixin'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/external_identifier/{externalIdentifier}:
get:
tags:
- Job
summary: Get Job by External Identifier
description: Retrieve a job using your external identifier instead of the Nash job ID. Useful when integrating with external systems that track their own order IDs.
operationId: get_job_by_external_id_v1_jobs_external_identifier__string_externalIdentifier__get
parameters:
- name: externalIdentifier
in: path
description: job external identifier
required: true
schema:
title: Externalidentifier
type: string
description: job external identifier
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnedJobMixin'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
post:
tags:
- Job
summary: Create or Update Job by External Identifier
description: Create a new job or update an existing one using your external identifier. If a job with the given external identifier exists, it is updated; otherwise a new job is created. Set autodispatch=true to automatically dispatch after creation.
operationId: create_or_update_job_by_external_id_v1_jobs_external_identifier__string_externalIdentifier__post
parameters:
- name: externalIdentifier
in: path
description: job external identifier
required: true
schema:
title: Externalidentifier
type: string
description: job external identifier
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobInputSerializerAndAutodispatch'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnedJobMixin'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/external_identifier/{externalIdentifier}/autodispatch:
post:
tags:
- Job
summary: Autodispatch job by external identifier
description: Automatically dispatch an existing job using your external identifier. Requests quotes from providers and selects the best one based on the organization's dispatch strategy.
operationId: autodispatch_job_by_external_id_v1_jobs_external_identifier__string_externalIdentifier__autodispatch_post
parameters:
- name: externalIdentifier
in: path
description: job external identifier
required: true
schema:
title: Externalidentifier
type: string
description: job external identifier
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FullJobPayload'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/external_identifier/{externalIdentifier}/cancel:
post:
tags:
- Job
summary: Cancel Job by External Identifier
description: Cancel an active job using your external identifier. Cancels the delivery with the assigned provider and updates the job status.
operationId: _cancel_job_by_external_identifier_v1_jobs_external_identifier__string_externalIdentifier__cancel_post
parameters:
- name: externalIdentifier
in: path
description: job external identifier
required: true
schema:
title: Externalidentifier
type: string
description: job external identifier
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FullJobPayload'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/{id}:
get:
tags:
- Job
summary: Get Job
description: 'Retrieve a job by its ID, including all job configurations, tasks, deliveries, and quotes. Pass `compressed_payload=true` by default — it drops the quotes and failedQuotes arrays and collapses advancedTask to just its id, which typically shrinks the response 10x+. Only omit it (or pass false) when the caller explicitly needs quote details: pricing, provider selection, or failed-dispatch error messages.'
operationId: get_job_v1_jobs__string_id__get
parameters:
- name: id
in: path
description: job id
required: true
schema:
title: Id
type: string
description: job id
- name: compressedPayload
in: query
description: 'Return a slimmer job payload by excluding the full `quotes` and `failedQuotes` arrays and reducing `advancedTask` to just `{id}`. Prefer `compressed_payload=true` by default for status / ETA / tracking / cancellation flows — it can shrink responses by 10x+ on jobs that shopped many providers. Set to false (or omit) only when the caller needs quote data: pricing breakdowns, provider selection rationale, or failed-dispatch error messages.'
required: false
schema:
title: Compressedpayload
anyOf:
- type: boolean
- type: 'null'
description: 'Return a slimmer job payload by excluding the full `quotes` and `failedQuotes` arrays and reducing `advancedTask` to just `{id}`. Prefer `compressed_payload=true` by default for status / ETA / tracking / cancellation flows — it can shrink responses by 10x+ on jobs that shopped many providers. Set to false (or omit) only when the caller needs quote data: pricing breakdowns, provider selection rationale, or failed-dispatch error messages.'
default: null
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnedJobMixin'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
patch:
tags:
- Job
summary: Update Job by JobID/ExternalIdentifier
description: Update an existing job's details such as pickup/dropoff times, addresses, or metadata. The id can be a Nash job ID or your external identifier.
operationId: update_job_v1_jobs__string_id__patch
parameters:
- name: id
in: path
description: Job ID or External Identifier
required: true
schema:
title: Id
anyOf:
- type: string
- type: 'null'
description: Job ID or External Identifier
- name: jobConfigurationId
in: path
description: Job Configuration ID (for updating a package in a batch job)
required: true
schema:
title: Jobconfigurationid
anyOf:
- type: string
- type: 'null'
description: Job Configuration ID (for updating a package in a batch job)
default: null
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateJobInputSerializer'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnedJobMixin'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/{id}/autodispatch:
post:
tags:
- Job
summary: Autodispatch job
description: Automatically dispatch an existing job using the organization's dispatch strategy. Requests quotes from providers and selects the best one based on configured rules.
operationId: autodispatch_job_v1_jobs__string_id__autodispatch_post
parameters:
- name: id
in: path
description: job id
required: true
schema:
title: Id
type: string
description: job id
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FullJobPayload'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/{id}/rebook:
post:
tags:
- Job
summary: Rebook Job
description: Cancel the existing job and create a new one with updated details. The original job is canceled before the new job is created from the provided data.
operationId: rebook_job_v1_jobs__string_id__rebook_post
parameters:
- name: id
in: path
description: job id
required: true
schema:
title: Id
type: string
description: job id
- name: compressedPayload
in: query
description: 'Return a slimmer job payload by excluding the full `quotes` and `failedQuotes` arrays and reducing `advancedTask` to just `{id}`. Prefer `compressed_payload=true` by default for status / ETA / tracking / cancellation flows — it can shrink responses by 10x+ on jobs that shopped many providers. Set to false (or omit) only when the caller needs quote data: pricing breakdowns, provider selection rationale, or failed-dispatch error messages.'
required: false
schema:
title: Compressedpayload
anyOf:
- type: boolean
- type: 'null'
description: 'Return a slimmer job payload by excluding the full `quotes` and `failedQuotes` arrays and reducing `advancedTask` to just `{id}`. Prefer `compressed_payload=true` by default for status / ETA / tracking / cancellation flows — it can shrink responses by 10x+ on jobs that shopped many providers. Set to false (or omit) only when the caller needs quote data: pricing breakdowns, provider selection rationale, or failed-dispatch error messages.'
default: null
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RebookJobBody'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnedJobMixin'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/{id}/refresh:
post:
tags:
- Job
summary: Refresh job
description: Refresh a job's status by fetching the latest delivery information from the assigned provider. Useful for syncing state when provider webhooks may have been missed.
operationId: refresh_job_v1_jobs__string_id__refresh_post
parameters:
- name: id
in: path
description: job id
required: true
schema:
title: Id
type: string
description: job id
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FullJobPayload'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/{jobId}/cancel:
post:
tags:
- Job
summary: Cancel Job by Job ID
description: Cancel an active job and its associated deliveries. Cancels the delivery with the assigned provider and updates the job status.
operationId: cancel_job_v1_jobs__string_jobId__cancel_post
parameters:
- name: jobId
in: path
description: job id
required: true
schema:
title: Jobid
type: string
description: job id
- name: objectId
in: path
description: Task ID or Job Configuration ID
required: true
schema:
title: Objectid
anyOf:
- type: string
- type: 'null'
description: Task ID or Job Configuration ID
default: null
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FullJobPayload'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/{jobId}/tasks/{taskId}/delivery_incident:
post:
tags:
- Job
summary: Create delivery incident
description: Report a delivery incident such as a damaged package, missing items, or late delivery. Creates an incident record linked to the specified task.
operationId: delivery_incident_v1_jobs__string_jobId__tasks__string_taskId__delivery_incident_post
parameters:
- name: jobId
in: path
description: job id
required: true
schema:
title: Jobid
type: string
description: job id
- name: taskId
in: path
description: task id
required: true
schema:
title: Taskid
type: string
description: task id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeliveryIncidentInputSerializer'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeliveryIncidentOutputSerializer'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/{jobId}/tasks/{taskId}/quotes:
post:
tags:
- Job
summary: Select Quote by Job ID and Task ID
description: 'Select the winning quote for a specific task within a job. Deprecated: prefer the Select Quote endpoint instead.'
operationId: select_quote_task_v1_jobs__string_jobId__tasks__string_taskId__quotes_post
parameters:
- name: jobId
in: path
description: job id
required: true
schema:
title: Jobid
type: string
description: job id
- name: taskId
in: path
description: task id
required: true
schema:
title: Taskid
type: string
description: task id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SelectQuoteInputSerializer'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SelectTaskQuoteOutputSerializer'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/{jobId}/tasks/{taskId}/refresh_quotes:
post:
tags:
- Job
summary: Refresh Quotes by Job ID and Task ID
description: Request fresh price quotes from delivery providers for a specific task. Replaces any existing quotes with updated pricing.
operationId: refresh_quotes_task_v1_jobs__string_jobId__tasks__string_taskId__refresh_quotes_post
parameters:
- name: jobId
in: path
description: job id
required: true
schema:
title: Jobid
type: string
description: job id
- name: taskId
in: path
description: task id
required: true
schema:
title: Taskid
type: string
description: task id
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshQuotesOutputSerializer'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/jobs/{jobId}/{taskId}/reassign:
post:
tags:
- Job
summary: Reassign task by Job ID and Task ID
description: Cancel the current delivery attempt and create a new task for reassignment. A new task is created on the same job configuration, allowing a different provider to fulfill the delivery.
operationId: reassign_task_v1_jobs__string_jobId___string_taskId__reassign_post
parameters:
- name: jobId
in: path
description: job id
required: true
schema:
title: Jobid
type: string
description: job id
- name: taskId
in: path
description: task id
required: true
schema:
title: Taskid
type: string
description: task id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReassignTaskInputSerializer'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnedJobMixin'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/refund-request/{id}:
get:
tags:
- Job
summary: Get Refund Request
description: Retrieve a single refund request by its ID, including status and resolution details.
operationId: get_refund_request_v1_refund_request__string_id__get
parameters:
- name: id
in: path
description: The ID of the refund request.
required: true
schema:
title: Id
type: string
description: The ID of the refund request.
example: rfrq_01234567890123456789
example: rfrq_01234567890123456789
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefundRequestResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/refund-requests:
get:
tags:
- Job
summary: Get Refund Requests by Task ID or Job ID
description: Retrieve all refund requests associated with a task or job. At least one of task_id or job_id must be provided.
operationId: get_refund_requests_v1_refund_requests_get
parameters:
- name: taskId
in: query
description: The task ID to filter by.
required: false
schema:
title: Taskid
anyOf:
- type: string
- type: 'null'
description: The task ID to filter by.
default: null
- name: jobId
in: query
description: The job ID to filter by.
required: false
schema:
title: Jobid
anyOf:
- type: string
- type: 'null'
description: The job ID to filter by.
default: null
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListRefundRequestResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/select_quote:
post:
tags:
- Job
summary: Select Quote
description: Select a delivery quote to dispatch the job to a provider. Selecting a quote creates a delivery and begins the fulfillment process with the chosen provider.
operationId: select_quote_v1_select_quote_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SelectQuoteInputSerializer'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SelectQuoteOutputSerializer'
'422':
description: Unprocessable Content
co
# --- truncated at 32 KB (162 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nash/refs/heads/main/openapi/nash-job-api-openapi.yml