Skip to main content
POST
/
v1
/
jobs
/
external_identifier
/
{externalIdentifier}
Create or Update Job by External Identifier
curl --request POST \
  --url https://api.sandbox.usenash.com/v1/jobs/external_identifier/{externalIdentifier} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "packageDeliveryMode": "<string>",
  "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
  },
  "pickupLatitude": 123,
  "pickupLongitude": 123,
  "pickupBusinessName": "<string>",
  "pickupFirstName": "<string>",
  "pickupLastName": "<string>",
  "pickupPlaceId": "<string>",
  "pickupStoreLocationId": "<string>",
  "pickupPhoneNumber": "<string>",
  "pickupEmail": "<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
  },
  "dropoffLatitude": 123,
  "dropoffLongitude": 123,
  "dropoffFirstName": "<string>",
  "dropoffLastName": "<string>",
  "dropoffPhoneNumber": "<string>",
  "dropoffEmail": "<string>",
  "dropoffStoreLocationId": "<string>",
  "dropoffExternalStoreLocationId": "<string>",
  "dropoffBarcodes": [
    "<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": "car",
  "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,
  "autodispatch": false
}
'
{
  "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"
    }
  }
}
This endpoint is deprecated. Please use the Create or Update Order by External Identifier endpoint instead.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
externalIdentifier
string
required

job external identifier

Body

application/json

Expected payload for creating a job and optionally autodispatch.

​
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
ParsedAddressInputSerializer · object

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
ParsedAddressInputSerializer · object

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
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"

​
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"
]
​
weight
​
dimensions
Dimensions · object
​
packageItems
Packageitems · object[] | null
​
referenceId
string | null
​
externalIdentifier
string | null

External identifier for the job.

Example:

"mini-mart-order-99"

​
optionsGroupId
string | null

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

Example:

"dss_1yMhHj"

​
jobMetadata
Jobmetadata · object

Job metadata for the job.

Example:
{ "key": "value" }
​
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.

​
autodispatch
boolean
default:false

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