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

# Identify an account

> Resolve a bank or wallet identifier to the institution behind it, the rails that can reach it, and — on supported rails — the holder name. Charged on an `identified` outcome. Promo credits cover first calls; there is no complimentary test lane.




## OpenAPI

````yaml /openapi.yaml post /v1/identify
openapi: 3.1.0
info:
  title: Patchwork API
  version: 1.0.0
  description: >
    Public data-plane API. Two products today: Identify (bare account
    resolution) and Loom (threads, runs, and outcomes). Every response is a JSON
    envelope — `status: success` with `data`, or `status: error` with `error`.
  contact:
    url: https://usepatchwork.co
servers:
  - url: https://api.usepatchwork.co
security:
  - bearerAuth: []
tags:
  - name: Identify
    description: Resolve an account or wallet to the institution and rails behind it.
  - name: Loom
    description: Threads, messages, runs, and outcomes for an embedded agent.
paths:
  /v1/identify:
    post:
      tags:
        - Identify
      summary: Identify an account
      description: >
        Resolve a bank or wallet identifier to the institution behind it, the
        rails that can reach it, and — on supported rails — the holder name.
        Charged on an `identified` outcome. Promo credits cover first calls;
        there is no complimentary test lane.
      operationId: identify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyRequest'
            examples:
              institution:
                summary: Institution lookup
                value:
                  rail: routing_number
                  code: '021000021'
              holder:
                summary: With holder resolution
                value:
                  rail: nuban
                  code: '058'
                  account_number: '0123456789'
      responses:
        '200':
          description: Identification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeIdentify'
              examples:
                institution:
                  summary: Institution lookup
                  value:
                    status: success
                    data:
                      result: identified
                      rail: routing_number
                      country: US
                      institution:
                        name: JPMorgan Chase Bank
                        type: bank
                        code: '021000021'
                        address:
                          city: Tampa
                          country: US
                      reachable_rails:
                        - ach
                        - wire
                        - rtp
                      identified_at: '2026-08-02T12:00:00Z'
                holder:
                  summary: With holder resolution
                  value:
                    status: success
                    data:
                      result: identified
                      rail: nuban
                      country: NG
                      institution:
                        name: Guaranty Trust Bank
                        type: bank
                        code: '058'
                        bic: GTBINGLA
                        address:
                          country: NG
                      reachable_rails:
                        - nip
                      account:
                        number: '0123456789'
                        name: ADA LOVELACE
                        name_resolution: resolved
                      identified_at: '2026-08-02T12:00:00Z'
        '400':
          description: Missing or unsupported rail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Workspace is out of credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    IdentifyRequest:
      type: object
      required:
        - rail
        - code
      properties:
        rail:
          type: string
          enum:
            - swift
            - iban
            - routing_number
            - sort_code
            - ifsc
            - nuban
            - momo
            - gh_bank
          description: Kind of identifier to resolve.
        code:
          type: string
          description: >-
            The identifier — ABA routing number, IBAN, sort code, SWIFT/BIC, and
            so on.
        account_number:
          type: string
          description: >
            Account or wallet number. On holder-enabled rails (`nuban`, `momo`,
            `gh_bank`) this also resolves the holder name.
        country:
          type: string
          description: ISO 3166-1 alpha-2 hint when the rail is ambiguous.
    EnvelopeIdentify:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: string
          const: success
        data:
          $ref: '#/components/schemas/IdentifyResult'
    Error:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          const: error
        error:
          type: object
          required:
            - message
            - code
          properties:
            message:
              type: string
              description: Human-readable explanation.
            code:
              type: string
              description: Stable machine-readable code.
            details:
              description: Optional extra context.
    IdentifyResult:
      type: object
      required:
        - result
        - rail
      properties:
        result:
          type: string
          enum:
            - identified
            - not_found
            - unsupported
          description: Outcome of the lookup.
        rail:
          type: string
          description: Rail that was resolved.
        country:
          type: string
          description: ISO country of the institution, when known.
        institution:
          $ref: '#/components/schemas/Institution'
        reachable_rails:
          type: array
          items:
            type: string
          description: Payment rails the institution can be reached on.
        account:
          $ref: '#/components/schemas/Account'
        identified_at:
          type: string
          format: date-time
          description: Present only when `result` is `identified`.
    Institution:
      type: object
      description: The identified financial institution.
      properties:
        name:
          type: string
        type:
          type: string
          description: Institution type, e.g. `bank`.
        code:
          type: string
          description: Institution code on this rail.
        bic:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    Account:
      type: object
      description: Present when an account number was supplied.
      properties:
        number:
          type: string
        name:
          type: string
          description: Resolved holder name, when available.
        name_resolution:
          type: string
          enum:
            - resolved
            - unavailable
            - not_supported
    Address:
      type: object
      properties:
        city:
          type: string
        country:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Identify accepts a workspace API key (`sk_…`). Loom accepts either a
        short-lived session token (direct) or a workspace API key (relay).

````