GET /v1/status — retrieve card delivery status

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

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

string

required

Your API key, passed as a Bearer token: Bearer <API_KEY>. Requests without a valid key return 401 Unauthorized.

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'

const response = await fetch(
  'https://api.varmo.fi/v1/status/12b986fd-8f73-4a55-b1b1-1b3f203c7522',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer <API_KEY>',
      'Accept': 'application/json',
    },
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.varmo.fi/v1/status/12b986fd-8f73-4a55-b1b1-1b3f203c7522',
    headers={
        'Authorization': 'Bearer <API_KEY>',
        'Accept': 'application/json',
    },
)

data = response.json()
print(data)

Response fields (200 OK)

string

required

The dispatch UUID that uniquely identifies this card delivery record.

string

required

The current delivery status of the card. One of: dispatched, in_transit, out_for_delivery, delivered, exception.

string

required

ISO 8601 timestamp indicating when the card entered the dispatch pipeline (e.g., 2026-04-29T14:22:01Z).

object

required

The destination address details for this card delivery.

Show properties

string

required

The destination postal code used to compute the predicted delivery window.

string

required

ISO 3166-1 alpha-2 country code for the delivery destination (e.g., FI).

object

required

Varmo’s delivery prediction for this card, based on historical data for the destination postal code and current carrier conditions.

Show properties

object

required

The predicted date range within which the card is expected to arrive.

Show properties

string

required

The earliest predicted delivery date in ISO 8601 format (e.g., 2026-05-02).

string

required

The latest predicted delivery date in ISO 8601 format (e.g., 2026-05-04).

string

required

How confident Varmo is in the delivery window prediction. One of: High, Medium, Low. Low confidence indicates sparse historical data for the destination postal code, resulting in a wider delivery window.

object

required

Ready-to-use copy and action recommendation for displaying card delivery status in your product UI.

Show properties

string

required

The BCP 47 locale tag used to generate the recommended_message (e.g., en-US).

string

required

A plain-language string you can display directly to your end user describing the expected delivery timeline (e.g., "Your card is likely arriving in the next 1-2 days.").

string

required

An action you should surface to the user alongside the message. One of: None (no action needed), Activate (prompt the user to activate their card), ContactSupport (direct the user to contact support due to a delivery exception).

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.

​Endpoint

​Path parameters

​Request headers

​Example request

​Response fields (200 OK)

​Full example response

​Rate limits

Endpoint

Path parameters

Request headers

Example request

Response fields (200 OK)

Full example response

Rate limits