Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.varmo.fi/llms.txt

Use this file to discover all available pages before exploring further.

Use this endpoint to retrieve the current delivery status, predicted delivery window, and UI copy recommendation for a specific dispatched card. Call it after a card has been dispatched to poll for status updates or to render real-time delivery progress in your product.

​
Endpoint

GET https://api.varmo.fi/v1/status/{id}

​
Path parameters

​
id
string
required
The dispatch identifier assigned to the card when it was dispatched. Must be a valid UUID v4 (e.g., 12b986fd-8f73-4a55-b1b1-1b3f203c7522).

​
Request headers

​
Authorization
string
required
Your API key, passed as a Bearer token: Bearer <API_KEY>. Requests without a valid key return 401 Unauthorized.
​
Accept
string
Set to application/json to explicitly request a JSON response body. Recommended for all requests.

​
Example request

curl --request GET \
  --url https://api.varmo.fi/v1/status/12b986fd-8f73-4a55-b1b1-1b3f203c7522 \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Accept: application/json'

​
Response fields (200 OK)

​
id
string
required
The dispatch UUID that uniquely identifies this card delivery record.
​
status
string
required
The current delivery status of the card. One of: dispatched, in_transit, out_for_delivery, delivered, exception.
​
dispatch_date
string
required
ISO 8601 timestamp indicating when the card entered the dispatch pipeline (e.g., 2026-04-29T14:22:01Z).
​
destination
object
required
The destination address details for this card delivery.
​
prediction
object
required
Varmo’s delivery prediction for this card, based on historical data for the destination postal code and current carrier conditions.
​
ui_suggestion
object
required
Ready-to-use copy and action recommendation for displaying card delivery status in your product UI.

​
Full example response

{
  "id": "12b986fd-8f73-4a55-b1b1-1b3f203c7522",
  "status": "dispatched",
  "dispatch_date": "2026-04-29T14:22:01Z",
  "destination": {
    "postal_code": "00100",
    "country_code": "FI"
  },
  "prediction": {
    "delivery_window": {
      "min": "2026-05-02",
      "max": "2026-05-04"
    },
    "confidence_level": "High"
  },
  "ui_suggestion": {
    "locale": "en-US",
    "recommended_message": "Your card is likely arriving in the next 1-2 days.",
    "recommended_action": "None"
  }
}

​
Rate limits

Each API key is limited to 1,000 requests per minute. Every response includes the following headers so you can track your usage:
  • X-RateLimit-Limit — the maximum number of requests allowed per minute for your key.
  • X-RateLimit-Remaining — the number of requests remaining in the current one-minute window.
  • X-RateLimit-Reset — the UTC epoch timestamp at which your rate limit window resets.
If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying. See Errors for more detail.