---
title: "Batch import unassigned stops"
method: POST
path: "/unassignedStops:import"
tags: ["Unassigned Stops"]
---

# Batch import unassigned stops

`POST /unassignedStops:import`

## Request

- Base URL: `https://api.spoke.com/public/v1`
- URL: `https://api.spoke.com/public/v1/unassignedStops:import`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/spoke/apis/spoke-api/docs/unassignedStops:import/post.ts> (a function with typed inputs; its response is checked against the schema)

Batch import unassigned stops. The request body must contain an array of unassigned stops to import. Note that the `depot` is the same for all unassigned stops in a same request. This is because the depot is used as a biasing location for the unassigned stops, so that the geocoding results are more accurate for a same region.

## Request body

- object
  - `unassignedStops` object[], required: An array of unassigned stops to import in batch. Supports a maximum of 100 unassigned stops per request. Note that the `depot` is shared across all unassigned stops in the request, and thus should not be provided for individual unassigned stops. That is because the `depot` location is used to bias the geocoding results of the stops.
    - `address` object, required: Address of the stop, at least one of the fields is required. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.
      - `addressName` string, nullable: The name of the address. This will not be used for geocoding, and is only for the final address display purposes.
      - `addressLineOne` string, nullable: The first line of the address.
      - `addressLineTwo` string, nullable: The second line of the address.
      - `city` string, nullable: The city of the address.
      - `state` string, nullable: The state of the address.
      - `zip` string, nullable: The zip code of the address.
      - `country` string, nullable: The country of the address.
      - `latitude` number, nullable: The latitude of the address in decimal degrees.
      - `longitude` number, nullable: The longitude of the address in decimal degrees.
    - `recipient` object, nullable: Recipient information for this stop
      - `externalId` string, nullable: External ID of the recipient, as defined by the API user
      - `email` string, email, nullable: The email address of the recipient. Multiple emails are not supported.
      - `phone` string, nullable: Phone number of the recipient
      - `name` string, nullable: Name of the recipient
    - `orderInfo` object, nullable: Order information for this stop
      - `products` string[]: Products in this stop
      - `invoiceNumber` string, nullable: Invoice number
      - `sellerOrderId` string, nullable: Seller order ID
      - `sellerName` string, nullable: Seller name
      - `sellerWebsite` string, nullable: Seller website
    - `paymentOnDelivery` object, nullable: Payment on delivery (also known as "Cash on Delivery") data for this stop
      - `amount` integer, nullable: Amount *in minor units* (e.g. cents) to be collected upon delivery
      - `currency` 'AED' | 'ARS' | 'AUD' | 'BRL' | 'CAD' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'DKK' | 'EGP' | 'EUR' | 'GBP' | 'HKD' | 'HUF' | 'ILS' | 'INR' | 'JPY' | 'KRW' | 'MYR' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'RON' | 'RUB' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'USD' | 'UYU' | 'ZAR', nullable: Currency of the payment. Defaults to the team's currency.
    - `proofOfAttemptRequirements` object, nullable: Proof of attempt requirement settings for this stop
      - `enabled` boolean, nullable: Whether proof of attempt is required for this stop
    - `allowedDrivers` string[], nullable: Driver IDs that are allowed to be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization.
    - `activity` 'delivery' | 'pickup', nullable: Activity type
    - `optimizationOrder` 'first' | 'last' | 'default', nullable: The preferred order of this stop in the optimized route. If not provided or `"default"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `"first"` or `"last"`.
    - `packageCount` number, nullable: Number of packages in the stop
    - `weight` object, nullable: Weight information for this stop.
      - `amount` number, required: The weight amount for this stop.
      - `unit` 'kilogram' | 'pound' | 'metric-ton', required: The weight unit in which the amount is specified.
    - `notes` string, nullable: Notes for the stop
    - `clientId` string, nullable: Client ID of the retailer in Spoke Connect
    - `barcodes` string[]: List of barcode IDs associated with this stop
    - `customProperties` object, nullable: Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.
    - `timing` object, nullable
      - `timeWindows` object[]: Up to two ordered arrival windows for this stop. An empty array clears the windows. A single window may have one null bound; two windows must have both bounds set. Windows must not overlap or touch, and their total span must not exceed 24 hours.
        - `earliestAttemptTime` object, nullable, required: Time of day in hours and minutes. Use a 24 hour clock.
          - `hour` integer, required: Hour of the day
          - `minute` integer, required: Minute of the hour
        - `latestAttemptTime` object, nullable, required: Time of day in hours and minutes. Use a 24 hour clock.
          - `hour` integer, required: Hour of the day
          - `minute` integer, required: Minute of the hour
      - `earliestAttemptTime` object, nullable: Time of day in hours and minutes. Use a 24 hour clock.
        - `hour` integer, required: Hour of the day
        - `minute` integer, required: Minute of the hour
      - `latestAttemptTime` object, nullable: Time of day in hours and minutes. Use a 24 hour clock.
        - `hour` integer, required: Hour of the day
        - `minute` integer, required: Minute of the hour
      - `estimatedAttemptDuration` integer, nullable: Duration in seconds of the activity in this stop, only set if you want to override the default. This can be set up to 8 hours.
  - `depot` string, nullable: The Depot ID the unassigned stops in the batch belong to, in the format `depot/<id>`. This is used to bias the geocoding results of the unassigned stops, so every unassigned stop in the batch should belong to the same depot. If not provided, or null, it will default to the team's main depot.

## Response `200`

Success

- object: Success
  - `success` string[], required: The ids of the successfully imported unassigned stops
  - `failed` object[], required: The failed unassigned stops
    - `error` object, required
      - `message` string, required: The error that occurred during import
      - `code` string: Stable error code
      - `param` string: Invalid request parameter
    - `unassignedStop` object, required: The unassigned stop that failed to import
      - `address` object, required: The address of the unassigned stop that failed to import
        - `addressName` string, nullable, required: The name of the address. This will not be used for geocoding, and is only for the final address display purposes.
        - `addressLineOne` string, nullable, required: The first line of the address.
        - `addressLineTwo` string, nullable, required: The second line of the address.
        - `city` string, nullable, required: The city of the address.
        - `state` string, nullable, required: The state of the address.
        - `zip` string, nullable, required: The zip code of the address.
        - `country` string, nullable, required: The country of the address.
        - `latitude` number, nullable, required: The latitude of the address in decimal degrees.
        - `longitude` number, nullable, required: The longitude of the address in decimal degrees.
      - `recipient` object, nullable, required: The recipient of the unassigned stop that failed to import
        - `externalId` string, nullable, required: External ID of the recipient, as defined by the API user
        - `email` string, email, nullable, required: The email address of the recipient. Multiple emails are not supported.
        - `phone` string, nullable, required: Phone number of the recipient
        - `name` string, nullable, required: Name of the recipient

## Other responses

- `400`: The request has errors. Either syntactic or semantic
- `401`: Unauthorized
- `403`: The request contains fields that are not supported by your team subscription.
- `404`: A depot or a driver was not found
- `422`: The stop is unprocessable.
- `500`: An internal server error occurred
- `default`: The default error model

---

[API](https://skmtc.dev/spoke/apis/spoke-api.md) - [All operations](https://skmtc.dev/spoke/apis/spoke-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spoke/apis/spoke-api/revisions/a09d9194ae1c?raw)