Skip to main content
PATCH
/
v1
/
jobs
/
{id}
Update Job by JobID/ExternalIdentifier
curl --request PATCH \
  --url https://api.sandbox.usenash.com/v1/jobs/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pickupAddress": "<string>",
  "pickupAddressComponents": {
    "street": "Pennsylvania Avenue NW",
    "city": "Washington",
    "country": "US",
    "number": "1600",
    "secondaryNumber": null,
    "county": "Washington",
    "state": "DC",
    "postalCode": "20500",
    "latitude": 38.8948949,
    "longitude": -77.0371581
  },
  "pickupPhoneNumber": "<string>",
  "pickupBusinessName": "<string>",
  "pickupFirstName": "<string>",
  "pickupLastName": "<string>",
  "pickupEmail": "<string>",
  "pickupInstructions": "<string>",
  "pickupStoreLocationId": "<string>",
  "pickupBarcodes": [
    "<string>"
  ],
  "dropoffAddress": "<string>",
  "dropoffAddressComponents": {
    "street": "Pennsylvania Avenue NW",
    "city": "Washington",
    "country": "US",
    "number": "1600",
    "secondaryNumber": null,
    "county": "Washington",
    "state": "DC",
    "postalCode": "20500",
    "latitude": 38.8948949,
    "longitude": -77.0371581
  },
  "dropoffPhoneNumber": "<string>",
  "dropoffBusinessName": "<string>",
  "dropoffFirstName": "<string>",
  "dropoffLastName": "<string>",
  "dropoffEmail": "<string>",
  "dropoffStoreLocationId": "<string>",
  "dropoffInstructions": "<string>",
  "dropoffBarcodes": [
    "<string>"
  ],
  "packageDeliveryMode": "<string>",
  "packagePickupStartTime": "<string>",
  "packagePickupEndTime": "<string>",
  "packageDropoffStartTime": "<string>",
  "packageDropoffEndTime": "<string>",
  "packageDescription": "<string>",
  "packageRequirements": [
    "photo_proof_of_delivery",
    "age_verification_on_delivery"
  ],
  "packageMinimumVehicleSize": "car",
  "packageValue": 123,
  "packageTax": 123,
  "tipAmount": 123,
  "currency": "<string>",
  "packageItems": [
    {}
  ],
  "referenceId": "<string>",
  "itemsCount": 123,
  "weight": 123,
  "externalIdentifier": "<string>",
  "jobMetadata": {},
  "packageMetadata": {}
}
'
{
  "id": "job_01234567890",
  "createdAt": "2023-08-29T19:17:46.264523",
  "portalUrl": "https://usenash.com/portal/job_abc123",
  "isActive": true,
  "isBatch": false,
  "jobConfigurations": [
    {
      "id": "cfg_01234567890",
      "package": {
        "id": "pkg_01234567890",
        "requirements": [
          "photo_proof_of_delivery",
          "age_verification_on_delivery"
        ],
        "valueCents": 123,
        "itemsCount": 100,
        "pickupLocation": {
          "id": "loc_01234567890",
          "address": "1600 Amphitheatre Parkway",
          "formattedAddress": "1600 Amphitheatre Parkway",
          "addressCity": "Mountain View",
          "addressCountry": "US",
          "timezoneId": "America/Los_Angeles",
          "timezoneName": "Pacific Time",
          "addressNumber": "1600",
          "addressFormattedStreet": "Amphitheatre Parkway",
          "addressCounty": "Santa Clara",
          "addressState": "CA",
          "addressZip": "94043",
          "instructions": "Turn left on Main St",
          "businessName": "Nash",
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+15555555555",
          "email": "[email protected]",
          "lat": 37.774929,
          "lng": -122.419416
        },
        "dropoffLocation": {
          "id": "loc_01234567890",
          "address": "1600 Amphitheatre Parkway",
          "formattedAddress": "1600 Amphitheatre Parkway",
          "addressCity": "Mountain View",
          "addressCountry": "US",
          "timezoneId": "America/Los_Angeles",
          "timezoneName": "Pacific Time",
          "addressNumber": "1600",
          "addressFormattedStreet": "Amphitheatre Parkway",
          "addressCounty": "Santa Clara",
          "addressState": "CA",
          "addressZip": "94043",
          "instructions": "Turn left on Main St",
          "businessName": "Nash",
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+15555555555",
          "email": "[email protected]",
          "lat": 37.774929,
          "lng": -122.419416
        },
        "description": "Package description",
        "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>"
        ],
        "taxCents": 100,
        "serviceFeeCents": 100,
        "externalIdentifier": "mini-mart-order-99",
        "minimumVehicleSize": "car",
        "pickupStoreLocationId": "store_01234567890",
        "pickupStoreLocationExternalId": "0123",
        "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",
            "status": "dropoff_complete",
            "isActive": true,
            "priceCents": 123,
            "currency": "<string>",
            "type": "<string>",
            "statusHistory": [
              {
                "created_at": "2023-08-29T19:17:46.264523",
                "status": "created"
              },
              {
                "created_at": "2023-08-29T19:17:47.509265",
                "status": "not_assigned_driver"
              }
            ],
            "pickupEta": "<string>",
            "dropoffEta": "<string>",
            "dropoffDeadline": "<string>",
            "documents": [
              {
                "createdAt": "<string>",
                "id": "<string>",
                "type": "<string>",
                "contentType": "<string>",
                "url": "<string>",
                "data": "<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,
            "pickedItems": [
              {
                "sku": "<string>",
                "requestedSku": "<string>",
                "id": "<string>",
                "requestedId": "<string>",
                "quantity": 123,
                "scannedBarcode": "<string>",
                "weight": 123,
                "priceCents": 123,
                "status": "<string>",
                "name": "<string>",
                "scans": [
                  {
                    "substitutionType": "<string>",
                    "barcodes": [
                      {
                        "weight": 123,
                        "priceCents": 123,
                        "weightUnit": "<string>",
                        "productCode": "<string>",
                        "isVariableWeight": true,
                        "barcode": "<string>",
                        "variableValue": 123,
                        "format": "<string>",
                        "indicatorDigit": "<string>",
                        "checkDigit": "<string>",
                        "manufacturerCode": "<string>",
                        "itemReference": "<string>",
                        "pluCheckDigit": "<string>",
                        "barcodeSansCheckDigit": "<string>",
                        "expirationDate": "<string>"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          "tipAmountUsd": 100,
          "failureReason": "Task failed",
          "taskNotes": [
            {
              "created_at": "2023-08-29T19:17:46.264523",
              "id": "not_01234567890",
              "note": "Task note",
              "user": {
                "email": "[email protected]"
              }
            }
          ]
        }
      ],
      "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",
          "status": "dropoff_complete",
          "isActive": true,
          "priceCents": 123,
          "currency": "<string>",
          "type": "<string>",
          "statusHistory": [
            {
              "created_at": "2023-08-29T19:17:46.264523",
              "status": "created"
            },
            {
              "created_at": "2023-08-29T19:17:47.509265",
              "status": "not_assigned_driver"
            }
          ],
          "pickupEta": "<string>",
          "dropoffEta": "<string>",
          "dropoffDeadline": "<string>",
          "documents": [
            {
              "createdAt": "<string>",
              "id": "<string>",
              "type": "<string>",
              "contentType": "<string>",
              "url": "<string>",
              "data": "<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,
          "pickedItems": [
            {
              "sku": "<string>",
              "requestedSku": "<string>",
              "id": "<string>",
              "requestedId": "<string>",
              "quantity": 123,
              "scannedBarcode": "<string>",
              "weight": 123,
              "priceCents": 123,
              "status": "<string>",
              "name": "<string>",
              "scans": [
                {
                  "substitutionType": "<string>",
                  "barcodes": [
                    {
                      "weight": 123,
                      "priceCents": 123,
                      "weightUnit": "<string>",
                      "productCode": "<string>",
                      "isVariableWeight": true,
                      "barcode": "<string>",
                      "variableValue": 123,
                      "format": "<string>",
                      "indicatorDigit": "<string>",
                      "checkDigit": "<string>",
                      "manufacturerCode": "<string>",
                      "itemReference": "<string>",
                      "pluCheckDigit": "<string>",
                      "barcodeSansCheckDigit": "<string>",
                      "expirationDate": "<string>"
                    }
                  ]
                }
              ]
            }
          ]
        },
        "tipAmountUsd": 100,
        "failureReason": "Task failed",
        "taskNotes": [
          {
            "created_at": "2023-08-29T19:17:46.264523",
            "id": "not_01234567890",
            "note": "Task note",
            "user": {
              "email": "[email protected]"
            }
          }
        ]
      },
      "delivery": {
        "id": "dlv_01234567890",
        "status": "dropoff_complete",
        "isActive": true,
        "priceCents": 123,
        "currency": "<string>",
        "type": "<string>",
        "statusHistory": [
          {
            "created_at": "2023-08-29T19:17:46.264523",
            "status": "created"
          },
          {
            "created_at": "2023-08-29T19:17:47.509265",
            "status": "not_assigned_driver"
          }
        ],
        "pickupEta": "<string>",
        "dropoffEta": "<string>",
        "dropoffDeadline": "<string>",
        "documents": [
          {
            "createdAt": "<string>",
            "id": "<string>",
            "type": "<string>",
            "contentType": "<string>",
            "url": "<string>",
            "data": "<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,
        "pickedItems": [
          {
            "sku": "<string>",
            "requestedSku": "<string>",
            "id": "<string>",
            "requestedId": "<string>",
            "quantity": 123,
            "scannedBarcode": "<string>",
            "weight": 123,
            "priceCents": 123,
            "status": "<string>",
            "name": "<string>",
            "scans": [
              {
                "substitutionType": "<string>",
                "barcodes": [
                  {
                    "weight": 123,
                    "priceCents": 123,
                    "weightUnit": "<string>",
                    "productCode": "<string>",
                    "isVariableWeight": true,
                    "barcode": "<string>",
                    "variableValue": 123,
                    "format": "<string>",
                    "indicatorDigit": "<string>",
                    "checkDigit": "<string>",
                    "manufacturerCode": "<string>",
                    "itemReference": "<string>",
                    "pluCheckDigit": "<string>",
                    "barcodeSansCheckDigit": "<string>",
                    "expirationDate": "<string>"
                  }
                ]
              }
            ]
          }
        ]
      },
      "publicTrackingUrl": "https://usenash.com/tracking/job_abc123"
    }
  ],
  "externalIdentifier": "mini-mart-order-99",
  "jobMetadata": {
    "key": "value"
  },
  "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",
    "smartReassignment": true
  },
  "shortReferenceCode": "0123456",
  "selectedConfiguration": {
    "tasks": []
  },
  "jobSpecification": {
    "packages": []
  },
  "route": {
    "id": "rte_JphRWDiEosGpXuxwgaYfY3",
    "type": "SINGLE_PICKUP_MULTIPLE_DROPOFFS",
    "stops": [
      {
        "stopType": "PICKUP",
        "objectIds": [
          "ord_Qr5bVt8WiByGh66z2g7xEu",
          "ord_WJFuooSiRvFCaceGZjpbqs"
        ],
        "location": {
          "lat": 45.558214,
          "lng": -122.587074
        },
        "arrivalTime": "2025-04-25T03:27:00",
        "departTime": "2025-04-25T03:30:00",
        "serviceTime": 360,
        "distanceFromPrevious": 3376,
        "durationFromPrevious": 420
      }
    ],
    "jobId": "job_1234567890abcdef12345678",
    "externalId": "rte_JphRWDiEosGpXuxwgaYfY3",
    "routeMetadata": {
      "priority": "high",
      "source": "optimization_engine"
    },
    "validationErrors": {
      "order_123": "Order 123 has pickup but no dropoff"
    }
  }
}

​
Pre Dispatch Updates

Updating a job should always work before a quote is selected. Some updates may result in pricing changes Please note that you are only able to update the package delivery times and the pickup or dropoff addresses before an order has been dispatched to a fleet. If any task in a job is dispatched and a delivery time or address are attempted to be updated, then an error will be thrown by the endpoint. If you update any of the following fields, then the quotes returned by the job will be refreshed and the endpoint will return a new set of quotes. Moreover, any existing quotes (and quote IDs) will be invalid for dispatch. The fields that will force a refresh in the quotes:
  1. pickupAddress
  2. dropoffAddress
  3. packagePickupStartTime
  4. packagePickupEndTime
  5. packageDropoffStartTime
  6. packageDropoffEndTime
  7. packageDeliveryMode
  8. packageRequirements
  9. packageMinimumVehicleSize
  10. packageValue: for this field, it can also be updated in the post-dispatch stage

​
Note on Updating Times

If you wish to update the times of a Job, you must provide at least one time constraint out of packagePickupStartTime, packagePickupEndTime, packageDropoffStartTime, and packageDropoffEndTime. Times that are not specified will be calculated by Nash, and the previous times not included in the Update Request will be overwritten. Therefore, if you want to update only one time field and keep the rest the same, you must provide them in the parameters of the Update Request.
If you change packageDeliveryMode from SCHEDULED job to NOW, you do not need to specify any other time fields.

​
Post Dispatch Updates

If a quote has been selected or the job is dispatched via auto-dispatch, Nash will return an error if any of the assigned fleets in the job reject the update of the order. In the post-dispatch stage, updating the package value of the job may result in a price change, based on how the providers calculate their pricing. Below is a list of fields that are allowed to be updated, with more details on pre-dispatch or post-dispatch restrictions.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string | null
required

Job ID or External Identifier

​
jobConfigurationId
string | null
required

Job Configuration ID (for updating a package in a batch job)

Body

application/json

Expected input for update job endpoint.

​
pickupAddress
string | null

Pickup address

​
pickupAddressComponents
ParsedAddressInputSerializer · object

Parsed address input serializer for creating a job.

​
pickupPhoneNumber
string | null

Pickup phone number

​
pickupBusinessName
string | null

Pickup business name

​
pickupFirstName
string | null

Pickup first name

​
pickupLastName
string | null

Pickup last name

​
pickupEmail
string | null

Pickup email

​
pickupInstructions
string | null

Pickup instructions

​
pickupStoreLocationId
string | null

Pickup store location ID

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

Dropoff address

​
dropoffAddressComponents
ParsedAddressInputSerializer · object

Parsed address input serializer for creating a job.

​
dropoffPhoneNumber
string | null

Dropoff phone number

​
dropoffBusinessName
string | null

Dropoff business name

​
dropoffFirstName
string | null

Dropoff first name

​
dropoffLastName
string | null

Dropoff last name

​
dropoffEmail
string | null

Dropoff email

​
dropoffStoreLocationId
string | null

Dropoff store location ID

​
dropoffInstructions
string | null

Dropoff instructions

​
dropoffBarcodes
string[] | null
​
packageDeliveryMode
string | null

Package delivery mode

​
packagePickupStartTime
string | null

Package pickup start time

​
packagePickupEndTime
string | null

Package pickup end time

​
packageDropoffStartTime
string | null

Package dropoff start time

​
packageDropoffEndTime
string | null

Package dropoff end time

​
packageDescription
string | null

Package description

​
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,
photo_pre_delivery_verification,
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,
tobacco,
parking_check_in,
display_barcode_on_pickup,
pick_and_pack
Example:
[
  "photo_proof_of_delivery",
  "age_verification_on_delivery"
]
​
packageMinimumVehicleSize
enum<string>

Minimum vehicle size required for the package. Allowed values: ['any', 'bike', 'motorbike', 'cargobike', 'sedan', 'car', 'suv', 'pickup_truck', 'pickup', 'van', 'large_van', 'extra_large_van', 'truck']

Available options:
any,
bike,
motorbike,
cargobike,
sedan,
car,
suv,
pickup_truck,
pickup,
van,
large_van,
extra_large_van,
truck
Example:

"car"

​
packageValue
number | null

Package value

​
packageTax
number | null

Package tax

​
tipAmount
number | null

Tip amount

​
currency
string | null

Currency

​
packageItems
Packageitems · object[] | null

List of items in the package

​
referenceId
string | null

Reference ID

​
itemsCount
integer | null

Items count

​
weight

Package weight

​
externalIdentifier
string | null

External identifier for the job

​
jobMetadata
Jobmetadata · object

Job metadata

​
packageMetadata
Packagemetadata · object

Package metadata

Response

OK

A Nash Job.

​
id
string
required

Job ID

Example:

"job_01234567890"

​
createdAt
string
required

Created at

Example:

"2023-08-29T19:17:46.264523"

​
portalUrl
string
required

Portal URL

Example:

"https://usenash.com/portal/job_abc123"

​
isActive
boolean
required

Is the job active

Example:

true

​
isBatch
boolean
required

Is the job a batch

Example:

false

​
jobConfigurations
JobConfigurationsSerializer · object[]
required

Job configurations

​
externalIdentifier
string | null

External identifier

Example:

"mini-mart-order-99"

​
jobMetadata
Jobmetadata · object

Job metadata

Example:
{ "key": "value" }
​
optionsGroup
OptionsGroupSerializer · object

Options group

​
shortReferenceCode
string | null

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

Example:

"0123456"

​
selectedConfiguration
Selectedconfiguration · object
deprecated

Selected configuration

Example:
{ "tasks": [] }
​
jobSpecification
Jobspecification · object
deprecated

Job specification

Example:
{ "packages": [] }
​
route
RouteSerializer · object

Route