---
agentTools:
  projectIndex: https://kosmo.readme.io/llms.txt
---

# Batch import stops

You can use this endpoint to create multiple stops at once. It will return a plan ID which you can use to optimize the plan.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "contact": {
      "email": "developer@kosmo.delivery",
      "name": "Kosmo API Support"
    },
    "description": "Kosmo API Reference v2",
    "termsOfService": "https://www.kosmo.delivery/",
    "title": "Kosmo API Reference v2",
    "version": "2.0"
  },
  "paths": {
    "/v2/stops/batch": {
      "post": {
        "operationId": "batchImportStops",
        "description": "You can use this endpoint to create multiple stops at once. It will return a plan ID which you can use to optimize the plan.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateStopsBatchRequest"
              }
            }
          },
          "description": "Batch import stops request body",
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateStopsBatchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/kosmoerr.ErrorPayloadDTO"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/kosmoerr.ErrorPayloadDTO"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/kosmoerr.ErrorPayloadDTO"
                }
              }
            }
          }
        },
        "summary": "Batch import stops",
        "tags": [
          "Stops"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api.kosmo.delivery",
      "description": "Kosmo API URL"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "token"
      }
    },
    "schemas": {
      "StopRequest": {
        "description": "Details of dropoff.",
        "required": [
          "location",
          "contact"
        ],
        "properties": {
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "contact": {
            "$ref": "#/components/schemas/Contact"
          },
          "parcel": {
            "description": "Deprecated - use parcels instead.",
            "$ref": "#/components/schemas/ParcelRequest"
          },
          "parcels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ParcelRequest"
            }
          },
          "orderReferenceId": {
            "description": "You can provide this field to identify this dropoff with a specific ID in your system. So you will be able to track your system order in a case if you want to create multi dropoff order.",
            "type": "string",
            "example": "1aa3ce25-fb22-4f49-861e-118a500a26f2"
          },
          "cashOnDeliveryAmount": {
            "description": "The amount of cash on delivery in cents. It's required to be greater than 0 if you want to collect cash on delivery.",
            "type": "integer",
            "example": {
              "amount": 6000
            }
          },
          "timeAtLocation": {
            "description": "The time in seconds the driver will spend at the location.",
            "type": "integer",
            "example": 600
          },
          "arrivalTimeStart": {
            "description": "Expected arrival time to receive order.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-01T00:00:00.000Z"
          },
          "arrivalTimeEnd": {
            "description": "Expected dropoff time to receive order.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-01T00:00:00.000Z"
          },
          "clientId": {
            "description": "The client ID. You can manage your clients in the Kosmo dashboard.",
            "type": "string",
            "example": "client_123456"
          },
          "tags": {
            "description": "Tags for the order.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "stopType": {
            "description": "Type of the stop.",
            "type": "string",
            "enum": [
              "pickup",
              "dropoff"
            ],
            "default": "dropoff"
          },
          "priority": {
            "description": "The priority of the stop.",
            "$ref": "#/components/schemas/OptimizationPriority"
          }
        }
      },
      "OptimizationPriority": {
        "description": "The optimization priority of the stop.",
        "type": "string",
        "enum": [
          "",
          "first",
          "last"
        ],
        "default": ""
      },
      "CreateStopsBatchRequest": {
        "description": "The request to create a batch of stops.",
        "required": [
          "stops"
        ],
        "properties": {
          "stops": {
            "description": "The list of stops.",
            "items": {
              "$ref": "#/components/schemas/StopRequest"
            },
            "type": "array"
          }
        }
      },
      "CreateStopsBatchResponse": {
        "description": "The response of the created stops batch.",
        "required": [
          "planId"
        ],
        "properties": {
          "planId": {
            "description": "The ID of the created stops batch.",
            "type": "string",
            "example": "plan_123456"
          }
        }
      },
      "Location": {
        "description": "Details of location.",
        "required": [
          "address",
          "country"
        ],
        "properties": {
          "address": {
            "description": "The address including street number.",
            "type": "string",
            "example": "1 Parliament Pl",
            "x-oapi-codegen-extra-tags": {
              "validate": "required"
            }
          },
          "addressDetails": {
            "description": "Details such as unit number, floor, bulding name, etc. This will help the driver to know where to exactly go.",
            "type": "string",
            "example": "03-12"
          },
          "postalCode": {
            "description": "The postal code.",
            "type": "string",
            "example": "178880"
          },
          "country": {
            "description": "Country code of the location (ISO-3166)",
            "type": "string",
            "format": "ISO-3166",
            "example": "SG",
            "x-oapi-codegen-extra-tags": {
              "validate": "required"
            }
          },
          "lat": {
            "description": "Latitude",
            "type": "number",
            "example": 1.3222623,
            "x-go-type": "float64"
          },
          "lng": {
            "description": "Longitude",
            "type": "number",
            "example": 103.8704758,
            "x-go-type": "float64"
          },
          "instructions": {
            "description": "Specify any particular instructions you want the driver to be aware at pick up time.",
            "type": "string",
            "example": "Please call me when you arrive"
          }
        }
      },
      "Contact": {
        "description": "Details of contact (can be a store or a person).",
        "required": [
          "fullname",
          "phone"
        ],
        "properties": {
          "fullname": {
            "description": "Full name of the contact.",
            "type": "string",
            "example": "John Doe",
            "x-oapi-codegen-extra-tags": {
              "validate": "required"
            }
          },
          "phone": {
            "description": "The phone number of the contact.",
            "type": "string",
            "example": "+1234567890",
            "x-oapi-codegen-extra-tags": {
              "validate": "required,phone"
            }
          },
          "email": {
            "description": "The email of the contact.",
            "type": "string",
            "example": "contact-email@gmail.com",
            "x-oapi-codegen-extra-tags": {
              "validate": "omitempty,email"
            }
          }
        }
      },
      "ParcelRequest": {
        "description": "The parcel information for the delivery order.",
        "type": "object",
        "properties": {
          "description": {
            "description": "Description of the parcel.",
            "type": "string"
          },
          "weight": {
            "description": "Weight of the parcel in kilograms.",
            "type": "number",
            "example": 0.1
          },
          "height": {
            "description": "Height of the parcel in centimeters.",
            "type": "integer",
            "example": 10
          },
          "quantity": {
            "description": "Number of parcels.",
            "type": "integer",
            "example": 5
          },
          "width": {
            "description": "Width of the parcel in centimeters.",
            "type": "integer",
            "example": 10
          },
          "length": {
            "description": "Length of the parcel in centimeters.",
            "type": "integer",
            "example": 10
          },
          "value": {
            "description": "Value of the parcel in cents",
            "type": "integer"
          }
        }
      },
      "kosmoerr.ErrorPayloadDTO": {
        "properties": {
          "details": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/kosmoerr.ErrorDetailDTO"
            }
          },
          "key": {
            "description": "Error key.",
            "type": "string",
            "example": "invalid_request_error"
          },
          "message": {
            "description": "Error message.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "kosmoerr.ErrorDetailDTO": {
        "properties": {
          "key": {
            "description": "Error key.",
            "type": "string",
            "example": "invalid_phone_number"
          },
          "message": {
            "description": "Error message.",
            "type": "string",
            "example": "invalid phone number: Phone"
          },
          "field": {
            "description": "Error field.",
            "type": "string",
            "example": "CreateQuotesRequest.Dropoffs[0].Receiver.Phone"
          }
        },
        "type": "object"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 99,
      "1": 136,
      "2": 86,
      "3": 191,
      "4": 139,
      "5": 245,
      "6": 189,
      "7": 0,
      "8": 16,
      "9": 17,
      "10": 176,
      "11": 113
    }
  }
}
```