recipients

List recipients

GET /v1/recipients

• listRecipients
• API key scope recipients:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema RecipientPage

  Cursor-paginated list of Recipient.

  • data array of Recipientrequired

  • page PageInforequired

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/recipients" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/recipients", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/recipients",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Add recipient

POST /v1/recipients

• createRecipient
• API key scope recipients:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 201 Created application/json

  Schema Recipient

  Recipient. approval is the recipient's review as the caller sees it (null when it was never reviewed). Full bank identifiers are returned only on GET /recipients/{id} (and on create/update); list responses carry bank.iban and bank.accountNumber as null and show maskedIdentifier instead.

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • type RecipientTyperequired

  • name stringrequired

    max length 140

  • nickname string | null

    max length 50

  • email Email | null

  • address Address | null

  • currency CurrencyCoderequired

  • bank RecipientBankrequired

  • maskedIdentifier stringrequiredread-only

    Masked IBAN/account number for lists.

  • defaultReference string | null

    max length 35

  • purpose string | null

    max length 140

  • status RecipientStatusrequiredread-only

    Fields of status

    RecipientStatus

  • verification RecipientVerification | null

  • lastPaidAt Timestamp | null

  • createdBy Uuidread-only

    Fields of createdBy

    Uuid

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • updatedAt Timestampread-only

    Fields of updatedAt

    Timestamp

  • approval RecipientApproval | nullrequired

  • metadata Metadata

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/recipients" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "type": "company",
  "name": "Acme GmbH",
  "currency": "EUR",
  "bank": {
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "bankCountry": "DE"
  },
  "defaultReference": "INV-2026"
}'

const response = await fetch("https://bank.wirebloom.com/v1/recipients", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "company",
    "name": "Acme GmbH",
    "currency": "EUR",
    "bank": {
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "bankCountry": "DE"
    },
    "defaultReference": "INV-2026"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/recipients",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
      "type": "company",
      "name": "Acme GmbH",
      "currency": "EUR",
      "bank": {
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "bankCountry": "DE"
      },
      "defaultReference": "INV-2026"
    },
    timeout=30,
)
response.raise_for_status()

Get recipient (full details)

GET /v1/recipients/{recipientId}

• getRecipient
• API key scope recipients:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema Recipient

  Recipient. approval is the recipient's review as the caller sees it (null when it was never reviewed). Full bank identifiers are returned only on GET /recipients/{id} (and on create/update); list responses carry bank.iban and bank.accountNumber as null and show maskedIdentifier instead.

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • type RecipientTyperequired

  • name stringrequired

    max length 140

  • nickname string | null

    max length 50

  • email Email | null

  • address Address | null

  • currency CurrencyCoderequired

  • bank RecipientBankrequired

  • maskedIdentifier stringrequiredread-only

    Masked IBAN/account number for lists.

  • defaultReference string | null

    max length 35

  • purpose string | null

    max length 140

  • status RecipientStatusrequiredread-only

    Fields of status

    RecipientStatus

  • verification RecipientVerification | null

  • lastPaidAt Timestamp | null

  • createdBy Uuidread-only

    Fields of createdBy

    Uuid

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • updatedAt Timestampread-only

    Fields of updatedAt

    Timestamp

  • approval RecipientApproval | nullrequired

  • metadata Metadata

• 304 Not modified (`If-None-Match` matched).
• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/recipients/{recipientId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/recipients/{recipientId}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/recipients/{recipientId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Edit recipient

PATCH /v1/recipients/{recipientId}

• updateRecipient
• API key scope recipients:write
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 200 OK application/json

  Schema Recipient

  Recipient. approval is the recipient's review as the caller sees it (null when it was never reviewed). Full bank identifiers are returned only on GET /recipients/{id} (and on create/update); list responses carry bank.iban and bank.accountNumber as null and show maskedIdentifier instead.

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • type RecipientTyperequired

  • name stringrequired

    max length 140

  • nickname string | null

    max length 50

  • email Email | null

  • address Address | null

  • currency CurrencyCoderequired

  • bank RecipientBankrequired

  • maskedIdentifier stringrequiredread-only

    Masked IBAN/account number for lists.

  • defaultReference string | null

    max length 35

  • purpose string | null

    max length 140

  • status RecipientStatusrequiredread-only

    Fields of status

    RecipientStatus

  • verification RecipientVerification | null

  • lastPaidAt Timestamp | null

  • createdBy Uuidread-only

    Fields of createdBy

    Uuid

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • updatedAt Timestampread-only

    Fields of updatedAt

    Timestamp

  • approval RecipientApproval | nullrequired

  • metadata Metadata

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 412 `If-Match` does not match the current ETag (resource changed). application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 428 `If-Match` header is required for this operation. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X PATCH "https://bank.wirebloom.com/v1/recipients/{recipientId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "If-Match: \"<etag>\"" \
  -H "Content-Type: application/json" \
  --data '{}'

const response = await fetch("https://bank.wirebloom.com/v1/recipients/{recipientId}", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "If-Match": "\"<etag>\"",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "PATCH",
    "https://bank.wirebloom.com/v1/recipients/{recipientId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "If-Match": "\"<etag>\"",
        "Content-Type": "application/json",
    },
    json={},
    timeout=30,
)
response.raise_for_status()

Delete recipient (soft)

DELETE /v1/recipients/{recipientId}

• deleteRecipient
• API key scope recipients:write
• Tenant customer

Parameters

Responses

• 204 No Content
• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 412 `If-Match` does not match the current ETag (resource changed). application/problem+json

  Body Problem; see the error catalogue.

• 428 `If-Match` header is required for this operation. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X DELETE "https://bank.wirebloom.com/v1/recipients/{recipientId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "If-Match: \"<etag>\""

const response = await fetch("https://bank.wirebloom.com/v1/recipients/{recipientId}", {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "If-Match": "\"<etag>\"",
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);

import os

import requests

response = requests.request(
    "DELETE",
    "https://bank.wirebloom.com/v1/recipients/{recipientId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "If-Match": "\"<etag>\"",
    },
    timeout=30,
)
response.raise_for_status()

Run Confirmation / Verification of Payee

POST /v1/recipients/{recipientId}/verify

• verifyRecipient
• API key scope recipients:write
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema RecipientVerification

  • scheme stringrequired

    One of: "cop", "vop"

  • outcome VerificationOutcomerequired

  • matchedName string | null

  • reasonCode string | null

  • provider ProviderIdrequired

  • verifiedAt Timestamprequired

  • overriddenBy Uuid | null

  • overrideReason string | null

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/recipients/{recipientId}/verify" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/recipients/{recipientId}/verify", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/recipients/{recipientId}/verify",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Field requirements per currency and country

GET /v1/recipients/requirements

• getRecipientRequirements
• API key scope recipients:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema RecipientRequirements

  Dynamic form definition for the Add-recipient wizard, derived from routing and the routed provider (FR-REC-01).

  • currency CurrencyCoderequired

  • bankCountry CountryCoderequired

  • recipientType RecipientTyperequired

  • rails array of Railrequired

  • fields array of RecipientRequirementFieldrequired

  • verificationAvailable string | null

    One of: "cop", "vop"

  • alternatives array of array of string

    Alternative sets of required field paths: the recipient is complete when every path of at least one set is present (e.g. [["bank.iban"], ["bank.accountNumber", "bank.routingCodes.sortCode"]]).

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/recipients/requirements?currency=GBP&country=GB" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/recipients/requirements?currency=GBP&country=GB", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/recipients/requirements?currency=GBP&country=GB",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()