API ReferenceStop
Create stops with automatic geocoding
Bulk-creates stops from free-text addresses.
Bulk-creates stops from free-text addresses. Routal resolves each address to coordinates and stores the result on the stop. Do not pass location, it is rejected: POST /v2/stops is the endpoint for coordinates you already have.
Stops whose address cannot be geocoded are still created, without coordinates. They stay unassigned and cannot be optimized until someone fixes the address in the Routal Planner.
Pass either plan_id (add to a plan) or project_id (create unassigned). Payload size is capped at 5 MB. Geocoding costs more than coordinate-based creation, so prefer POST /v2/stops when your side already has coordinates.
Authorization
api_key private_key<token>
Pass your API key as the private_key query string parameter. Generate and rotate keys in Developer Settings of your Routal workspace.
Keys stay server-side. Never ship them to a browser or mobile app.
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/geocode" \ -H "Content-Type: application/json" \ -d '[ { "address": "Aragó Street 245, 08015 Barcelona, Spain" } ]'[
{
"id": "4f75d991ac359f8c4c79d762",
"fixed_id": "1",
"organization_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"plan_label": "March deliveries",
"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,
"price": 8.4,
"max_delivery_time": 7200,
"status": "pending",
"plan_execution_date": "2026-09-09T07:20:39.194Z",
"order": 0,
"planned_arrival_time": 29500,
"planned_departure_time": 30000,
"estimated_arrival_time": "2026-09-09T07:20:39.194Z",
"estimated_departure_time": "2026-09-09T07:20:39.194Z",
"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-09-09T07:20:39.190Z",
"updated_at": "2026-09-09T07:20:39.190Z",
"deleted_at": "2026-09-09T07:20:39.190Z"
}
],
"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"
},
"location_distance": 120,
"time_in_stop": 180,
"custom_fields": {
"delivered_to": "neighbor 2A",
"cod_collected": 24.9,
"photo_count": 2
},
"created_at": "2026-09-09T07:20:39.190Z"
}
],
"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-09-09T07:20:39.193Z",
"updated_at": "2026-09-09T07:20:39.193Z"
},
"pin": "4729",
"customer_text_field": "Leave at reception if I'm not home.",
"supervisors": [
"4f75d991ac359f8c4c79d762"
],
"location_validation_sent": false,
"location_validation_sent_at": "2026-09-09T07:20:39.195Z",
"location_validated": false,
"location_validated_at": "2026-09-09T07:20:39.195Z",
"packages": [
{
"identifier": "4f75d991ac359f8c4c79d762",
"status": "pending",
"picked_at": "2026-09-09T07:20:39.195Z",
"delivered_at": "2026-09-09T07:20:39.195Z",
"updated_at": "2026-09-09T07:20:39.195Z"
}
],
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-09-09T07:20:39.034Z",
"updated_at": "2026-09-09T07:20:39.034Z",
"deleted_at": "2026-09-09T07:20:39.034Z",
"deleted": true,
"pickup": {
"id": "4f75d991ac359f8c4c79d762",
"fixed_id": "1",
"organization_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"plan_label": "March deliveries",
"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,
"price": 8.4,
"max_delivery_time": 7200,
"status": "pending",
"plan_execution_date": "2026-09-09T07:20:39.194Z",
"order": 0,
"planned_arrival_time": 29500,
"planned_departure_time": 30000,
"estimated_arrival_time": "2026-09-09T07:20:39.194Z",
"estimated_departure_time": "2026-09-09T07:20:39.194Z",
"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-09-09T07:20:39.190Z",
"updated_at": "2026-09-09T07:20:39.190Z",
"deleted_at": "2026-09-09T07:20:39.190Z"
}
],
"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"
},
"location_distance": 120,
"time_in_stop": 180,
"custom_fields": {
"delivered_to": "neighbor 2A",
"cod_collected": 24.9,
"photo_count": 2
},
"created_at": "2026-09-09T07:20:39.190Z"
}
],
"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-09-09T07:20:39.193Z",
"updated_at": "2026-09-09T07:20:39.193Z"
},
"pin": "4729",
"customer_text_field": "Leave at reception if I'm not home.",
"supervisors": [
"4f75d991ac359f8c4c79d762"
],
"location_validation_sent": false,
"location_validation_sent_at": "2026-09-09T07:20:39.195Z",
"location_validated": false,
"location_validated_at": "2026-09-09T07:20:39.195Z",
"packages": [
{
"identifier": "4f75d991ac359f8c4c79d762",
"status": "pending",
"picked_at": "2026-09-09T07:20:39.195Z",
"delivered_at": "2026-09-09T07:20:39.195Z",
"updated_at": "2026-09-09T07:20:39.195Z"
}
],
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-09-09T07:20:39.034Z",
"updated_at": "2026-09-09T07:20:39.034Z",
"deleted_at": "2026-09-09T07:20:39.034Z",
"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