Skip to main content
Routal

Create multiple stops

Bulk-creates stops with already known coordinates.

POST
/v2/stops

Bulk-creates stops with already known coordinates. No geocoding is performed — pass the location (lat / lng) directly on each stop. Stops without a location are accepted but the optimizer cannot place them until coordinates are added. Use this when your source system already stores validated coordinates (warehouse pick lists, sorted parcels, IoT devices).

Pass either:

  • plan_id — the stops are added to that plan, ready to be optimized; or
  • project_id — the stops are created as unassigned at the project level, useful for an inbox of pending orders that you'll assign to a plan later.

Payload size is limited to 5 MB (~5,000 stops as a rough rule of thumb). For larger imports chunk your calls. If your data has free-text addresses instead of coordinates, use POST /v2/stops/geocode instead.

Authorization

api_key
private_key<token>

The Routal API authenticates requests with an API key passed as the private_key query string parameter. Generate and rotate your keys from the Developer Settings section of your Routal workspace.Never ship API keys to a browser or mobile app — they must stay server-side.

In: query

Query Parameters

plan_id?string

The plan where the stops will be created

Match^[0-9a-f]{24}
project_id?string

The project where the stops will be created in case of creating unassigned plan

Match^[0-9a-f]{24}

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/stops" \  -H "Content-Type: application/json" \  -d '[    {}  ]'
[
  {
    "id": "4f75d991ac359f8c4c79d762",
    "fixed_id": "1",
    "organization_id": "4f75d991ac359f8c4c79d762",
    "project_id": "4f75d991ac359f8c4c79d762",
    "plan_id": "4f75d991ac359f8c4c79d762",
    "type": "delivery",
    "route_id": "4f75d991ac359f8c4c79d762",
    "vehicle_id": "4f75d991ac359f8c4c79d762",
    "client_id": "4f75d991ac359f8c4c79d762",
    "client_external_id": "CUST-58291",
    "external_id": "ORD-2026-58291",
    "location": {
      "location_id": "4f75d991ac359f8c4c79d762",
      "label": "Location label",
      "country": "Spain",
      "country_code": "ES",
      "state": "Catalonia",
      "city": "Barcelona",
      "street": "Calle de Pau Claris",
      "postal_code": "08302",
      "comments": "Location comments",
      "lat": 40.45,
      "lng": -3.68,
      "main_text": "Calle de Pau Claris 12",
      "secondary_text": "Barcelona, Catalonia, Spain"
    },
    "location_details": "Local 2, junto a la entrada principal",
    "label": "Acme Pharmacy — Aragó branch",
    "comments": "Ring intercom 2B. Do not leave at reception.",
    "phone": "+34612345678",
    "email": "sarah.johnson@example.com",
    "url": "https://shop.example.com/orders/58291",
    "reference_person": "Sarah Johnson",
    "duration": 180,
    "requires": [
      "refrigerated",
      "fragile"
    ],
    "cluster": "eixample-norte",
    "reward": 5,
    "time_windows": [
      [
        28800,
        61200
      ]
    ],
    "volume": 0.12,
    "weight": 8.4,
    "max_delivery_time": 7200,
    "status": "pending",
    "plan_execution_date": "2026-05-29T14:55:24.491Z",
    "order": 0,
    "planned_arrival_time": 29500,
    "planned_departure_time": 30000,
    "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
    "estimated_departure_time": "2026-05-29T14:55:24.491Z",
    "pickup_id": "4f75d991ac359f8c4c79d762",
    "distance_to_previous_stop": 30000,
    "distance_to_next_stop": 20000,
    "optimization_warning": true,
    "chain_id": "order-58291",
    "chain_position": 1,
    "custom_fields": {
      "order_reference": "ORD-2026-58291",
      "parcel_count": 2,
      "cod_amount": 24.9
    },
    "tasks": [
      {
        "id": "4f75d991ac359f8c4c79d762",
        "stop_id": "4f75d991ac359f8c4c79d762",
        "label": "Deliver refrigerated parcel 1/2",
        "comments": "Keep cold chain. Weight 12.4 kg.",
        "barcode": "8410076472158",
        "status": "completed",
        "custom_fields": {
          "sku": "SKU-4582",
          "quantity": 2,
          "lot_number": "L-2026-038"
        },
        "created_by": "4f75d991ac359f8c4c79d762",
        "created_at": "2026-05-29T14:55:24.485Z",
        "updated_at": "2026-05-29T14:55:24.485Z",
        "deleted_at": "2026-05-29T14:55:24.485Z"
      }
    ],
    "reports": [
      {
        "id": "4f75d991ac359f8c4c79d762",
        "stop_id": "4f75d991ac359f8c4c79d762",
        "route_id": "4f75d991ac359f8c4c79d762",
        "project_id": "4f75d991ac359f8c4c79d762",
        "plan_id": "4f75d991ac359f8c4c79d762",
        "type": "service_report_completed",
        "comments": "Customer not present. Notice left in the mailbox.",
        "images": [
          {
            "id": "4f75d991ac359f8c4c79d762",
            "url": "https://api.routal.com"
          }
        ],
        "signature": {
          "id": "4f75d991ac359f8c4c79d762",
          "url": "https://api.routal.com"
        },
        "tasks": [
          {
            "task_id": "4f75d991ac359f8c4c79d762",
            "status": "completed",
            "comments": "Parcel delivered in perfect condition.",
            "custom_fields": {
              "sku": "SKU-4582",
              "quantity": 2,
              "lot_number": "L-2026-038"
            }
          }
        ],
        "cancel_reason": "nobody",
        "location": {
          "location_id": "4f75d991ac359f8c4c79d762",
          "label": "Location label",
          "country": "Spain",
          "country_code": "ES",
          "state": "Catalonia",
          "city": "Barcelona",
          "street": "Calle de Pau Claris",
          "postal_code": "08302",
          "comments": "Location comments",
          "lat": 40.45,
          "lng": -3.68,
          "main_text": "Calle de Pau Claris 12",
          "secondary_text": "Barcelona, Catalonia, Spain"
        },
        "time_in_stop": 180,
        "custom_fields": {
          "delivered_to": "neighbor 2A",
          "cod_collected": 24.9,
          "photo_count": 2
        },
        "created_at": "2026-05-29T14:55:24.486Z"
      }
    ],
    "report_attempts": 2,
    "survey": {
      "stop_id": "4f75d991ac359f8c4c79d762",
      "route_id": "4f75d991ac359f8c4c79d762",
      "rating": 1,
      "rating_tag": "time",
      "comments": "The delivery was very professional and punctual.",
      "created_at": "2026-05-29T14:55:24.489Z",
      "updated_at": "2026-05-29T14:55:24.489Z"
    },
    "pin": "4729",
    "customer_text_field": "Leave at reception if I'm not home.",
    "supervisors": [
      "4f75d991ac359f8c4c79d762"
    ],
    "location_validation_sent": false,
    "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
    "location_validated": false,
    "location_validated_at": "2026-05-29T14:55:24.500Z",
    "created_by": "4f75d991ac359f8c4c79d762",
    "created_at": "2026-05-29T14:55:24.339Z",
    "updated_at": "2026-05-29T14:55:24.339Z",
    "deleted_at": "2026-05-29T14:55:24.339Z",
    "deleted": true,
    "pickup": {
      "id": "4f75d991ac359f8c4c79d762",
      "fixed_id": "1",
      "organization_id": "4f75d991ac359f8c4c79d762",
      "project_id": "4f75d991ac359f8c4c79d762",
      "plan_id": "4f75d991ac359f8c4c79d762",
      "type": "delivery",
      "route_id": "4f75d991ac359f8c4c79d762",
      "vehicle_id": "4f75d991ac359f8c4c79d762",
      "client_id": "4f75d991ac359f8c4c79d762",
      "client_external_id": "CUST-58291",
      "external_id": "ORD-2026-58291",
      "location": {
        "location_id": "4f75d991ac359f8c4c79d762",
        "label": "Location label",
        "country": "Spain",
        "country_code": "ES",
        "state": "Catalonia",
        "city": "Barcelona",
        "street": "Calle de Pau Claris",
        "postal_code": "08302",
        "comments": "Location comments",
        "lat": 40.45,
        "lng": -3.68,
        "main_text": "Calle de Pau Claris 12",
        "secondary_text": "Barcelona, Catalonia, Spain"
      },
      "location_details": "Local 2, junto a la entrada principal",
      "label": "Acme Pharmacy — Aragó branch",
      "comments": "Ring intercom 2B. Do not leave at reception.",
      "phone": "+34612345678",
      "email": "sarah.johnson@example.com",
      "url": "https://shop.example.com/orders/58291",
      "reference_person": "Sarah Johnson",
      "duration": 180,
      "requires": [
        "refrigerated",
        "fragile"
      ],
      "cluster": "eixample-norte",
      "reward": 5,
      "time_windows": [
        [
          28800,
          61200
        ]
      ],
      "volume": 0.12,
      "weight": 8.4,
      "max_delivery_time": 7200,
      "status": "pending",
      "plan_execution_date": "2026-05-29T14:55:24.491Z",
      "order": 0,
      "planned_arrival_time": 29500,
      "planned_departure_time": 30000,
      "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
      "estimated_departure_time": "2026-05-29T14:55:24.491Z",
      "pickup_id": "4f75d991ac359f8c4c79d762",
      "distance_to_previous_stop": 30000,
      "distance_to_next_stop": 20000,
      "optimization_warning": true,
      "chain_id": "order-58291",
      "chain_position": 1,
      "custom_fields": {
        "order_reference": "ORD-2026-58291",
        "parcel_count": 2,
        "cod_amount": 24.9
      },
      "tasks": [
        {
          "id": "4f75d991ac359f8c4c79d762",
          "stop_id": "4f75d991ac359f8c4c79d762",
          "label": "Deliver refrigerated parcel 1/2",
          "comments": "Keep cold chain. Weight 12.4 kg.",
          "barcode": "8410076472158",
          "status": "completed",
          "custom_fields": {
            "sku": "SKU-4582",
            "quantity": 2,
            "lot_number": "L-2026-038"
          },
          "created_by": "4f75d991ac359f8c4c79d762",
          "created_at": "2026-05-29T14:55:24.485Z",
          "updated_at": "2026-05-29T14:55:24.485Z",
          "deleted_at": "2026-05-29T14:55:24.485Z"
        }
      ],
      "reports": [
        {
          "id": "4f75d991ac359f8c4c79d762",
          "stop_id": "4f75d991ac359f8c4c79d762",
          "route_id": "4f75d991ac359f8c4c79d762",
          "project_id": "4f75d991ac359f8c4c79d762",
          "plan_id": "4f75d991ac359f8c4c79d762",
          "type": "service_report_completed",
          "comments": "Customer not present. Notice left in the mailbox.",
          "images": [
            {
              "id": "4f75d991ac359f8c4c79d762",
              "url": "https://api.routal.com"
            }
          ],
          "signature": {
            "id": "4f75d991ac359f8c4c79d762",
            "url": "https://api.routal.com"
          },
          "tasks": [
            {
              "task_id": "4f75d991ac359f8c4c79d762",
              "status": "completed",
              "comments": "Parcel delivered in perfect condition.",
              "custom_fields": {
                "sku": "SKU-4582",
                "quantity": 2,
                "lot_number": "L-2026-038"
              }
            }
          ],
          "cancel_reason": "nobody",
          "location": {
            "location_id": "4f75d991ac359f8c4c79d762",
            "label": "Location label",
            "country": "Spain",
            "country_code": "ES",
            "state": "Catalonia",
            "city": "Barcelona",
            "street": "Calle de Pau Claris",
            "postal_code": "08302",
            "comments": "Location comments",
            "lat": 40.45,
            "lng": -3.68,
            "main_text": "Calle de Pau Claris 12",
            "secondary_text": "Barcelona, Catalonia, Spain"
          },
          "time_in_stop": 180,
          "custom_fields": {
            "delivered_to": "neighbor 2A",
            "cod_collected": 24.9,
            "photo_count": 2
          },
          "created_at": "2026-05-29T14:55:24.486Z"
        }
      ],
      "report_attempts": 2,
      "survey": {
        "stop_id": "4f75d991ac359f8c4c79d762",
        "route_id": "4f75d991ac359f8c4c79d762",
        "rating": 1,
        "rating_tag": "time",
        "comments": "The delivery was very professional and punctual.",
        "created_at": "2026-05-29T14:55:24.489Z",
        "updated_at": "2026-05-29T14:55:24.489Z"
      },
      "pin": "4729",
      "customer_text_field": "Leave at reception if I'm not home.",
      "supervisors": [
        "4f75d991ac359f8c4c79d762"
      ],
      "location_validation_sent": false,
      "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
      "location_validated": false,
      "location_validated_at": "2026-05-29T14:55:24.500Z",
      "created_by": "4f75d991ac359f8c4c79d762",
      "created_at": "2026-05-29T14:55:24.339Z",
      "updated_at": "2026-05-29T14:55:24.339Z",
      "deleted_at": "2026-05-29T14:55:24.339Z",
      "deleted": true
    }
  }
]
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
Empty