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

> Resolve a bank account or wallet to the institution, the rails that reach it, and — where we can — the holder.

Identify is the first workbench tool, and the only one live today. You send a `rail` and its `code`. Patchwork returns the institution, the payment rails it can be reached on, and — when you also pass an `account_number` on a supported rail — the resolved holder name.

It is a bare REST product. You can call it with an API key and no agent. When the `api_product` binding ships, the same product can be wired into an agent as a patch.

<Note>
  Charged on an `identified` outcome. Promo credits cover first calls. There is no complimentary test lane.
</Note>

## Quickstart

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.usepatchwork.co/v1/identify \
    -H "Authorization: Bearer $PATCHWORK_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"rail":"routing_number","code":"021000021"}'
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.usepatchwork.co/v1/identify", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PATCHWORK_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ rail: "routing_number", code: "021000021" }),
  });
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  r = requests.post(
      "https://api.usepatchwork.co/v1/identify",
      headers={"Authorization": f"Bearer {os.environ['PATCHWORK_API_KEY']}"},
      json={"rail": "routing_number", "code": "021000021"},
  )
  print(r.json()["data"])
  ```
</CodeGroup>

A successful institution lookup looks like this:

```json theme={null}
{
  "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"
  }
}
```

## Rails

| Rail          | `rail`           | `code`                 | Holder name           |
| ------------- | ---------------- | ---------------------- | --------------------- |
| SWIFT / BIC   | `swift`          | BIC                    | —                     |
| IBAN          | `iban`           | IBAN                   | —                     |
| ABA routing   | `routing_number` | 9-digit routing number | —                     |
| UK sort code  | `sort_code`      | Sort code              | —                     |
| India IFSC    | `ifsc`           | IFSC                   | —                     |
| Nigeria NUBAN | `nuban`          | Bank code              | With `account_number` |
| Mobile money  | `momo`           | Provider / MSISDN      | With `account_number` |
| Ghana bank    | `gh_bank`        | Bank code              | With `account_number` |

Holder resolution is available on `nuban`, `momo`, and `gh_bank`. Pass `account_number` (or the wallet number) on those rails.

```bash theme={null}
curl https://api.usepatchwork.co/v1/identify \
  -H "Authorization: Bearer $PATCHWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rail":"nuban","code":"058","account_number":"0123456789"}'
```

`country` is an optional ISO 3166-1 alpha-2 hint when the rail is ambiguous.

## Results

`data.result` is one of `identified`, `not_found`, or `unsupported`. Only `identified` is billed.

If a field is unknown we omit it — we do not send nulls. `identified_at` is present only on a match.

The result object: [The Identify Result object](/api-reference/identify). The request: [Identify an account](/api-reference/identify/identify-an-account).

## Errors

Missing `rail` or `code` is `MISSING_PARAMETER` (`400`). An unknown rail is `UNSUPPORTED_RAIL` (`400`). Out of credits is `402`. See [Errors](/api-reference/errors).