Refreshing Claims

To retrieve the most up-to-date balance information for a specific claim, you’ll need to refresh it.

Before refreshing a claim, ensure you have a valid account_holder_id.

All claim refreshes are asynchronous operations. You will receive a webhook notification once the refresh is complete. For more details, refer to our Claim Refresh Webhook Documentation.

Refreshing a Claim Copied

To initiate a claim refresh, use the following endpoint:

POST /v1/verify/claims/{id}/refresh

Request:

curl https://api.hoseki.app/api/v1/verify/claims/{claim_id)/refresh \
  --request POST \
  --header 'Accept: /' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "permissions": [
    "balances"
  ]
}'

Response:

{
  "id": "vy_clac_VDuR6hmjILpF03nabeFaV",
  "created_at": 1615766400,
  "account_holder_id": "ah_ezwIXuhcaxO749oDQdZef",
  "display_name": "My favorite address",
  "status": "active",
  "currency": "BTC",
  "balance": {
    "as_of": 1615766400,
    "current": "5306287072",
    "available": "5306287072"
  },
  "balance_refresh": {
    "last_attempted_at": 1615766400,
    "status": "succeeded",
    "next_available_at": 1615802400
  }
}

Permissions: Copied

When refreshing a claim, you must specify the permission for the data you want to update.

Currently, only the balances permission is supported for claim refreshes.

Balance Refreshes: Copied

After a balance refresh is completed, Hoseki sets the next available refresh time using the balance_refresh.next_refresh_available_at field.

Before initiating a new balance refresh, check this field to ensure a refresh is currently allowed. If either of the following conditions is true, the refresh request will be rejected:

• The next_refresh_available_at field is null (which indicates the previous refresh is still pending or the account is inactive).

• The current time is earlier than the next_refresh_available_at timestamp.