---
title: "Create a refresh intent"
method: POST
path: "/refresh_intents"
tags: ["Refresh intents"]
---

# Create a refresh intent

`POST /refresh_intents`

Creates a refresh intent for a link, using the link's `link_token` to authenticate the request. Unless the institution requires multi-factor authentication, the refresh starts asynchronously and Fintoc notifies the result through webhooks. Your organization needs the on demand refresh policy, and Fintoc rate limits consecutive refreshes (5 minutes between `only_last` refreshes, 60 minutes between `historical` ones).

## Query parameters

- `link_token` string, required
- `refresh_type` 'only_last' | 'historical'
- `result_status` 'succeeded' | 'failed' | 'rejected'

## Response `201`

Refresh intent created. If `requires_mfa` is `null` the refresh starts immediately; otherwise complete the multi-factor authentication in the widget with `requires_mfa.widget_token`.

- RefreshIntent
  - `id` string, required — Unique identifier of the refresh intent.
  - `object` 'refresh_intent', required — Type of the object. Always `refresh_intent`.
  - `created_at` string, date-time, required — ISO 8601 timestamp of when the refresh intent was created.
  - `new_movements` integer — Number of new movements the refresh fetched. Only present when `refreshed_object` is `account` (for example, in webhook payloads).
  - `public_error` 'retryable_error' | 'support_required_error' | 'null', nullable, required — Reason for the failure. `retryable_error` means you can retry the refresh, `support_required_error` means you need to contact Fintoc support. `null` unless `status` is `failed`.
  - `refreshed_object` 'link' | 'account', required — Type of the object being refreshed. The refresh intents API always returns `link` refresh intents.
  - `refreshed_object_id` string, required — Identifier of the object being refreshed.
  - `requires_mfa` object, nullable, required — Present when the institution requires multi-factor authentication to complete the refresh; contains the `widget_token` needed to resume the flow in the widget. `null` otherwise. Only included when `refreshed_object` is `link`.
    - `widget_token` string — Token used to initialize the Fintoc widget to complete the multi-factor authentication.
  - `status` 'created' | 'waiting_for_action' | 'requires_action' | 'processing_action' | 'rejected' | 'failed' | 'succeeded' | 'canceled', required — Status of the refresh intent. `rejected` means the institution rejected the stored credentials.
  - `type` 'only_last' | 'historical', required — Type of the refresh. `only_last` fetches the most recent movements, `historical` fetches the full history of movements.

## Other responses

- `400` — Invalid request: the `link_token` is missing or empty, the `refresh_type` is invalid, another refresh intent is in progress, you exceeded the rate limit, or the institution rejected the stored credentials.
- `401` — Invalid or missing API key.
- `402` — The organization cannot refresh links: the trial window expired or a payment is pending.
- `403` — The `link_token` is invalid, the organization does not have the on demand refresh policy, or every account of the link is already up to date.

---

[API](https://skmtc.net/fintoc/apis/fintoc-api.md) · [All operations](https://skmtc.net/fintoc/apis/fintoc-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fintoc/fintoc-api/revisions/9dafa63688a3/schema)