State Update

Use this endpoint to report trip progress timestamps to VectorCare.

POST https://hub.vectorcare.com/openapi/v2.0/requests/{request_id}/state/

Note: URLs must include the trailing slash.

How It Works

This endpoint records when specific events occurred during a trip. You provide a state name and the timestamp when that state happened.

Important

This does not directly change the status of the service request in VectorCare. Instead, it logs timestamps for a predefined set of transport states. The service request’s actual status is managed separately by VectorCare based on the overall workflow.

One exception: service creators can configure an “autocomplete” state (such as arrived or on_board) that will mark the request as completed when you send that specific state. For example, if a service creator sets their autocomplete state to arrived, then posting the arrived state will immediately mark the request as completed (even before completed is sent). This is configured per-service and is not the default behavior.

Request Body

{
  "name": "en_route",
  "timestamp": "2025-01-15T14:30:00Z"
}

Field	Type	Description
name	string	State value (see table below)
timestamp	string	ISO 8601 UTC timestamp when the state occurred

Available States

State	Value	Description
En Route	en_route	En route to pickup location
Arrived	arrived	Arrived at pickup location
On Board	on_board	Patient on board at pickup location
Arrived at Destination	arrived_at_destination	Arrived at destination
Completed	completed	Trip complete
Canceled	canceled	Trip canceled (any reason)
Dry Run	dry_run	Trip canceled at pickup location

State Flow

A typical trip progresses through states in order:

en_route → arrived → on_board → arrived_at_destination → completed

However, any trip can also end with:

• canceled - Trip canceled before completion
• dry_run - Trip canceled after arriving at pickup (patient not available, etc.)

Example

curl -X POST "https://hub.vectorcare.com/openapi/v2.0/requests/KP-ABCD1234/state/" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "en_route",
    "timestamp": "2025-01-15T14:30:00Z"
  }'

Success (201 Created)

{
  "name": "en_route",
  "timestamp": "2025-01-15T14:30:00Z"
}

Timestamp Rules

• Must be in ISO 8601 format with UTC timezone (e.g., 2025-01-15T14:30:00Z)
• Cannot be in the future
• Must be within 7 days of the current time

Tip

Always use the actual time the event occurred, not the time you’re sending the request.

Errors

Status	Cause
400	Invalid state name, timestamp in future, or timestamp too old
401	Invalid or expired token
404	Request not found