# Nash

> Delivery orchestration platform for managing multi-courier last-mile delivery via orders and jobs, with real-time tracking, automatic dispatch, and external-identifier-based idempotent operations.

Source: https://cotera.co/docs/reference/tools/individual-tools/nash

---

**Authentication Type:** API Key\
**Description:** Nash (usenash.com) is a delivery orchestration platform that connects your business to courier networks for last-mile delivery. Nash exposes two complementary resource types — **orders** and **jobs** — that represent different stages of the delivery lifecycle. Manage delivery requests, track courier status in real time, dispatch automatically, and integrate using your own external identifiers for idempotent workflows.

**Orders vs. Jobs:** An **order** represents pre-dispatch delivery details — the pickup/dropoff locations, timing, and quotes from courier providers. When an order is confirmed and dispatched, Nash creates a **job** that tracks the live delivery. Job responses contain the delivery status under `tasks[].deliveries[].status`. You can work with orders through the `/v1/order` and `/v1/orders` API endpoints, and with jobs through `/v1/jobs`.

***

## Authentication

To authenticate, you need a Nash API key:

1. Log in to your [Nash dashboard](https://app.usenash.com)
2. Navigate to **Settings → API Keys** and generate a key
3. Provide it as the `apiKey` credential field when connecting Nash in Cotera

Your key is sent as a Bearer token on every request:

```
Authorization: Bearer <your-api-key>
```

**Optional — Organization ID (`orgId`):** If your account belongs to multiple Nash organizations, provide the `orgId` credential field. Nash passes it as the `Nash-Org-Id` header to scope requests to the correct organization. Leave blank for single-org accounts.

**Optional — Base URL (`baseUrl`):** Nash provides four API environments:

| Environment            | Base URL                                         |
| ---------------------- | ------------------------------------------------ |
| Production (default)   | `https://api.usenash.com`                        |
| Sandbox                | `https://api.sandbox.usenash.com`                |
| Production (Australia) | `https://api.ap-southeast-2.usenash.com`         |
| Sandbox (Australia)    | `https://api.sandbox.ap-southeast-2.usenash.com` |

Set `baseUrl` to switch environments. If omitted, requests go to Production.

***

## Orders

A Nash **order** represents a delivery request before it is dispatched — it holds pickup/dropoff details, timing, courier quotes, and configuration. When an order is confirmed and autodispatched, Nash creates a job to track the live delivery.

Use these tools to manage the full order lifecycle: create orders, fetch quotes, confirm, dispatch, and archive.

### List Orders

List Nash orders with optional filters and pagination.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (nullable): Max orders to return (default 25, max 100).
* **offset** `number` (nullable): Pagination offset.
* **sortBy** `string` (nullable): Field to sort by (e.g. `created_at`).
* **sortDirection** `string` (nullable): Sort direction: `ASC` or `DESC`.
* **startDate** `string` (nullable): Filter orders created after this ISO 8601 datetime.
* **endDate** `string` (nullable): Filter orders created before this ISO 8601 datetime.
* **deliveryStatuses** `string` (nullable): Comma-separated delivery statuses to filter by.
* **search** `string` (nullable): Free-text search across orders.

**Returns:**

* **orders** `array`: Array of order summary objects.
* **total** `number` (nullable): Total count of matching orders.

**Example Usage:**

```json
{
  "limit": 50,
  "deliveryStatuses": "pending,confirmed",
  "startDate": "2024-01-01T00:00:00Z"
}
```

***

### Get Order

Retrieve a Nash order by its ID, including delivery details and current status.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (required): Nash order ID.

**Returns:**

* **order** `object`: Full order payload with pickup/dropoff details, quotes, and status.

**Example Usage:**

```json
{
  "id": "order_abc123"
}
```

***

### Create Order

Create a new Nash order with pickup and dropoff details.

**Operation Type:** Mutation (Write)

**Parameters:**

* **orderData** `object` (required): Order creation payload. Must include pickup/dropoff location details, contact information, and pickup/dropoff times. See the [Nash API reference](https://docs.usenash.com/api-reference/order/order) for the full schema.

**Returns:**

* **order** `object`: The created order with ID, status, and available quotes.

**Example Usage:**

```json
{
  "orderData": {
    "pickup": {
      "name": "Warehouse A",
      "address": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US",
      "phone": "+14155550001"
    },
    "dropoff": {
      "name": "Customer",
      "address": "456 Market St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "+14155550002"
    },
    "pickup_time": "2024-07-24T14:00:00Z",
    "dropoff_time": "2024-07-24T16:00:00Z"
  }
}
```

***

### Update Order

Update an existing Nash order by ID (pickup/dropoff times, addresses, metadata).

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Nash order ID to update.
* **updateData** `object` (required): Partial update fields — pickup/dropoff times, addresses, metadata, etc.

**Returns:**

* **order** `object`: The updated order object.

***

### Archive Order

Archive a Nash order by its ID. Archived orders are soft-deleted and no longer active.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Nash order ID to archive.

**Returns:**

* **order** `object`: The archived order.

***

### Unarchive Order

Unarchive a previously archived Nash order, making it active again.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Nash order ID to unarchive.

**Returns:**

* **order** `object`: The unarchived order with updated status.

***

### Confirm Order

Confirm a Nash order by its ID, locking in the delivery details.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Nash order ID to confirm.

**Returns:**

* **order** `object`: The confirmed order.

***

### Autodispatch Order

Automatically dispatch a Nash order using the organization's configured dispatch strategy.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Nash order ID to autodispatch.

**Returns:**

* **order** `object`: The dispatched order with selected provider and accepted quote.

***

### Get Order Quotes

Fetch available courier quotes for a delivery request without committing to a delivery. Use this to compare providers and pricing before creating or confirming an order.

**Operation Type:** Mutation (Write)

**Parameters:**

* **quoteRequest** `object` (required): Quote request payload including pickup/dropoff details. See the [Nash API reference](https://docs.usenash.com/api-reference/order/order) for the full schema.

**Returns:**

* **quotes** `object`: Available courier quotes with pricing and estimated delivery times.

***

### Refresh Order Quotes

Refresh the available courier quotes for an existing Nash order to get updated pricing and availability.

**Operation Type:** Mutation (Write)

**Parameters:**

* **refreshRequest** `object` (required): Refresh quotes request payload. See the [Nash API reference](https://docs.usenash.com/api-reference/order/order) for the full schema.

**Returns:**

* **result** `object`: Updated quotes for the order.

***

### Get Order Documents

Retrieve documents associated with a Nash order, such as proof of delivery or shipping labels.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (required): Nash order ID to retrieve documents for.

**Returns:**

* **documents** `object`: Documents associated with the order.

***

### Upsert Order By External ID

Create or update a Nash order using your own external identifier (idempotent create-or-update).

**Operation Type:** Mutation (Write)

**Parameters:**

* **externalId** `string` (required): Your external order identifier. If an order with this ID exists it will be updated; otherwise a new order is created.
* **orderData** `object` (required): Order payload (same schema as Create Order). Include `autodispatch: true` to dispatch immediately after creation/update.

**Returns:**

* **order** `object`: The created or updated order.

***

## Jobs

A Nash **job** represents an active delivery — it is created when an order is confirmed and dispatched. Jobs contain one or more tasks (pickup + dropoff pairs), quotes from courier providers, and the selected delivery. Use these tools to monitor and manage the full delivery lifecycle after dispatch.

**Delivery status** is nested inside the job response (under `tasks[].deliveries[].status`). There is no separate status endpoint; use **Get Job** or **Refresh Job** to poll the current delivery status.

### List Jobs

List Nash delivery jobs with optional filters and pagination.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (nullable): Max jobs to return (default 25, max 100).
* **offset** `number` (nullable): Pagination offset.
* **sortBy** `string` (nullable): Field to sort by (e.g. `created_at`).
* **sortDirection** `string` (nullable): Sort direction: `ASC` or `DESC`.
* **startDate** `string` (nullable): Filter jobs created after this ISO 8601 datetime.
* **endDate** `string` (nullable): Filter jobs created before this ISO 8601 datetime.
* **deliveryStatuses** `string` (nullable): Comma-separated delivery statuses to filter by.
* **search** `string` (nullable): Free-text search across jobs.

**Returns:**

* **jobs** `array`: Array of job summary objects.
* **total** `number` (nullable): Total count of matching jobs.

**Example Usage:**

```json
{
  "limit": 50,
  "deliveryStatuses": "pending,in_progress",
  "startDate": "2024-01-01T00:00:00Z"
}
```

***

### Get Job

Retrieve a Nash delivery job by its ID, including tasks, deliveries, quotes, and current delivery status.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (required): Nash job ID.
* **compressedPayload** `boolean` (nullable): When `true`, excludes quotes arrays to reduce response size.

**Returns:**

* **job** `object`: Full job payload with tasks, deliveries, quotes, and configuration. Delivery status is at `tasks[].deliveries[].status`.

**Example Usage:**

```json
{
  "id": "job_abc123",
  "compressedPayload": true
}
```

***

### Create Job

Create a new Nash delivery job with pickup and dropoff details.

**Operation Type:** Mutation (Write)

**Parameters:**

* **jobData** `object` (required): Job creation payload. Must include pickup/dropoff location details, contact information, and pickup/dropoff times. See the [Nash API reference](https://docs.usenash.com/api-reference/job/jobs) for the full schema.

**Returns:**

* **job** `object`: The created job with ID, status, quotes, and tasks.

**Example Usage:**

```json
{
  "jobData": {
    "pickup": {
      "name": "Warehouse A",
      "address": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US",
      "phone": "+14155550001"
    },
    "dropoff": {
      "name": "Customer",
      "address": "456 Market St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "+14155550002"
    },
    "pickup_time": "2024-07-24T14:00:00Z",
    "dropoff_time": "2024-07-24T16:00:00Z"
  }
}
```

***

### Update Job

Update an existing Nash delivery job by ID (pickup/dropoff times, addresses, metadata).

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Nash job ID to update.
* **updateData** `object` (required): Partial update fields — pickup/dropoff times, addresses, metadata, etc.

**Returns:**

* **job** `object`: The updated job object.

***

### Cancel Job

Cancel an active Nash delivery job and its associated deliveries.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Nash job ID to cancel.

**Returns:**

* **job** `object`: The cancelled job with updated status.

***

### Autodispatch Job

Automatically dispatch a Nash delivery job using the organization's configured dispatch strategy.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Nash job ID to autodispatch.

**Returns:**

* **job** `object`: The dispatched job with selected provider and accepted quote.

***

### Refresh Job

Refresh a Nash job status by fetching the latest information from the delivery provider.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Nash job ID to refresh.

**Returns:**

* **job** `object`: The job with the latest courier/delivery status synced from the provider.

***

## Jobs by External Identifier

These tools let you manage jobs using your own external IDs instead of Nash-assigned IDs. This enables idempotent create-or-update workflows keyed to your order system.

### Get Job By External ID

Retrieve a Nash delivery job using your own external identifier.

**Operation Type:** Query (Read)

**Parameters:**

* **externalIdentifier** `string` (required): Your external order/job identifier as stored in Nash.

**Returns:**

* **job** `object`: Full job payload.

***

### Upsert Job By External ID

Create or update a Nash delivery job using your own external identifier (idempotent create-or-update).

**Operation Type:** Mutation (Write)

**Parameters:**

* **externalIdentifier** `string` (required): Your external order/job identifier. If a job with this ID exists it will be updated; otherwise a new job is created.
* **jobData** `object` (required): Job payload (same schema as Create Job). Include `autodispatch: true` to dispatch immediately after creation/update.

**Returns:**

* **job** `object`: The created or updated job.

***

### Cancel Job By External ID

Cancel a Nash delivery job identified by your own external identifier.

**Operation Type:** Mutation (Write)

**Parameters:**

* **externalIdentifier** `string` (required): Your external order/job identifier for the job to cancel.

**Returns:**

* **job** `object`: The cancelled job with updated status.

***

### Autodispatch Job By External ID

Automatically dispatch a Nash delivery job identified by your own external identifier.

**Operation Type:** Mutation (Write)

**Parameters:**

* **externalIdentifier** `string` (required): Your external order/job identifier for the job to autodispatch.

**Returns:**

* **job** `object`: The autodispatched job with provider assigned.

***

## Common Use Cases

**Order-First Delivery Workflow:**

* Fetch quotes with **Get Order Quotes** to compare providers before committing
* Create an order with **Create Order** or use **Upsert Order By External ID** (idempotent — safe to retry) to key the order to your own identifier
* Confirm the order with **Confirm Order**, then dispatch with **Autodispatch Order**
* Once dispatched, Nash creates a job — use **List Jobs** or **Get Job** to track the live delivery status

**Job-Based Delivery Workflow:**

* Create a job directly with **Upsert Job By External ID** (idempotent — safe to retry)
* Autodispatch immediately by including `autodispatch: true` in the job payload, or call **Autodispatch Job** as a separate step
* Poll delivery status with **Get Job** or trigger a live sync with **Refresh Job**

**Status Monitoring:**

* Use **List Orders** or **List Jobs** to find records by date range and delivery status for batch monitoring
* Call **Get Job** on specific IDs and inspect `tasks[].deliveries[].status` for current courier status
* Delivery status is always embedded in the job response — use **Refresh Job** to sync with the courier's latest state

**Cancellations:**

* Cancel a job by Nash job ID with **Cancel Job**
* Cancel by your own order ID with **Cancel Job By External ID** — no need to look up the Nash ID first

**Documents:**

* Retrieve proof of delivery and shipping labels with **Get Order Documents**