> ## 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.

# GET /v1/status — retrieve card delivery status

> GET /v1/status/{id} — fetch delivery status, predicted delivery window, confidence level, and UI suggestion for a dispatched card.

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

```bash theme={null}
GET https://api.varmo.fi/v1/status/{id}
```

## Path parameters

<ParamField path="id" type="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`).
</ParamField>

## Request headers

<ParamField header="Authorization" type="string" required>
  Your API key, passed as a Bearer token: `Bearer <API_KEY>`. Requests without a valid key return `401 Unauthorized`.
</ParamField>

<ParamField header="Accept" type="string">
  Set to `application/json` to explicitly request a JSON response body. Recommended for all requests.
</ParamField>

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.varmo.fi/v1/status/12b986fd-8f73-4a55-b1b1-1b3f203c7522 \
    --header 'Authorization: Bearer <API_KEY>' \
    --header 'Accept: application/json'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## Response fields (200 OK)

<ResponseField name="id" type="string" required>
  The dispatch UUID that uniquely identifies this card delivery record.
</ResponseField>

<ResponseField name="status" type="string" required>
  The current delivery status of the card. One of: `dispatched`, `in_transit`, `out_for_delivery`, `delivered`, `exception`.
</ResponseField>

<ResponseField name="dispatch_date" type="string" required>
  ISO 8601 timestamp indicating when the card entered the dispatch pipeline (e.g., `2026-04-29T14:22:01Z`).
</ResponseField>

<ResponseField name="destination" type="object" required>
  The destination address details for this card delivery.

  <Expandable title="properties">
    <ResponseField name="postal_code" type="string" required>
      The destination postal code used to compute the predicted delivery window.
    </ResponseField>

    <ResponseField name="country_code" type="string" required>
      ISO 3166-1 alpha-2 country code for the delivery destination (e.g., `FI`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="prediction" type="object" required>
  Varmo's delivery prediction for this card, based on historical data for the destination postal code and current carrier conditions.

  <Expandable title="properties">
    <ResponseField name="delivery_window" type="object" required>
      The predicted date range within which the card is expected to arrive.

      <Expandable title="properties">
        <ResponseField name="min" type="string" required>
          The earliest predicted delivery date in ISO 8601 format (e.g., `2026-05-02`).
        </ResponseField>

        <ResponseField name="max" type="string" required>
          The latest predicted delivery date in ISO 8601 format (e.g., `2026-05-04`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="confidence_level" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ui_suggestion" type="object" required>
  Ready-to-use copy and action recommendation for displaying card delivery status in your product UI.

  <Expandable title="properties">
    <ResponseField name="locale" type="string" required>
      The BCP 47 locale tag used to generate the `recommended_message` (e.g., `en-US`).
    </ResponseField>

    <ResponseField name="recommended_message" type="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."`).
    </ResponseField>

    <ResponseField name="recommended_action" type="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).
    </ResponseField>
  </Expandable>
</ResponseField>

## Full example response

```json theme={null}
{
  "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

<Note>
  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](/api-reference/errors) for more detail.
</Note>