POST
/
v1
/
jobs
curl --request POST \
  --url https://api.sandbox.usenash.com/v1/jobs \
  --header 'Content-Type: application/json' \
  --data '{
  "pickupAddress": "<string>",
  "pickupAddressComponents": {
    "number": "1600",
    "secondaryNumber": null,
    "street": "Pennsylvania Avenue NW",
    "county": "Washington",
    "city": "Washington",
    "state": "DC",
    "postalCode": "20500",
    "country": "US",
    "latitude": 38.8948949,
    "longitude": -77.0371581
  },
  "pickupLatitude": 123,
  "pickupLongitude": 123,
  "pickupBusinessName": "<string>",
  "pickupFirstName": "<string>",
  "pickupLastName": "<string>",
  "pickupPlaceId": "<string>",
  "pickupStoreLocationId": "<string>",
  "pickupPhoneNumber": "<string>",
  "pickupEmail": "<string>",
  "pickupBarcodes": [
    "<string>"
  ],
  "dropoffAddress": "<string>",
  "dropoffAddressComponents": {
    "number": "1600",
    "secondaryNumber": null,
    "street": "Pennsylvania Avenue NW",
    "county": "Washington",
    "city": "Washington",
    "state": "DC",
    "postalCode": "20500",
    "country": "US",
    "latitude": 38.8948949,
    "longitude": -77.0371581
  },
  "dropoffLatitude": 123,
  "dropoffLongitude": 123,
  "dropoffFirstName": "<string>",
  "dropoffLastName": "<string>",
  "dropoffPhoneNumber": "<string>",
  "dropoffEmail": "<string>",
  "dropoffStoreLocationId": "<string>",
  "dropoffExternalStoreLocationId": "<string>",
  "dropoffBarcodes": [
    "<string>"
  ],
  "packageDeliveryMode": "<string>",
  "pickupInstructions": "<string>",
  "dropoffBusinessName": "<string>",
  "dropoffInstructions": "<string>",
  "dropoffPlaceId": "<string>",
  "packagePickupStartTime": "<string>",
  "packagePickupEndTime": "<string>",
  "packageDropoffStartTime": "<string>",
  "packageDropoffEndTime": "<string>",
  "packageDescription": "<string>",
  "packageValue": 123,
  "packageValueCents": 123,
  "packageTax": 123,
  "packageServiceFee": 123,
  "tipAmount": 123,
  "tipAmountCents": 123,
  "tipAmountUsd": 123,
  "currency": "<string>",
  "itemsCount": 123,
  "packageExternalIdentifier": "<string>",
  "packageMinimumVehicleSize": "<string>",
  "packageRequirements": [
    "photo_proof_of_delivery",
    "age_verification_on_delivery"
  ],
  "weight": 123,
  "dimensions": {},
  "packageItems": [
    {}
  ],
  "referenceId": "<string>",
  "externalIdentifier": "mini-mart-order-99",
  "optionsGroupId": "dss_1yMhHj",
  "jobMetadata": {
    "key": "value"
  },
  "inputDatetimesLocalizedToPickupTz": false,
  "quoteRequestOnly": false
}'
{
  "id": "job_01234567890",
  "createdAt": "2023-08-29T19:17:46.264523",
  "portalUrl": "https://usenash.com/portal/job_abc123",
  "externalIdentifier": "mini-mart-order-99",
  "jobMetadata": {
    "key": "value"
  },
  "isActive": true,
  "isBatch": false,
  "jobConfigurations": [
    {
      "id": "cfg_01234567890",
      "package": {
        "id": "pkg_01234567890",
        "description": "Package description",
        "requirements": [
          "photo_proof_of_delivery",
          "age_verification_on_delivery"
        ],
        "tags": [
          "Alcohol"
        ],
        "packageDeliveryMode": "now",
        "pickupStartTime": "2021-01-01T00:00:00Z",
        "pickupEndTime": "2021-01-01T00:00:00Z",
        "pickupBarcodes": [
          "<string>"
        ],
        "dropoffStartTime": "2021-01-01T00:00:00Z",
        "dropoffEndTime": "2021-01-01T00:00:00Z",
        "dropoffBarcodes": [
          "<string>"
        ],
        "valueCents": 123,
        "taxCents": 100,
        "serviceFeeCents": 100,
        "itemsCount": 100,
        "externalIdentifier": "mini-mart-order-99",
        "minimumVehicleSize": "car",
        "pickupLocation": {
          "id": "loc_01234567890",
          "address": "1600 Amphitheatre Parkway",
          "formattedAddress": "1600 Amphitheatre Parkway",
          "addressNumber": "1600",
          "addressFormattedStreet": "Amphitheatre Parkway",
          "addressCity": "Mountain View",
          "addressCounty": "Santa Clara",
          "addressState": "CA",
          "addressZip": "94043",
          "addressCountry": "US",
          "timezoneId": "America/Los_Angeles",
          "timezoneName": "Pacific Time",
          "instructions": "Turn left on Main St",
          "businessName": "Nash",
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+15555555555",
          "email": "john.doe@example.com"
        },
        "pickupStoreLocationId": "store_01234567890",
        "dropoffLocation": {
          "id": "loc_01234567890",
          "address": "1600 Amphitheatre Parkway",
          "formattedAddress": "1600 Amphitheatre Parkway",
          "addressNumber": "1600",
          "addressFormattedStreet": "Amphitheatre Parkway",
          "addressCity": "Mountain View",
          "addressCounty": "Santa Clara",
          "addressState": "CA",
          "addressZip": "94043",
          "addressCountry": "US",
          "timezoneId": "America/Los_Angeles",
          "timezoneName": "Pacific Time",
          "instructions": "Turn left on Main St",
          "businessName": "Nash",
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+15555555555",
          "email": "john.doe@example.com"
        },
        "dropoffStoreLocationId": "store_01234567890",
        "drivingMetrics": {
          "distance": 100,
          "duration": 100
        },
        "value": 100,
        "tax": 100,
        "serviceFee": 100,
        "tipAmountCents": 123,
        "weight": 100,
        "dimensions": {
          "height": 100,
          "length": 100,
          "width": 100
        },
        "items": [
          {
            "count": 1,
            "description": "Item 1",
            "valueCents": 100
          }
        ],
        "referenceId": "mini-mart-order-99",
        "packageMetadata": {
          "key": "value"
        }
      },
      "tasks": [
        {
          "id": "tsk_01234567890",
          "createdAt": "2023-08-29T19:17:46.264523",
          "status": "running",
          "pickupStartTime": "2023-08-29T19:17:46.264523",
          "pickupEndTime": "2023-08-29T19:17:46.264523",
          "dropoffStartTime": "2023-08-29T19:17:46.264523",
          "dropoffEndTime": "2023-08-29T19:17:46.264523",
          "providerId": "prv_01234567890",
          "providerIsInternal": true,
          "tipAmountCents": 100,
          "winnerQuote": {
            "id": "qot_01234567890",
            "price_cents": 100
          },
          "quotes": [
            {
              "id": "qot_01234567890",
              "price_cents": 100
            }
          ],
          "failedQuotes": [
            {
              "id": "qot_01234567890",
              "price_cents": 100
            }
          ],
          "delivery": {
            "id": "dlv_01234567890",
            "type": "<string>",
            "status": "dropoff_complete",
            "statusHistory": [
              {
                "created_at": "2023-08-29T19:17:46.264523",
                "status": "created"
              },
              {
                "created_at": "2023-08-29T19:17:47.509265",
                "status": "not_assigned_driver"
              }
            ],
            "isActive": true,
            "pickupEta": "<string>",
            "dropoffEta": "<string>",
            "dropoffDeadline": "<string>",
            "priceCents": 123,
            "currency": "<string>",
            "documents": [
              {
                "createdAt": "<string>",
                "id": "<string>",
                "type": "<string>",
                "url": "<string>",
                "contentType": "<string>",
                "documentMetadata": {}
              }
            ],
            "nashFeeCents": 123,
            "courierName": "<string>",
            "courierPhoneNumber": "<string>",
            "courierPickupPhoneNumber": "<string>",
            "courierDropoffPhoneNumber": "<string>",
            "courierLocation": {},
            "courierVehicle": {},
            "courierProfileImage": "<string>",
            "proofOfDelivery": [
              {}
            ],
            "providerDeliveryId": "<string>",
            "providerBatchId": "<string>",
            "price": 123,
            "taxAmountCents": 123,
            "tollFeeCents": 123,
            "waitFeeCents": 123,
            "waitTimeMinutes": 123,
            "cancellationFeeCents": 123,
            "returnFeeCents": 123,
            "otherProviderFees": {},
            "insuranceFeeCents": 123,
            "totalPriceBreakdown": {},
            "totalPriceCents": 123
          },
          "tipAmountUsd": 100,
          "failureReason": "Task failed",
          "taskNotes": [
            {
              "created_at": "2023-08-29T19:17:46.264523",
              "id": "not_01234567890",
              "note": "Task note",
              "user": {
                "email": "john.doe@example.com"
              }
            }
          ]
        }
      ],
      "advancedTask": {
        "id": "tsk_01234567890",
        "createdAt": "2023-08-29T19:17:46.264523",
        "status": "running",
        "pickupStartTime": "2023-08-29T19:17:46.264523",
        "pickupEndTime": "2023-08-29T19:17:46.264523",
        "dropoffStartTime": "2023-08-29T19:17:46.264523",
        "dropoffEndTime": "2023-08-29T19:17:46.264523",
        "providerId": "prv_01234567890",
        "providerIsInternal": true,
        "tipAmountCents": 100,
        "winnerQuote": {
          "id": "qot_01234567890",
          "price_cents": 100
        },
        "quotes": [
          {
            "id": "qot_01234567890",
            "price_cents": 100
          }
        ],
        "failedQuotes": [
          {
            "id": "qot_01234567890",
            "price_cents": 100
          }
        ],
        "delivery": {
          "id": "dlv_01234567890",
          "type": "<string>",
          "status": "dropoff_complete",
          "statusHistory": [
            {
              "created_at": "2023-08-29T19:17:46.264523",
              "status": "created"
            },
            {
              "created_at": "2023-08-29T19:17:47.509265",
              "status": "not_assigned_driver"
            }
          ],
          "isActive": true,
          "pickupEta": "<string>",
          "dropoffEta": "<string>",
          "dropoffDeadline": "<string>",
          "priceCents": 123,
          "currency": "<string>",
          "documents": [
            {
              "createdAt": "<string>",
              "id": "<string>",
              "type": "<string>",
              "url": "<string>",
              "contentType": "<string>",
              "documentMetadata": {}
            }
          ],
          "nashFeeCents": 123,
          "courierName": "<string>",
          "courierPhoneNumber": "<string>",
          "courierPickupPhoneNumber": "<string>",
          "courierDropoffPhoneNumber": "<string>",
          "courierLocation": {},
          "courierVehicle": {},
          "courierProfileImage": "<string>",
          "proofOfDelivery": [
            {}
          ],
          "providerDeliveryId": "<string>",
          "providerBatchId": "<string>",
          "price": 123,
          "taxAmountCents": 123,
          "tollFeeCents": 123,
          "waitFeeCents": 123,
          "waitTimeMinutes": 123,
          "cancellationFeeCents": 123,
          "returnFeeCents": 123,
          "otherProviderFees": {},
          "insuranceFeeCents": 123,
          "totalPriceBreakdown": {},
          "totalPriceCents": 123
        },
        "tipAmountUsd": 100,
        "failureReason": "Task failed",
        "taskNotes": [
          {
            "created_at": "2023-08-29T19:17:46.264523",
            "id": "not_01234567890",
            "note": "Task note",
            "user": {
              "email": "john.doe@example.com"
            }
          }
        ]
      },
      "delivery": {
        "id": "dlv_01234567890",
        "type": "<string>",
        "status": "dropoff_complete",
        "statusHistory": [
          {
            "created_at": "2023-08-29T19:17:46.264523",
            "status": "created"
          },
          {
            "created_at": "2023-08-29T19:17:47.509265",
            "status": "not_assigned_driver"
          }
        ],
        "isActive": true,
        "pickupEta": "<string>",
        "dropoffEta": "<string>",
        "dropoffDeadline": "<string>",
        "priceCents": 123,
        "currency": "<string>",
        "documents": [
          {
            "createdAt": "<string>",
            "id": "<string>",
            "type": "<string>",
            "url": "<string>",
            "contentType": "<string>",
            "documentMetadata": {}
          }
        ],
        "nashFeeCents": 123,
        "courierName": "<string>",
        "courierPhoneNumber": "<string>",
        "courierPickupPhoneNumber": "<string>",
        "courierDropoffPhoneNumber": "<string>",
        "courierLocation": {},
        "courierVehicle": {},
        "courierProfileImage": "<string>",
        "proofOfDelivery": [
          {}
        ],
        "providerDeliveryId": "<string>",
        "providerBatchId": "<string>",
        "price": 123,
        "taxAmountCents": 123,
        "tollFeeCents": 123,
        "waitFeeCents": 123,
        "waitTimeMinutes": 123,
        "cancellationFeeCents": 123,
        "returnFeeCents": 123,
        "otherProviderFees": {},
        "insuranceFeeCents": 123,
        "totalPriceBreakdown": {},
        "totalPriceCents": 123
      },
      "publicTrackingUrl": "https://usenash.com/tracking/job_abc123"
    }
  ],
  "optionsGroup": {
    "id": "opn_WyMhHj",
    "label": "New York City Strategy",
    "allowedProviders": [
      "prv_01234567890",
      "prv_01234567891"
    ],
    "enableAutoDispatch": true,
    "providerSelectionStrategy": "cheapest",
    "reassignOnFailure": true,
    "enableMaxDeliveryFee": true,
    "maxDeliveryFeeCents": 10000,
    "costSplitMaxFixedPriceCents": 10000,
    "costSplitMaxPercentage": 0.1,
    "costSplitStrategy": "price"
  },
  "shortReferenceCode": "0123456",
  "selectedConfiguration": {
    "tasks": []
  },
  "jobSpecification": {
    "packages": []
  }
}

