> ## 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.

# API pour obtenir un compte bancaire : identifiants, titulaires et synchronisation

> L'endpoint Obtenir un compte de Didit renvoie un compte avec ses identifiants, titulaires, fraîcheur de synchronisation et couverture de l'historique.

L'endpoint « Get an Account » de Didit renvoie un compte avec ses identifiants, ses titulaires, la récence de sa synchronisation et la couverture de son historique.
`sync.last_synced_at` indique le moment où Didit a récupéré pour la dernière fois les données auprès de la banque.
Les identifiants complets nécessitent l'autorisation d'accès aux données bancaires activée sur votre clé.
Voir [Comptes, soldes et transactions](https://docs.didit.me/fr/core-technology/bank-verification/accounts-balances-transactions.md).


## OpenAPI

````yaml fr/openapi-25.json GET /v3/bank/accounts/{account_id}/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, connexions, comptes, soldes, transactions, établissements et
      couverture. Les données bancaires sont disponibles pour les applications
      en sandbox. Les appels d'une application en production renvoient `404`
      tant que l'accès en production n'est pas annoncé. Rien n'est facturé en
      sandbox. Un appel effectué avec une clé API doit utiliser une clé qui
      porte l'autorisation Données bancaires (`bank-data`) : lecture pour les
      lectures, écriture pour les opérations qui modifient quelque chose. La
      vérification de compte fait exception : elle nécessite un accès en
      écriture aux sessions, ou un accès complet, et non l'autorisation Données
      bancaires. Les données bancaires ne font pas partie de l'accès complet :
      une clé à accès complet est refusée, et l'appel renvoie `403
      bank_data_access_denied` tant que vous n'avez pas créé une clé portant
      cette autorisation. Une requête qui ne porte aucune clé API est également
      refusée pour les données bancaires brutes (comptes, soldes, transactions
      et flux des modifications).


      Chaque refus sous `/v3/bank/`, sauf celui de la vérification de compte, a
      le même corps JSON (`code`, `message`, `request_id`, `field`,
      `next_action`, `retry_after`). Un chemin qui n'est pas une opération, un
      identifiant qui n'est pas un UUID ou une sous-ressource inconnue renvoie
      `404 not_found` quelle que soit la méthode, et toute erreur inattendue
      renvoie `500 internal_error` avec un `request_id`. Lorsque les données
      bancaires ne sont pas disponibles, chaque opération renvoie le `404`
      standard de la plateforme, exactement comme une route inconnue.
paths:
  /v3/bank/accounts/{account_id}/:
    get:
      tags:
        - Bank Data
      summary: Obtenir un compte
      description: >-
        Renvoie un compte avec ses identifiants complets, ses titulaires, son
        état de synchronisation et `history_coverage`, qui indique ce que la
        banque a fourni de l'historique demandé. `sync.last_synced_at`
        correspond à la date à laquelle les données ont été récupérées auprès de
        la banque, et non à la date de votre lecture.


        Nécessite une clé API dotée de l'autorisation Données bancaires
        (`bank-data`) : lecture pour cette opération. Une clé à accès complet ne
        l'inclut pas : accordez-la explicitement lors de la création de la clé,
        faute de quoi l'appel renvoie `403 bank_data_access_denied`. Une
        application sandbox lit ses données de la Test Bank avec la seule clé.
        Une requête sans clé API (identifiants client) est refusée pour les
        données brutes avec le même `403`.
      operationId: getBankAccount
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: L'identifiant du compte.
      responses:
        '200':
          description: Le compte.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
              examples:
                Business account:
                  summary: Un compte courant professionnel en Espagne
                  value:
                    id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                    connection_id: 5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35
                    name: Cuenta negocio
                    product: Cuenta corriente empresas
                    type: current
                    usage: business
                    currency: EUR
                    holder_name: EMPRESA DE EJEMPLO SL
                    holders:
                      - name: EMPRESA DE EJEMPLO SL
                        role: holder
                    identifiers:
                      iban: ES0000000000000000001332
                      bic: XXXXESBBXXX
                      account_number: null
                      sort_code: null
                      other: []
                    account_ref: ar_f3c1a85e9d27b640c8e1
                    account_ref_previous: null
                    status: open
                    scopes_granted:
                      - accounts
                      - balances
                      - transactions
                    sync:
                      last_synced_at: '2026-11-21T12:04:40Z'
                      status: ok
                      history_requested_from: '2025-11-21'
                      history_available_from: '2026-01-02'
                      pending_supported: true
                    history_coverage:
                      requested_from: '2025-11-21'
                      oldest_booking_date: '2026-01-02'
                      covered_ranges:
                        - from: '2026-01-02'
                          to: '2026-11-21'
                      missing_ranges:
                        - from: '2025-11-21'
                          to: '2026-01-01'
                      status: partial
                      extended_auth_used: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '404':
          description: >-
            La ressource n'existe pas dans cette application et cet
            environnement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: Introuvable
                  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: >-
            La personne ne partage plus ce compte (`access_removed`), ou la
            connexion a été supprimée ou ses données ne sont plus lisibles
            (`connection_not_active`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Access removed:
                  summary: Accès retiré
                  value:
                    code: access_removed
                    message: The person no longer shares this account.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '429':
          $ref: '#/components/responses/RateLimitedRead'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl
            'https://verification.didit.me/v3/bank/accounts/a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10/'
            \
              -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.get_account(
                "11111111-2222-3333-4444-555555555555",
            )
            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.getAccount("11111111-2222-3333-4444-555555555555");

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


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().getAccount("11111111-2222-3333-4444-555555555555");

            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->getAccount('11111111-2222-3333-4444-555555555555');

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


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            result =
            didit.bank.get_account("11111111-2222-3333-4444-555555555555")

            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.GetAccountAsync("11111111-2222-3333-4444-555555555555");

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BankAccount:
      type: object
      description: Un compte au sein d'une connexion.
      properties:
        id:
          type: string
          description: >-
            Identifiant du compte. Il appartient à la connexion et ne change
            jamais tant qu'il existe, renouvellements inclus.
          format: uuid
        connection_id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
        product:
          type: string
          description: Le nom du produit de la banque.
          nullable: true
        type:
          type: string
          enum:
            - current
            - savings
            - card
            - loan
            - investment
            - other
        usage:
          type: string
          enum:
            - personal
            - business
            - unknown
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: Code de devise ISO 4217.
        holder_name:
          type: string
          description: Nom du titulaire lorsque la banque le transmet.
          nullable: true
        holders:
          type: array
          items:
            $ref: '#/components/schemas/BankAccountHolder'
          description: >-
            Titulaires transmis par la banque. Seuls `holder` et `joint_holder`
            sont pris en compte pour l'actionnariat.
        identifiers:
          $ref: '#/components/schemas/BankAccountIdentifiers'
        account_ref:
          type: string
          description: >-
            Identifie un même compte bancaire entre les connexions d'une même
            application et d'un même environnement : il s'agit d'un hachage à
            clé des identifiants propres à la banque. `null` lorsque la banque
            ne fournit aucun identifiant fiable. Utilisez-le pour reconnaître un
            compte bancaire déjà connu.
          nullable: true
        account_ref_previous:
          type: string
          description: >-
            Le `account_ref` précédent, uniquement pour un alias vérifié, comme
            lors d'une migration bancaire.
          nullable: true
        status:
          type: string
          enum:
            - open
            - closed
            - access_removed
          description: >-
            `access_removed` : la personne a retiré le compte du périmètre du
            consentement. Il n'est plus synchronisé.
        scopes_granted:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        sync:
          $ref: '#/components/schemas/BankAccountSync'
        history_coverage:
          $ref: '#/components/schemas/BankHistoryCoverage'
      required:
        - id
        - connection_id
        - name
        - product
        - type
        - usage
        - currency
        - holder_name
        - holders
        - identifiers
        - account_ref
        - account_ref_previous
        - status
        - scopes_granted
        - sync
        - history_coverage
    BankDataError:
      type: object
      description: >-
        Corps d'erreur de toutes les opérations sur les données bancaires.
        Chaque champ est toujours présent.
      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: >-
            Code d'erreur lisible par machine. Fondez votre logique sur ce code,
            jamais sur `message`.
        message:
          type: string
          description: "Explication en langage clair pour un développeur. Le libellé peut changer\_; ne l'analysez pas."
        request_id:
          type: string
          description: >-
            Identifiant de cette requête. Indiquez-le lorsque vous contactez le
            support.
        field:
          type: string
          description: >-
            Le champ de la requête à corriger, lorsque l'erreur concerne un seul
            champ. Sinon `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: >-
            La prochaine étape à suivre, pour qu'un client puisse agir sans
            deviner. `null` lorsqu'il n'existe pas d'étape suivante standard.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Secondes à attendre avant de réessayer. Défini pour les erreurs de
            limite de débit et les erreurs temporaires, sinon `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
    BankAccountHolder:
      type: object
      properties:
        name:
          type: string
        role:
          type: string
          enum:
            - holder
            - joint_holder
            - representative
            - unknown
      required:
        - name
        - role
    BankAccountIdentifiers:
      type: object
      description: >-
        Identifiants complets, renvoyés aux appelants côté serveur disposant de
        l'autorisation sur les données bancaires.
      properties:
        iban:
          type: string
          description: IBAN complet, en majuscules et sans espaces.
          nullable: true
        bic:
          type: string
          nullable: true
        account_number:
          type: string
          description: Numéro de compte local, lorsque le compte n'a pas d'IBAN.
          nullable: true
        sort_code:
          type: string
          description: Code bancaire local, lorsque le compte n'a pas d'IBAN.
          nullable: true
        other:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
              value:
                type: string
            required:
              - scheme
              - value
          description: Tout autre identifiant fourni par la banque.
      required:
        - iban
        - bic
        - account_number
        - sort_code
        - other
    BankAccountSync:
      type: object
      properties:
        last_synced_at:
          type: string
          description: >-
            Quand les données du compte ont été récupérées pour la dernière fois
            auprès de la banque.
          format: date-time
          nullable: true
        status:
          type: string
          enum:
            - pending
            - ok
            - failed
        history_requested_from:
          type: string
          format: date
          nullable: true
        history_available_from:
          type: string
          description: >-
            La date de comptabilisation la plus ancienne que la banque a
            réellement fournie pour ce compte.
          format: date
          nullable: true
        pending_supported:
          type: boolean
          description: Indique si cette banque signale les transactions en attente.
      required:
        - last_synced_at
        - status
        - history_requested_from
        - history_available_from
        - pending_supported
    BankHistoryCoverage:
      type: object
      description: Ce que la banque a livré de l'historique demandé.
      properties:
        requested_from:
          type: string
          description: La date de début demandée.
          format: date
          nullable: true
        oldest_booking_date:
          type: string
          description: >-
            La date de comptabilisation la plus ancienne que la banque a
            réellement fournie.
          format: date
          nullable: true
        covered_ranges:
          type: array
          items:
            $ref: '#/components/schemas/BankDateRange'
        missing_ranges:
          type: array
          items:
            $ref: '#/components/schemas/BankDateRange'
        status:
          type: string
          enum:
            - complete
            - partial
            - empty
            - unavailable
            - unknown
          description: >-
            `partial` : la banque a fourni moins que demandé. `empty` : la
            banque a confirmé toute la fenêtre et n'a aucune transaction.
            `unavailable` : la banque n'a fourni aucun historique. `unknown` :
            pas encore connu.
        extended_auth_used:
          type: boolean
          description: >-
            `true` lorsque la personne a donné la confirmation supplémentaire
            que certaines banques demandent avant de libérer l'historique plus
            ancien.
      required:
        - requested_from
        - oldest_booking_date
        - covered_ranges
        - missing_ranges
        - status
        - extended_auth_used
    RateLimitBudgetError:
      type: object
      description: >-
        Renvoyé uniquement pour un refus de quota du middleware lié à la limite
        de débit. Les autres erreurs 429, y compris les conflits d'idempotence
        et les plafonds propres à chaque endpoint, ne garantissent pas ces
        champs de métadonnées.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: Message lisible de refus de budget existant.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: "Référence de support opaque\_: RL- suivi de 32 caractères hexadécimaux minuscules d'un UUID."
        limit:
          type: integer
          description: Budget du périmètre dépassé ; égal à X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: Budget restant, ramené à zéro ; égal à X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: >-
            Heure de réinitialisation de la fenêtre en secondes Unix ; égale à
            X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Durée de la fenêtre fixe en secondes, et non le temps d'attente
            restant. Respectez Retry-After avant de réessayer.
      example:
        detail: >-
          Write request rate limit exceeded. You can make up to 300 requests per
          minute.
        reference: RL-00000000000040008000000000000001
        limit: 300
        remaining: 0
        reset: 1794358860
        window_seconds: 60
    BankDateRange:
      type: object
      properties:
        from:
          type: string
          format: date
        to:
          type: string
          format: date
      required:
        - from
        - to
  responses:
    Unauthorized:
      description: Non autorisé
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Clé API invalide
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        La clé API ne dispose pas de l'autorisation Bank data (`bank-data`) ou,
        pour les données bancaires brutes d'une application en production, le
        paramètre d'application « Bank data in the API » est désactivé. Les
        données bancaires ne font pas partie de l'accès complet : une clé à
        accès complet, une clé limitée à d'autres ressources et une requête
        authentifiée sans clé API (identifiants client, pour les données brutes)
        sont toutes refusées avec ce corps de réponse. Créez donc une clé et
        accordez-lui explicitement l'autorisation. Ce refus intervient avant
        toute recherche : il ne dit donc rien de l'existence d'un objet.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: Données bancaires non autorisées
              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
    RateLimitedRead:
      description: >-
        Dépassement du budget de lecture du middleware. Respectez Retry-After
        avant de réessayer.
      headers:
        Retry-After:
          $ref: '#/components/headers/BudgetRetryAfter'
        X-RateLimit-Scope:
          $ref: '#/components/headers/BudgetXRateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/BudgetXRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/BudgetXRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/BudgetXRateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              GET request rate limit exceeded. You can make up to 600 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 600
            remaining: 0
            reset: 1794358860
            window_seconds: 60
    BankDataInternalError:
      description: >-
        Un problème s’est produit côté Didit. Toute erreur inattendue sous
        `/v3/bank/` répond dans le format d’erreur Bank, jamais par une page
        HTML : indiquez `request_id` au support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: Une erreur inattendue
              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
  headers:
    BudgetRetryAfter:
      description: >-
        Nombre de secondes à attendre, arrondi à la fenêtre suivante. Présent
        sur les refus liés au quota du middleware.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        Le périmètre dont le quota a été dépassé. Présent sur les refus liés au
        quota du middleware.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Budget du périmètre dépassé ; égal à la limite du corps. Présent sur les
        refus de budget du middleware.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Budget restant, ramené à zéro ; égal à remaining du corps. Présent lors
        des refus liés au budget du middleware.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Heure de réinitialisation en secondes Unix ; égale à reset dans le
        corps. Présent sur les refus liés au quota du middleware.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: "La clé API de votre application, disponible dans Developers -> API keys de la Business Console. La clé principale a un accès complet. Une clé nommée peut être limitée :\_aucun accès, lecture ou écriture par ressource, restreinte à certains workflows ou à certaines sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée\_; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou à cette action, ou que la requête provient d'une adresse hors de sa liste d'adresses IP\_; 404 sur une route de session signifie que la session se trouve hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL des images, vidéos et PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys."

````

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