> ## 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 actualizará tus cuentas y te notificará con los resultados a través del [sistema de webhooks](/es/docs/resources/webhooks-walkthrough).\ Cuando la actualización se complete exitosamente, recibirás el evento [`account.refresh_intent.succeeded`](/es/reference/main-resources/events-reference/types-of-events). Después de eso, puedes solicitar inmediatamente a la API de Fintoc los movimientos bancarios más recientes.\ Cuando la actualización falle o el banco indique que las credenciales no son válidas, recibirás los eventos `account.refresh_intent.failed` y `account.refresh_intent.rejected` respectivamente. Existen algunas restricciones para solicitar una actualización *on-demand*. Por ejemplo, no puedes crear un `Refresh Intent` si hay otro en curso. Además, si el `refresh_type` es de tipo `only_last`, debes esperar **cinco** minutos entre Refresh Intents. Si el `refresh_type` es de tipo `historical`, debes esperar **sesenta** minutos entre 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 ````