​
Scheduled Job Time Calculations

When creating a scheduled job, you must include at least one time constraint out of packagePickupStartTime, packagePickupEndTime, packageDropoffStartTime, and packageDropoffEndTime. Times that are not specified will be calculated by Nash.

If the specified pickup time of a scheduled job is very close to the current time (within 5 minutes in the past or 10 minutes in the future), it will be automatically transformed into an ASAP job.

For this and all other endpoints, as Nash processes fields from different providers, please assume that any field in the response we provide may be null.

​
Package Items

An array of item objects, each describing an item within the package for delivery.

Each object should include the item’s name, dimensions (length, width, height), and count, providing a detailed inventory of the package’s contents. This information is used to ensure accurate handling and space allocation for transport.

Note that it’s still highly recommended to include both pickup and dropoff times since our estimations are based on historical time data rather than real-time metrics.

The fields selectedConfiguration and jobSpecification returned in the job response are deprecated and not recommended to be used.

Migration guide, replace:

jobSpecification->package with data->jobConfiguration[0]->package

and selectedConfiguration with jobConfiguration[0]

Body

application/json

Expected payload for creating a job.

​
packageDeliveryMode
string
required
​
pickupAddress
string | null

The full address in one line for the pickup location for this package within the Job. Address format: [Number] [Street], [second line], [city], [state] [zip code], [country]. All address fields are required except "second line". Second line should include Apt/Suite/Unit/# appended to the number of the unit.

