> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Refresh a Bank Connection API: Sync Now

> Didit's Refresh a Bank Connection endpoint syncs now: 202 with the sync_id, or 200 with the finished sync when you wait up to 25 seconds.

Didit's Refresh a Bank Connection endpoint asks for a sync now and answers `202` with the `sync_id`.
Send `"wait": true` to hold up to 25 seconds and get the finished sync in one call, at no extra charge.
The bank limits unattended access, so the call can answer `429 refresh_limit_reached` with `Retry-After`.
See [Refresh bank data on demand](https://docs.didit.me/use-cases/refresh-bank-data-on-demand.md).


## OpenAPI

````yaml openapi-25.json POST /v3/bank/connections/{id}/refresh/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, connections, accounts, balances, transactions, institutions and
      coverage. Bank data is available for sandbox applications. A live
      application's calls answer `404` until live access is announced. Nothing
      is charged in sandbox. A call made with an API key needs a key that
      carries the Bank data permission (`bank-data`): read for reads, write for
      operations that change something. The account check is the exception: it
      needs write access to sessions, or full access, and not the Bank data
      permission. Bank data is not part of full access: a full-access key is
      refused, and the call answers `403 bank_data_access_denied` until you
      create a key that carries the permission. Raw bank data (accounts,
      balances, transactions and the change feed) also refuses a request that
      carries no API key.


      Every refusal under `/v3/bank/` except the account check's has the same
      JSON body (`code`, `message`, `request_id`, `field`, `next_action`,
      `retry_after`). A path that is not an operation, an id that is not a UUID
      or an unknown sub-resource answers `404 not_found` for every method, and
      any unexpected error answers `500 internal_error` with a `request_id`.
      Where Bank data is not available, every operation answers the platform's
      standard `404`, exactly as an unknown route does.
paths:
  /v3/bank/connections/{id}/refresh/:
    post:
      tags:
        - Bank Data
      summary: Refresh a bank connection
      description: >-
        Syncs now: reads the bank for new data at any moment. Answers `202` with
        the `sync_id`; if a sync is already running you get that same `sync_id`,
        not a second job. With `"wait": true` in the body, or the header
        `Prefer: wait=<seconds>` (up to 25), the call holds for up to 25 seconds
        and answers `200` with the finished sync (`outcome`, the per-account
        counts and `balances_changed`), so one request returns fresh data. If
        the bank has not answered in that time it answers `202`: read the sync
        with `get_sync_run` using the `sync_id`, or subscribe to
        `bank.sync.completed`. `bank.data.updated` follows only when the sync
        stores changes.


        Live syncs are included in the monthly price of the connection, like the
        automatic syncs: nothing extra is charged. The only limit is the bank's.
        Banks limit reads without the person present, for example to four a day
        (the Didit Test Bank in sandbox does the same). The automatic syncs of
        the day (`sync.frequency_per_day`) are set aside first and the rest are
        yours, so `sync.budgets` shows what is left and
        `sync.live_syncs_left_today` how many live syncs remain today. The
        automatic schedule never uses the last two reads of a day, so two live
        syncs always remain. When the budget is used up the call answers `429
        refresh_limit_reached` with `Retry-After` (the seconds until the budget
        resets, 1 to 86400) and a `sync` object with `live_syncs_left_today` and
        `budgets`. The limit is a ceiling set by the bank, not a promise of a
        number of syncs.


        When a sync stores changes, `bank.data.updated` tells you; then read the
        change feed.


        Needs an API key with the Bank data permission (`bank-data`): write for
        this operation, which changes something. A key with full access does not
        include it: grant it explicitly when you create the key, or the call
        answers `403 bank_data_access_denied`.


        Refreshing a deleted connection answers `409 connection_not_active`.
      operationId: refreshBankConnection
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The connection id.
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: Prefer
          in: header
          required: false
          schema:
            type: string
            example: wait=25
          description: >-
            `wait=<seconds>` holds the call for up to that many seconds, at most
            25, like `wait: true` in the body.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankRefreshRequest'
            examples:
              Wait for the result:
                summary: Wait for the result
                value:
                  wait: true
      responses:
        '200':
          description: The sync finished within 25 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankSyncCompleted'
              examples:
                Finished:
                  summary: A finished live sync
                  value:
                    id: d4a9e7b2-1c58-4f03-96ab-5e2d8c7f0b14
                    connection_id: 5e1d2a70-6b3c-4f8e-a1d9-0c7b2e4f8a36
                    trigger: requested
                    status: succeeded
                    started_at: '2026-11-21T12:30:02Z'
                    finished_at: '2026-11-21T12:30:09Z'
                    results:
                      - account_id: a71f0c2e-4d85-4b1a-9e63-2f8c0d5b7a14
                        resource: transactions
                        outcome: succeeded
                        added: 3
                        modified: 0
                        removed: 1
                        error: null
                    outcome: succeeded
                    balances_changed: true
                    error: null
        '202':
          description: >-
            Refresh accepted: queued or already running. With `wait`, the bank
            did not answer within 25 seconds: read the sync with the `sync_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankRefreshAccepted'
              examples:
                Queued:
                  summary: A sync was queued
                  value:
                    sync_id: d4a9e7b2-1c58-4f03-96ab-5e2d8c7f0b14
                    status: queued
                    next_refresh_at: null
        '400':
          description: >-
            The body is not valid, for example `wait` is not a boolean. `field`
            names it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Invalid request:
                  summary: Invalid request
                  value:
                    code: invalid_request
                    message: The request is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: wait
                    next_action: null
                    retry_after: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '404':
          description: The resource does not exist in this application and environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: Not found
                  value:
                    code: not_found
                    message: The resource does not exist.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '409':
          description: >-
            The connection cannot be refreshed: `connection_not_active`
            (revoked, paused, failed or deleted) or `consent_expired` (renew it
            first).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not active:
                  summary: Not active
                  value:
                    code: connection_not_active
                    message: This connection is not active.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: create_link
                    retry_after: null
                Consent expired:
                  summary: Consent expired
                  value:
                    code: consent_expired
                    message: The consent ended. Renew the connection to sync again.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: renew_connection
                    retry_after: null
        '429':
          description: The bank's budget for fetches without the person present is used up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankRefreshLimitError'
              examples:
                Refresh limit reached:
                  summary: Refresh limit reached
                  value:
                    code: refresh_limit_reached
                    message: >-
                      The bank's limit on fetches without the person present is
                      used up for today.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: retry_later
                    retry_after: 3600
                    sync:
                      live_syncs_left_today: 0
                      budgets:
                        - scope: connection
                          resource: all
                          limit: 4
                          remaining: 0
                          resets_at: '2026-11-22T00:00:00Z'
          headers:
            Retry-After:
              description: Seconds to wait before asking again.
              schema:
                type: integer
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl -X POST
            'https://verification.didit.me/v3/bank/connections/5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35/refresh/'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.refresh_connection(
                "11111111-2222-3333-4444-555555555555",
                wait=True,
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            const result = await
            didit.bank.refreshConnection("11111111-2222-3333-4444-555555555555",
            {
              wait: true,
            });

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.RefreshConnection(ctx, \"11111111-2222-3333-4444-555555555555\", didit.BankRefreshConnectionParams{\n\tBody: didit.BankRefreshRequest{\n\t\tWait: didit.Bool(true),\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.BankRefreshConnectionParams;

            import me.didit.types.BankRefreshRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().refreshConnection("11111111-2222-3333-4444-555555555555",
            BankRefreshConnectionParams.builder()
                    .wait_(true)
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->bank->refreshConnection('11111111-2222-3333-4444-555555555555',
            [
                'wait' => true,
            ]);

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.bank.refresh_connection(
              "11111111-2222-3333-4444-555555555555",
              wait: true
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Bank.RefreshConnectionAsync("11111111-2222-3333-4444-555555555555",
            new BankRefreshRequest

            {
                Wait = true,
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional retry-safety key you choose for one operation, up to 255
        characters (a UUID works). A request repeated with the same key,
        endpoint, query and body is answered with the first response, same
        status and same body, and runs and bills nothing a second time. The same
        key with another endpoint, query or body returns `409`
        `idempotency_key_reused`, and while the first request is still running,
        `409` `idempotency_key_in_progress` with `Retry-After`. A failed request
        (any `4xx` or `5xx`) is not stored, so you can send it again with the
        same key. Keys belong to your application, whether you call with an API
        key or an access token. See [Retries and
        idempotency](/integration/api-errors#retries-and-idempotency).
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankRefreshRequest:
      type: object
      description: Optional body of a refresh.
      properties:
        wait:
          type: boolean
          default: false
          description: >-
            `true` holds the call for up to 25 seconds and answers `200` with
            the finished sync, so one request returns fresh data. If the bank
            has not answered in that time the call answers `202`: read the sync
            with `get_sync_run` using the `sync_id`, or subscribe to
            `bank.sync.completed`. `bank.data.updated` follows only when the
            sync stores changes. The header `Prefer: wait=<seconds>` (up to 25)
            does the same.
    BankSyncCompleted:
      allOf:
        - $ref: '#/components/schemas/BankSyncRun'
        - type: object
          properties:
            outcome:
              type: string
              enum:
                - succeeded
                - partial
                - failed
              description: How the sync ended.
            balances_changed:
              type: boolean
              description: Whether any balance changed.
          required:
            - outcome
            - balances_changed
      description: >-
        A finished sync returned by a refresh with `wait`: the sync run with its
        `outcome`, the per-account counts in `results` and `balances_changed`.
    BankRefreshAccepted:
      type: object
      description: >-
        A refresh was accepted. A second call while a sync runs returns the same
        `sync_id`.
      properties:
        sync_id:
          type: string
          description: The sync that was queued, or the one already running.
          format: uuid
        status:
          type: string
          enum:
            - queued
            - running
        next_refresh_at:
          type: string
          description: >-
            The earliest moment a new refresh can be asked for. `null` unless a
            budget is used up.
          format: date-time
          nullable: true
      required:
        - sync_id
        - status
        - next_refresh_at
    BankDataError:
      type: object
      description: Error body of every Bank data operation. Every field is always present.
      properties:
        code:
          type: string
          enum:
            - ongoing_access_not_available
            - segment_not_available
            - window_not_available
            - history_window_ambiguous
            - redirect_url_not_registered
            - link_origin_not_allowed
            - bank_data_access_denied
            - connection_not_active
            - consent_expired
            - renewal_not_needed
            - renewal_window_expired
            - access_removed
            - refresh_limit_reached
            - cursor_expired
            - page_expired
            - invalid_cursor
            - page_token_mismatch
            - contract_rate_missing
            - insufficient_credits
            - invalid_request
            - not_found
            - internal_error
          description: Machine-readable error code. Branch on this, never on `message`.
        message:
          type: string
          description: >-
            Plain-language explanation for a developer. The wording can change;
            do not parse it.
        request_id:
          type: string
          description: Identifier of this request. Quote it when you contact support.
        field:
          type: string
          description: >-
            The request field to correct, when the error is about one field.
            Otherwise `null`.
          nullable: true
        next_action:
          type: string
          enum:
            - retry_later
            - renew_connection
            - create_link
            - restart_from_cursor
            - restart_read
            - top_up_balance
            - enable_bank_data_access
            - contact_support
            - null
          description: >-
            What to do next, so a client can act without guessing. `null` when
            there is no standard next step.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Seconds to wait before retrying. Set on rate-limit and temporary
            errors, otherwise `null`.
          nullable: true
      required:
        - code
        - message
        - request_id
        - field
        - next_action
        - retry_after
      example:
        code: ongoing_access_not_available
        message: >-
          This bank cannot keep access open. Use access one_time or choose
          another bank.
        request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
        field: institution_id
        next_action: create_link
        retry_after: null
    BankRefreshLimitError:
      allOf:
        - $ref: '#/components/schemas/BankDataError'
        - type: object
          properties:
            sync:
              type: object
              description: The connection's sync limits now.
              properties:
                live_syncs_left_today:
                  type: integer
                  nullable: true
                  minimum: 0
                budgets:
                  type: array
                  items:
                    $ref: '#/components/schemas/BankSyncBudget'
              required:
                - live_syncs_left_today
                - budgets
          required:
            - sync
      description: >-
        The refresh limit error with the connection's `sync` limits.
        `Retry-After` carries the seconds until the budget resets, between 1 and
        86400.
    BankSyncRun:
      type: object
      description: >-
        One synchronisation of a connection. Only initial, scheduled and
        requested syncs are listed.
      properties:
        id:
          type: string
          format: uuid
        connection_id:
          type: string
          format: uuid
        trigger:
          type: string
          enum:
            - initial
            - scheduled
            - requested
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - partial
            - failed
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/BankSyncRunResult'
          description: What the run did, per account and resource.
        error:
          type: object
          nullable: true
          description: >-
            Why the run failed as a whole. `null` when it did not. Errors of
            single accounts and resources are in `results`.
          properties:
            code:
              type: string
            message:
              type: string
            at:
              type: string
              format: date-time
          required:
            - code
            - message
            - at
      required:
        - id
        - connection_id
        - trigger
        - status
        - started_at
        - finished_at
        - results
        - error
    BankSyncBudget:
      type: object
      description: One bucket of the bank's limit on fetches without the person present.
      properties:
        scope:
          type: string
          enum:
            - connection
            - account
          description: What the bank counts the budget against.
        resource:
          type: string
          enum:
            - all
            - accounts
            - balances
            - transactions
        account_id:
          type: string
          description: The account, when `scope` is `account`.
          format: uuid
          nullable: true
        limit:
          type: integer
          description: >-
            How many times a day Didit may fetch from the bank without the
            person present, as the bank defines it. This is a ceiling set by the
            bank, not a promise.
        remaining:
          type: integer
          description: >-
            Fetches left for your refreshes in the current window. The reads
            kept for the automatic syncs are already taken out, and an automatic
            sync never takes the last two reads of the day, so two refreshes on
            demand always remain.
        resets_at:
          type: string
          description: When the window resets.
          format: date-time
      required:
        - scope
        - resource
        - limit
        - remaining
        - resets_at
    BankSyncRunResult:
      type: object
      properties:
        account_id:
          type: string
          description: '`null` for a connection-wide result.'
          format: uuid
          nullable: true
        resource:
          type: string
          enum:
            - accounts
            - balances
            - transactions
        outcome:
          type: string
          enum:
            - succeeded
            - failed
            - skipped
        added:
          type: integer
        modified:
          type: integer
        removed:
          type: integer
        error:
          allOf:
            - $ref: '#/components/schemas/BankSyncError'
          nullable: true
          description: Required when `outcome` is `failed`.
      required:
        - account_id
        - resource
        - outcome
        - added
        - modified
        - removed
        - error
    BankSyncError:
      type: object
      description: Why a sync failed.
      properties:
        code:
          type: string
          description: Didit error code.
        message:
          type: string
          description: Plain-language explanation.
        at:
          type: string
          description: When it happened. `null` on a per-account result.
          format: date-time
          nullable: true
      required:
        - code
        - message
        - at
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Invalid API Key
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        The API key does not carry the Bank data permission (`bank-data`), or,
        for raw bank data in a live application, the application setting "Bank
        data in the API" is off. Bank data is not part of full access: a
        full-access key, a key restricted to other resources and a request
        authenticated without an API key (client credentials, on raw data) are
        all refused with this body, so create a key and grant it explicitly. The
        refusal comes before any lookup, so it says nothing about whether an
        object exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: Bank data not allowed
              value:
                code: bank_data_access_denied
                message: >-
                  Bank data calls need an API key that carries the Bank data
                  permission.
                request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                field: null
                next_action: enable_bank_data_access
                retry_after: null
    BankDataInternalError:
      description: >-
        Something went wrong on Didit's side. Any unexpected error under
        `/v3/bank/` answers in the Bank error shape, never an HTML page: quote
        `request_id` to support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: An unexpected error
              value:
                code: internal_error
                message: >-
                  Something went wrong on our side. Quote the request_id to
                  support.
                request_id: 3f6a1c8e92b54d07a1e38c4b7f0d2e59
                field: null
                next_action: contact_support
                retry_after: null
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your application's API key, from Developers -> API keys in the Business
        Console. The primary key has full access. A named key can be scoped:
        none, read or write per resource, limited to some workflows or to
        approved sessions, to a list of IP addresses, and to an expiry date. 401
        means the key is wrong, revoked or expired; 403 means no key was sent,
        the key has no access to this resource or action, or the request came
        from an address outside its IP list; 404 on a session route means the
        session is outside the key's workflows or statuses. A key without media
        access receives image, video and PDF URLs as null, and a key without
        sessions write receives session links and tokens as null. See
        https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.