> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a refresh intent > 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). **`v1`** ยท Base URL `https://api.fintoc.com/v1` Fintoc will update your accounts and notify you with the results through the [webhook system](/docs/resources/webhooks-walkthrough).\ When the update is completed successfully, you will receive the event [`account.refresh_intent.succeeded`](/reference/main-resources/events-reference/types-of-events). After that, you can immediately request the Fintoc API for the newest bank movements.\ When the update fails or the bank indicates that the credentials are invalid, you will receive the events `account.refresh_intent.failed` and `account.refresh_intent.rejected` respectively. Some restrictions exist to request an *on-demand* update. For example, you can't create a `Refresh Intent` if there is another one in progress. Also, if the `refresh_type` is of type `only_last` you must wait **five** minutes between Refresh Intents. If the `refresh_type` is of type `historical` you must wait **sixty** minutes between Refresh Intents. ## OpenAPI ````yaml reference/fintoc-api.json POST /refresh_intents openapi: 3.1.0 info: title: fintoc-api version: v2026-02-01 servers: - url: https://api.fintoc.com/v1 security: [] paths: /refresh_intents: post: tags: - Refresh intents summary: Create a refresh intent description: >- 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). operationId: refresh-intents-create parameters: - name: link_token in: query required: true schema: type: string example: link_Q0xVGPvijElLRMwE_token_FhsFVurz5q5FycHA5xxhTpzX description: >- The `link_token` of the link to refresh, obtained when you exchanged the link. - name: refresh_type in: query required: false schema: type: string enum: - only_last - historical description: >- The statement to refresh. `only_last` retrieves the provisional statement, `historical` retrieves the historical statement. Defaults to `only_last`. - name: result_status in: query required: false schema: type: string enum: - succeeded - failed - rejected description: >- Result to force on the refresh intent in `test` mode. Has no effect in `live` mode. responses: '201': description: >- 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`. content: application/json: examples: refresh_intent_created: value: id: ri_2dXqkOKkS9mOvnaW object: refresh_intent created_at: '2021-08-23T18:22:46.792Z' public_error: null refreshed_object: link refreshed_object_id: link_nzwA3XWYiZkg4ojK requires_mfa: null status: created type: only_last schema: $ref: '#/components/schemas/refresh_intent' '400': description: >- 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. content: application/json: examples: rate_limit_exceeded: value: error: type: invalid_request_error code: rate_limit_exceeded message: >- This Link was recently refreshed. You have to wait at least 5 minutes between refresh intents doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '401': description: Invalid or missing API key. content: application/json: examples: invalid_api_key: value: error: type: authentication_error code: invalid_api_key message: 'Invalid API Key: invalid-*oken' schema: $ref: '#/components/schemas/error_object' '402': description: >- The organization cannot refresh links: the trial window expired or a payment is pending. content: application/json: examples: payment_required: value: error: type: api_error code: payment_required message: >- Your trial window expired or you have a pending payment. If you think that this is an error, send an email to soporte@fintoc.com. To catch up on payments, email billing@fintoc.com. doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '403': description: >- 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. content: application/json: examples: on_demand_policy_required: value: error: type: authorization_error code: on_demand_policy_required message: >- Your organization does not have access to on demand refreshes. Send an email to sales@fintoc.com to hire this refresh method. doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' security: - api_key: [] components: schemas: refresh_intent: type: object properties: id: type: string description: Unique identifier of the refresh intent. example: ri_2dXqkOKkS9mOvnaW object: const: refresh_intent description: Type of the object. Always `refresh_intent`. created_at: type: string format: date-time description: ISO 8601 timestamp of when the refresh intent was created. example: '2021-08-23T18:22:46.792Z' new_movements: type: integer description: >- Number of new movements the refresh fetched. Only present when `refreshed_object` is `account` (for example, in webhook payloads). example: 12 public_error: type: - string - 'null' enum: - retryable_error - support_required_error - null description: >- 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`. example: null refreshed_object: type: string enum: - link - account description: >- Type of the object being refreshed. The refresh intents API always returns `link` refresh intents. example: link refreshed_object_id: type: string description: Identifier of the object being refreshed. example: link_nzwA3XWYiZkg4ojK requires_mfa: type: - object - 'null' description: >- 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`. properties: widget_token: type: string description: >- Token used to initialize the Fintoc widget to complete the multi-factor authentication. example: ri_2dXqkOKkS9mOvnaW_sec_Q802GD8ZLmMuK0Atl4ucJuLp status: type: string enum: - created - waiting_for_action - requires_action - processing_action - rejected - failed - succeeded - canceled description: >- Status of the refresh intent. `rejected` means the institution rejected the stored credentials. example: succeeded type: type: string enum: - only_last - historical description: >- Type of the refresh. `only_last` fetches the most recent movements, `historical` fetches the full history of movements. example: only_last required: - id - object - refreshed_object - refreshed_object_id - requires_mfa - status - created_at - type - public_error error_object: type: object properties: error: type: object description: Details of the error that caused the request to fail. properties: code: type: string description: >- Machine-readable code identifying the specific error, for example `invalid_api_key`. Not returned by every error. example: invalid_api_key doc_url: type: string description: >- URL of a documentation page with more details about the error. Not returned by every error. example: https://docs.fintoc.com/reference/errors message: type: string description: Human-readable message describing the error. example: 'Invalid API Key: invalid-*oken' param: type: - string - 'null' description: >- Name of the request parameter that caused the error. `null` when the error cannot be tied to a single parameter, and not returned by every error. example: amount type: type: string description: >- Category of the error, for example `invalid_request_error`, `authentication_error`, or `api_error`. example: invalid_request_error required: - type - message securitySchemes: api_key: type: apiKey name: Authorization in: header ````