​
pickupAddressComponents
object | null

Parsed address input serializer for creating a job.

​
pickupLatitude
number | null
​
pickupLongitude
number | null
​
pickupBusinessName
string | null

Pickup business name at the origin. Limited to 80 characters.

​
pickupFirstName
string | null

First name of the person to pickup from. If unknown pass "Manager". Limited to 80 characters.

​
pickupLastName
string | null

Last name of the person to pickup from. If unknown pass "Manager". Limited to 80 characters.

​
pickupPlaceId
string | null

The Google place ID for the pickup location.If passed, resolving the pickup location's lat/lng will happen with this field.

​
pickupStoreLocationId
string | null

The Nash store location ID for the pickup location.

​
pickupPhoneNumber
string | null

The phone number to contact at the location in the form: "+15555555555"

​
pickupEmail
string | null
​
pickupBarcodes
string[] | null
​
dropoffAddress
string | null

The full address in one line for the dropoff location for this package within the Job. Address format: [Number] [Street], [second line], [city], [state], [zip code], [country]. All address fields are required except "second line". Second line should include Apt/Suite/Unit/# appended to the number of the unit.

​
dropoffAddressComponents
object | null

Parsed address input serializer for creating a job.

​
dropoffLatitude
number | null
​
dropoffLongitude
number | null
​
dropoffFirstName
string | null
​
dropoffLastName
string | null
​
dropoffPhoneNumber
string | null
​
dropoffEmail
string | null
​
dropoffStoreLocationId
string | null
​
dropoffExternalStoreLocationId
string | null
​
dropoffBarcodes
string[] | null
​
pickupInstructions
string | null

