get-recipients
Get saved payment recipients filtered by name. Returns matching recipients with their account details.
Input
| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✓ | Free-text search; matches partial names of saved recipients. |
Raw JSON Schema
{
"additionalProperties": false,
"properties": {
"name": {
"description": "Free-text search; matches partial names of saved recipients.",
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
Output
| Field | Type | Required | Description |
|---|---|---|---|
items | array<Recipient> | ✓ | Recipients matching the request. |
items[] — Recipient
Saved payment recipient. Profile of: ISO 20022 Creditor and CreditorAccount (subset). Account routing goes through the typed accountIdentifier discriminated union (IBAN, BBAN, country-specific account number, or alias); national identification is opaque to bank2ai and lives in the typed nationalId sub-object.
| Field | Type | Required | Description |
|---|---|---|---|
accountIdentifier | IbanIdentifier | BbanIdentifier | AccountNumberIdentifier | AliasIdentifier | ✓ | Typed account identifier for routing the transfer. |
bic | string | null | BIC / SWIFT code of the recipient's bank, ISO 9362. Default: null. Examples: "NWBKGB2L". | |
defaultDescription | string | null | Pre-filled free-text shown on the recipient's statement for transfers prepared against this recipient. Clients MAY use this as the default description when preparing a transfer; users can override per transfer. Default: null. | |
id | string | ✓ | Unique recipient identifier (server-scoped). |
isFavorite | boolean | Whether this recipient is marked as favorite. Default: false. | |
lastUsedAt | string | null | ISO 8601 timestamp of the most recent transfer to this recipient. Default: null. | |
name | string | ✓ | Recipient's full name or business name. Examples: "Jane Doe", "Acme Corp". |
nationalId | NationalId | null | Recipient's national identifier when known. Default: null. | |
nickname | string | null | Optional user-friendly handle for the recipient. Default: null. Examples: "Mom", "Landlord". |
accountIdentifier — type: "iban"
IBAN-routed account, ISO 13616.
| Field | Type | Required | Description |
|---|---|---|---|
iban | string | ✓ | IBAN, ISO 13616. Examples: "GB29NWBK60161331926819", "DE89370400440532013000". Pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$. |
type | string | Discriminator: iban. Default: "iban". |
accountIdentifier — type: "bban"
Domestic Basic Bank Account Number, used in markets without an IBAN.
| Field | Type | Required | Description |
|---|---|---|---|
bban | string | ✓ | Domestic account identifier in the country's native format. Examples: "0133-26-007890". |
country | string | ✓ | ISO 3166-1 alpha-2 country code. Examples: "IS", "GB". Pattern: ^[A-Z]{2}$. |
type | string | Discriminator: bban. Default: "bban". |
accountIdentifier — type: "accountNumber"
Country-specific composite for non-IBAN markets (US, UK pre-IBAN, etc.).
| Field | Type | Required | Description |
|---|---|---|---|
accountNumber | string | ✓ | Account number in the country's native format. |
country | string | ✓ | ISO 3166-1 alpha-2 country code. Examples: "US", "GB". Pattern: ^[A-Z]{2}$. |
routing | string | null | US ABA routing number, when applicable. Default: null. | |
sortCode | string | null | UK sort code, when applicable. Default: null. | |
type | string | Discriminator: accountNumber. Default: "accountNumber". |
accountIdentifier — type: "alias"
Alias-based identifier (UPI VPA, Pix key, email-routed payments, etc.).
| Field | Type | Required | Description |
|---|---|---|---|
alias | string | ✓ | The alias value as the user knows it. Examples: "alex@upi", "+44-7700-900000". |
aliasType | "email" | "phone" | "vpa" | "pix" | "other" | ✓ | Kind of alias. |
type | string | Discriminator: alias. Default: "alias". |
nationalId — NationalId
Person or business national identifier.
| Field | Type | Required | Description |
|---|---|---|---|
country | string | ✓ | ISO 3166-1 alpha-2 country code. Examples: "IS", "US". Pattern: ^[A-Z]{2}$. |
type | "ssn" | "kennitala" | "cpr" | "personnummer" | "cpf" | "other" | null | Hint for the kind of identifier. bank2ai does not validate the value. Default: null. | |
value | string | ✓ | National identifier value, in the country's native format. Examples: "010190-1234", "123-45-6789". |
Raw JSON Schema
{
"description": "Envelope for a list of recipients",
"properties": {
"items": {
"description": "Recipients matching the request.",
"items": {
"description": "Saved payment recipient.\n\nProfile of: ISO 20022 `Creditor` and `CreditorAccount` (subset).\nAccount routing goes through the typed `accountIdentifier`\ndiscriminated union (IBAN, BBAN, country-specific account number,\nor alias); national identification is opaque to bank2ai and lives\nin the typed `nationalId` sub-object.",
"properties": {
"accountIdentifier": {
"description": "Typed account identifier for routing the transfer.",
"oneOf": [
{
"description": "IBAN-routed account, ISO 13616.",
"properties": {
"iban": {
"description": "IBAN, ISO 13616.",
"examples": [
"GB29NWBK60161331926819",
"DE89370400440532013000"
],
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"type": "string"
},
"type": {
"const": "iban",
"default": "iban",
"description": "Discriminator: `iban`.",
"type": "string"
}
},
"required": [
"iban"
],
"type": "object"
},
{
"description": "Domestic Basic Bank Account Number, used in markets without an IBAN.",
"properties": {
"bban": {
"description": "Domestic account identifier in the country's native format.",
"examples": [
"0133-26-007890"
],
"type": "string"
},
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"IS",
"GB"
],
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"type": {
"const": "bban",
"default": "bban",
"description": "Discriminator: `bban`.",
"type": "string"
}
},
"required": [
"bban",
"country"
],
"type": "object"
},
{
"description": "Country-specific composite for non-IBAN markets (US, UK pre-IBAN, etc.).",
"properties": {
"accountNumber": {
"description": "Account number in the country's native format.",
"type": "string"
},
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"US",
"GB"
],
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"routing": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "US ABA routing number, when applicable."
},
"sortCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "UK sort code, when applicable."
},
"type": {
"const": "accountNumber",
"default": "accountNumber",
"description": "Discriminator: `accountNumber`.",
"type": "string"
}
},
"required": [
"accountNumber",
"country"
],
"type": "object"
},
{
"description": "Alias-based identifier (UPI VPA, Pix key, email-routed payments, etc.).",
"properties": {
"alias": {
"description": "The alias value as the user knows it.",
"examples": [
"alex@upi",
"+44-7700-900000"
],
"type": "string"
},
"aliasType": {
"description": "Kind of alias.",
"enum": [
"email",
"phone",
"vpa",
"pix",
"other"
],
"type": "string"
},
"type": {
"const": "alias",
"default": "alias",
"description": "Discriminator: `alias`.",
"type": "string"
}
},
"required": [
"alias",
"aliasType"
],
"type": "object"
}
]
},
"bic": {
"anyOf": [
{
"pattern": "^[A-Z]{6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3})?$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "BIC / SWIFT code of the recipient's bank, ISO 9362.",
"examples": [
"NWBKGB2L"
]
},
"defaultDescription": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pre-filled free-text shown on the recipient's statement for transfers prepared against this recipient. Clients MAY use this as the default `description` when preparing a transfer; users can override per transfer."
},
"id": {
"description": "Unique recipient identifier (server-scoped).",
"type": "string"
},
"isFavorite": {
"default": false,
"description": "Whether this recipient is marked as favorite.",
"type": "boolean"
},
"lastUsedAt": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp of the most recent transfer to this recipient."
},
"name": {
"description": "Recipient's full name or business name.",
"examples": [
"Jane Doe",
"Acme Corp"
],
"type": "string"
},
"nationalId": {
"anyOf": [
{
"description": "Person or business national identifier.",
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"IS",
"US"
],
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"type": {
"anyOf": [
{
"description": "Opaque label for the kind of national identifier carried in `NationalId.value`.\n\nbank2ai does not validate national-ID formats; this is a hint so\nclients can render or route appropriately. Servers SHOULD set the\nclosest-matching value or use `other`.",
"enum": [
"ssn",
"kennitala",
"cpr",
"personnummer",
"cpf",
"other"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Hint for the kind of identifier. bank2ai does not validate the value."
},
"value": {
"description": "National identifier value, in the country's native format.",
"examples": [
"010190-1234",
"123-45-6789"
],
"type": "string"
}
},
"required": [
"value",
"country"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Recipient's national identifier when known."
},
"nickname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional user-friendly handle for the recipient.",
"examples": [
"Mom",
"Landlord"
]
}
},
"required": [
"id",
"name",
"accountIdentifier"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
}