Saltar al contenido principal
Routal
API ReferencePlan

List stops of a plan

Returns every stop that belongs to the plan along with its execution payload — each stop includes its tasks, custom fields, timestamps and any reports captured…

GET
/v2/plan/{id}/stops

Returns every stop that belongs to the plan along with its execution payload — each stop includes its tasks, custom fields, timestamps and any reports captured at the visit (signature, photos, comments and per-task results such as scanned barcodes).

This is the right endpoint to export delivery data back to your TMS, generate invoices, or feed your customer notifications. The response can be large — paginate on your side if you need to display it.

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

Path Parameters

id*string

Plan ID

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

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/plan/string/stops"
[
  {
    "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

Update a plan

Updates plan-level attributes such as label, execution date, status or optimizer configuration.

List routes of a plan

Returns every route in the plan, each containing its ordered list of stops, the assigned vehicle, total distance, total duration and estimated arrival times.