Any special instructions for pickup. Limited to 280 characters. Nash Recommended Input: Pickup order [insert order number] for [insert customer name] from [pickup business name].

​
dropoffBusinessName
string | null
​
dropoffInstructions
string | null
​
dropoffPlaceId
string | null
​
packagePickupStartTime
string | null
​
packagePickupEndTime
string | null
​
packageDropoffStartTime
string | null
​
packageDropoffEndTime
string | null
​
packageDescription
string | null
​
packageValue
number | null
​
packageValueCents
integer | null
​
packageTax
​
packageServiceFee
​
tipAmount
​
tipAmountCents
integer | null
​
tipAmountUsd
number | null
​
currency
string | null
​
itemsCount
​
packageExternalIdentifier
string | null
​
packageMinimumVehicleSize
string | null
​
packageRequirements
(enum<string> | string)[] | null

Package requirements.

Detailed description: https://docs.usenash.com/reference/package-requirements.

Available options:
photo_proof_of_delivery,
signature_proof_of_delivery,
photo_proof_of_pickup,
signature_proof_of_pickup,
age_verification_on_delivery,
id_verification_on_delivery,
barcode_scan_on_pickup,
barcode_scan_on_dropoff,
meet_on_delivery,
shipping_label,
two_person_team,
pincode_verification,
schedule_ii_controlled_substances,
alcohol,
parking_check_in
​
weight
​
dimensions
object | null
​
packageItems
object[] | null
​
referenceId
string | null
​
externalIdentifier
string | null

External identifier for the job.

​
optionsGroupId
string | null

Dispatch strategy ID (formerly known as options group ID) for the job.

​
jobMetadata
object | null

Job metadata for the job.

​
inputDatetimesLocalizedToPickupTz
boolean
default:
false

Whether the input datetimes are localized to the pickup timezone.

​
quoteRequestOnly
boolean
default:
false

Whether to only request a quote and not create a job.

Response

200
application/json
OK

A Nash Job.

​
id
string
required

Job ID

​
createdAt
string
required

Created at

​
portalUrl
string
required

Portal URL

​
isActive
boolean
required

Is the job active

​
isBatch
boolean
required

Is the job a batch

​
jobConfigurations
object[]
required

Job configurations

Generic serializer for jbo configurations used in many endpoints.

​
externalIdentifier
string | null

External identifier

​
jobMetadata
object | null

Job metadata

​
optionsGroup
object | null

Options group

​
shortReferenceCode
string | null

7-digit non-unique human-readable reference code for the job.

​
selectedConfiguration
object | null
deprecated

Selected configuration

​
jobSpecification
object | null
deprecated

Job specification

Package RequirementsCreate or Update Job by External Identifier