> ## 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: 식별자, 명의인 및 동기화

> Didit의 계좌 조회 엔드포인트는 계좌 한 건의 식별자, 명의인, 동기화 최신성, 이력 범위를 반환합니다.

Didit의 계좌 조회(Get an Account) 엔드포인트는 계좌 하나를 반환하며, 여기에는 식별자, 명의자, 동기화 최신 상태와 이력 범위가 포함됩니다.
`sync.last_synced_at`은 Didit이 은행에서 마지막으로 데이터를 가져온 시점입니다.
전체 식별자를 확인하려면 API 키에 은행 데이터 권한이 있어야 합니다.
자세한 내용은 [계좌, 잔액 및 거래](https://docs.didit.me/ko/core-technology/bank-verification/accounts-balances-transactions.md)를 참고하십시오.


## OpenAPI

````yaml ko/openapi-25.json GET /v3/bank/accounts/{account_id}/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 신원 인증 API입니다. x-api-key 헤더로 인증하십시오.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, 연결, 계정, 잔액, 거래, 기관 및 적용 범위. 은행 데이터는 샌드박스 애플리케이션에서 사용할 수 있습니다.
      라이브 애플리케이션의 호출은 라이브 액세스가 공지될 때까지 `404`로 응답합니다. 샌드박스에서는 요금이 부과되지 않습니다. API
      키로 수행하는 호출에는 은행 데이터 권한(`bank-data`)이 있는 키가 필요합니다. 읽기에는 read, 무언가를 변경하는
      작업에는 write 권한이 필요합니다. 계정 확인은 예외입니다. 이 경우에는 은행 데이터 권한이 아니라 세션에 대한 write 액세스
      또는 전체 액세스가 필요합니다. 은행 데이터는 전체 액세스에 포함되지 않습니다. 전체 액세스 키는 거부되며, 해당 권한이 있는 키를
      생성할 때까지 호출은 `403 bank_data_access_denied`로 응답합니다. 원시 은행 데이터(계정, 잔액, 거래 및
      변경 피드)도 API 키가 없는 요청은 거부합니다.


      `/v3/bank/` 아래에서 계정 확인을 제외한 모든 거부 응답은 동일한 JSON 본문(`code`, `message`,
      `request_id`, `field`, `next_action`, `retry_after`)을 가집니다. 작업이 아닌 경로,
      UUID가 아닌 ID 또는 알 수 없는 하위 리소스는 모든 메서드에 대해 `404 not_found`로 응답하며, 예상치 못한 오류는
      `request_id`와 함께 `500 internal_error`로 응답합니다. 은행 데이터를 사용할 수 없는 경우 모든 작업은 알
      수 없는 경로와 마찬가지로 플랫폼의 표준 `404`로 응답합니다.
paths:
  /v3/bank/accounts/{account_id}/:
    get:
      tags:
        - Bank Data
      summary: 계좌 조회
      description: >-
        하나의 계좌를 반환하며, 전체 식별자, 계좌 소유자, 동기화 상태, `history_coverage`를 포함합니다. 이 필드는
        요청한 내역 중 은행이 실제로 전달한 범위를 나타냅니다. `sync.last_synced_at`은 은행에서 데이터를 가져온
        시점이며, 사용자가 데이터를 읽은 시점이 아닙니다.


        은행 데이터 권한(`bank-data`)이 있는 API 키가 필요하며, 이 작업은 읽기 권한을 사용합니다. 전체 액세스 키에는 이
        권한이 포함되지 않으므로, 키를 생성할 때 명시적으로 부여해야 합니다. 그렇지 않으면 호출 시 `403
        bank_data_access_denied`가 반환됩니다. 샌드박스 애플리케이션은 API 키만으로 Test Bank 데이터를 읽을
        수 있습니다. API 키 없이(클라이언트 자격 증명) 보낸 요청은 원시 데이터에 대해 같은 `403`으로 거부됩니다.
      operationId: getBankAccount
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: 계좌 ID입니다.
      responses:
        '200':
          description: 계좌입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
              examples:
                Business account:
                  summary: 스페인의 기업 당좌 계좌
                  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: 이 애플리케이션과 환경에 리소스가 존재하지 않습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: 찾을 수 없음
                  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: >-
            사용자가 더 이상 이 계정을 공유하지 않거나(`access_removed`), 연결이 삭제되었거나 데이터를 더 이상 읽을
            수 없는 경우(`connection_not_active`)입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Access removed:
                  summary: 액세스 제거됨
                  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: 연결 내의 계좌 하나입니다.
      properties:
        id:
          type: string
          description: 계정 ID입니다. 연결에 속하며, 갱신을 포함하여 존재하는 동안 절대 변경되지 않습니다.
          format: uuid
        connection_id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
        product:
          type: string
          description: 은행의 상품 이름입니다.
          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: ISO 4217 통화 코드입니다.
        holder_name:
          type: string
          description: 은행이 공유하는 경우 명의인 이름입니다.
          nullable: true
        holders:
          type: array
          items:
            $ref: '#/components/schemas/BankAccountHolder'
          description: 은행이 공유하는 명의인입니다. 소유권은 `holder`와 `joint_holder`만 집계합니다.
        identifiers:
          $ref: '#/components/schemas/BankAccountIdentifiers'
        account_ref:
          type: string
          description: >-
            같은 애플리케이션 및 환경의 여러 연결에 걸쳐 같은 은행 계좌를 식별합니다. 은행 고유 식별자의 키 기반 해시입니다.
            은행이 신뢰할 수 있는 식별자를 제공하지 않으면 `null`입니다. 이미 알고 있는 은행 계좌를 인식하는 데 사용합니다.
          nullable: true
        account_ref_previous:
          type: string
          description: 이전 `account_ref`입니다. 은행 이전과 같이 검증된 별칭에 대해서만 사용됩니다.
          nullable: true
        status:
          type: string
          enum:
            - open
            - closed
            - access_removed
          description: '`access_removed`: 최종 사용자가 동의에서 계정을 제거했습니다. 더 이상 동기화되지 않습니다.'
        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: 모든 은행 데이터 작업의 오류 본문입니다. 모든 필드가 항상 포함됩니다.
      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: 기계가 읽을 수 있는 오류 코드입니다. 분기 처리는 이 값으로 하고, `message`로는 하지 마십시오.
        message:
          type: string
          description: 개발자를 위한 쉬운 설명입니다. 문구는 변경될 수 있으므로 파싱하지 않아야 합니다.
        request_id:
          type: string
          description: 이 요청의 ID입니다. 지원팀에 문의할 때 이 값을 알려 주십시오.
        field:
          type: string
          description: 오류가 하나의 필드와 관련된 경우 수정해야 할 요청 필드입니다. 그렇지 않으면 `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: 클라이언트가 추측하지 않고 조치할 수 있도록 다음 단계를 안내합니다. 표준 다음 단계가 없으면 `null`입니다.
          nullable: true
        retry_after:
          type: integer
          description: 재시도 전에 기다릴 시간(초)입니다. 속도 제한 및 일시적 오류에 설정되며, 그 외에는 `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: 전체 식별자이며, 은행 데이터 권한이 있는 서버 측 호출자에게만 반환됩니다.
      properties:
        iban:
          type: string
          description: 전체 IBAN이며, 대문자이고 공백이 없습니다.
          nullable: true
        bic:
          type: string
          nullable: true
        account_number:
          type: string
          description: 계좌에 IBAN이 없는 경우 현지 계좌 번호입니다.
          nullable: true
        sort_code:
          type: string
          description: 계좌에 IBAN이 없는 경우 현지 은행 코드입니다.
          nullable: true
        other:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
              value:
                type: string
            required:
              - scheme
              - value
          description: 은행이 제공하는 기타 식별자입니다.
      required:
        - iban
        - bic
        - account_number
        - sort_code
        - other
    BankAccountSync:
      type: object
      properties:
        last_synced_at:
          type: string
          description: 계좌 데이터를 은행에서 마지막으로 가져온 시점입니다.
          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: 이 계정에 대해 은행이 실제로 제공한 가장 이른 기장일입니다.
          format: date
          nullable: true
        pending_supported:
          type: boolean
          description: 이 은행이 보류 중인 거래를 보고하는지 여부입니다.
      required:
        - last_synced_at
        - status
        - history_requested_from
        - history_available_from
        - pending_supported
    BankHistoryCoverage:
      type: object
      description: 요청한 이력 중 은행이 실제로 제공한 범위입니다.
      properties:
        requested_from:
          type: string
          description: 요청된 시작일입니다.
          format: date
          nullable: true
        oldest_booking_date:
          type: string
          description: 은행이 실제로 제공한 가장 이른 기장일입니다.
          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`: 은행이 요청보다 적은 데이터를 제공했습니다. `empty`: 은행이 전체 기간을 확인했으며 거래가
            없습니다. `unavailable`: 은행이 내역을 제공하지 않았습니다. `unknown`: 아직 알 수 없습니다.
        extended_auth_used:
          type: boolean
          description: 사용자가 일부 은행이 이전 이력을 공개하기 전에 요구하는 추가 확인 절차를 완료한 경우 `true`입니다.
      required:
        - requested_from
        - oldest_booking_date
        - covered_ranges
        - missing_ranges
        - status
        - extended_auth_used
    RateLimitBudgetError:
      type: object
      description: >-
        속도 제한 미들웨어 예산 거부 응답에만 반환됩니다. 멱등성 충돌과 엔드포인트별 상한을 포함한 다른 429 오류는 이 메타데이터
        필드를 보장하지 않습니다.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: 기존의 사람이 읽을 수 있는 예산 거부 메시지입니다.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: 불투명한 지원 참조 번호입니다. RL- 뒤에 소문자 UUID 16진수 문자 32자가 이어집니다.
        limit:
          type: integer
          description: 초과된 범위의 예산입니다. X-RateLimit-Limit 값과 같습니다.
        remaining:
          type: integer
          minimum: 0
          description: 남은 예산이며 0 미만으로 내려가지 않습니다. X-RateLimit-Remaining과 같습니다.
        reset:
          type: integer
          format: int64
          description: Unix 초 단위의 윈도우 재설정 시간이며 X-RateLimit-Reset 값과 같습니다.
        window_seconds:
          type: integer
          description: 고정 윈도우 기간(초 단위)이며, 남은 대기 시간이 아닙니다. 재시도하기 전에 Retry-After 값을 준수해야 합니다.
      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: 인증되지 않음
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: 잘못된 API 키
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        API 키에 은행 데이터 권한(`bank-data`)이 없거나, 프로덕션 애플리케이션에서 원시 은행 데이터를 조회하는 경우
        애플리케이션 설정 "Bank data in the API"가 꺼져 있습니다. 은행 데이터는 전체 액세스 권한에 포함되지 않습니다.
        전체 액세스 키, 다른 리소스로 제한된 키, 그리고 API 키 없이 인증된 요청(클라이언트 자격 증명, 원시 데이터 대상)은 모두
        이 응답으로 거부됩니다. 따라서 키를 새로 만들고 명시적으로 권한을 부여하십시오. 이 거부는 어떤 조회보다 먼저 이루어지므로,
        객체의 존재 여부와는 관계가 없습니다.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: 은행 데이터 접근이 허용되지 않음
              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: 미들웨어 읽기 예산을 초과했습니다. 재시도하기 전에 Retry-After를 따르세요.
      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: >-
        Didit 측에서 문제가 발생했습니다. `/v3/bank/` 아래의 예기치 않은 오류는 HTML 페이지가 아닌 Bank 오류
        형식으로 응답합니다. 지원팀에 `request_id`를 알려 주십시오.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: 예상치 못한 오류
              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: 다음 윈도우까지 기다려야 하는 시간(초)을 올림한 값입니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: 예산을 초과한 범위입니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: 초과된 범위의 예산입니다. 본문 한도와 같습니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: 남은 예산이며 0 미만으로 내려가지 않습니다. 본문의 remaining과 같습니다. 미들웨어 예산 거부 응답에만 있습니다.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: Unix 초 단위의 재설정 시간이며 본문의 reset 값과 같습니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        귀사 애플리케이션의 API 키입니다. Business Console의 Developers -> API keys에서 확인할 수
        있습니다. 기본 키는 모든 권한을 가집니다. 명명된 키는 범위를 지정할 수 있습니다. 리소스별로 권한 없음, 읽기 또는 쓰기를
        설정할 수 있고, 일부 워크플로나 승인된 세션으로 제한할 수 있으며, 허용된 IP 목록으로 제한할 수 있고, 만료일을 설정할 수
        있습니다. 401은 키가 잘못되었거나, 취소되었거나, 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스
        또는 작업에 대한 권한이 없거나, 요청이 IP 목록 밖의 주소에서 왔음을 의미합니다. 세션 경로에서 발생한 404는 세션이 키의
        워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 동영상 및 PDF URL을 null로
        받으며, 세션 쓰기 권한이 없는 키는 세션 링크와 토큰을 null로 받습니다. 자세한 내용은
        https://docs.didit.me/console/api-keys 를 참조합니다.

````

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