tenants

Operators, customers, people (memberships), invitations, teams and customer settings (currencies, addresses, alerts, approved domains, approval policies, primary owner, closure).

Markdown version: tenants.md

List customers (operator)

GET /v1/customers

listCustomers
API key scope customers:read
Tenant operator

API key scope: customers:read (operator-level keys only, X-Tenant-Id = the operator id).

Metadata filter: filter[metadata.<key>]=<value> (exact match; at most 5; AND).

Batch look-up (P12-T07): filter[id]=<id>,<id>,… (at most 100) returns those rows only, e.g. to resolve names shown next to ids; combine with limit ≥ the number of ids.

Parameters

Name	In	Type	Description
`X-Tenant-Id`required	header	Uuid	Tenant context: the operator tenant id (staff operations) or customer tenant id (customer operations). Validated against the caller's memberships; mismatch → `403`. For API keys it must equal the key's customer id (customer-level keys are bound to one customer) or, for operator-level keys (P9-T08b), the operator id.
`X-Request-Id`	header	string	Client-supplied correlation id. Generated by the server when absent; always echoed in the response and in problem details.
`cursor`	query	string	Opaque cursor from `page.nextCursor` or `page.prevCursor`. Must be used with the same `sort` and `filter` as the request that produced it (`400 invalid-cursor` otherwise).
`limit`	query	integer	Page size (max 100).
`sort`	query	string	Sort order; prefix `-` for descending. Cursor stability is guaranteed only for the default sort.
`filter`	query	object	Filters as `filter[field]=value`. Multiple values for one field are comma-separated (OR); different fields combine with AND. Date ranges use `filter[createdFrom]`/`filter[createdTo]` (inclusive, RFC 3339 or date). P10-T03: `filter[metadata.<key>]=<value>` matches a metadata attribute exactly (key `[A-Za-z0-9_-]{1,40}`; at most 5 per request, AND-combined, one value each).
`q`	query	string	Free-text search (trigram; min 2 characters).
`withTotal`	query	boolean	Include `page.total` (may be slower). Computed on the first page only (a request without `cursor`); later pages omit `page.total` (scalability audit X-32).

Responses

200 OK application/json
Schema CustomerPage
Cursor-paginated list of Customer.
- data array of Customerrequired
- 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/customers" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/customers", {
  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/customers",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Create a customer (operator-initiated)

POST /v1/customers

createCustomer
API key scope customers:write
Tenant operator

Creates a draft customer. With primaryOwner a primary-owner invitation is emailed; without it (console sessions only) no invitation is sent. Creates a draft customer and invites the primary owner. Self-registration uses /auth/register.

API key scope: customers:write (operator-level keys only, X-Tenant-Id = the operator id).

API keys (review W3-02): an operator key needs customers:write, the owner address must be on the operator settings' apiKeyInvitationDomains (422 invitation_domains_required / domain_not_approved before anything is written) and each key may create 10 customers a minute (429).

Parameters

Name	In	Type	Description
`X-Tenant-Id`required	header	Uuid	Tenant context: the operator tenant id (staff operations) or customer tenant id (customer operations). Validated against the caller's memberships; mismatch → `403`. For API keys it must equal the key's customer id (customer-level keys are bound to one customer) or, for operator-level keys (P9-T08b), the operator id.
`X-Request-Id`	header	string	Client-supplied correlation id. Generated by the server when absent; always echoed in the response and in problem details.
`Idempotency-Key`	header	string	Optional idempotency key; same semantics as on money operations.

Request body

Required. application/json

Schema CustomerCreate

Send customerType (P10-T03); identityType is derived (corporate for businesses, individual otherwise) and may be omitted; when both are sent they must agree (422). For sole traders and individuals legalName is the person's full name and incorporationCountry the country of residence; an individual has no registration number. primaryOwner is optional for console sessions: the customer is then created as a draft without an invitation, and staff invite the owner later (POST /ops/customers/{customerId}/owner-invitation). API keys must still send it (422 with field /primaryOwner).

legalName stringrequired
max length 200
tradingName string | null
max length 200
identityType IdentityType
registrationNumber string | null
max length 50
incorporationCountry CountryCoderequired
primaryOwner object
Fields of primaryOwner
- email Emailrequired
- firstName stringrequired
- lastName stringrequired
pricingTemplateId Uuid | null
customerType CustomerType
metadata Metadata

Responses

201 Created application/json
Schema Customer
- id Uuidrequiredread-only
  Fields of id
  Uuid
- operatorId Uuidrequiredread-only
  Fields of operatorId
  Uuid
- number stringrequiredread-only
  8-digit display id, unique per operator.
  pattern ^[0-9]{8}$
- legalName stringrequired
  max length 200
- tradingName string | null
  max length 200
- identityType IdentityTyperequired
- registrationNumber string | null
  max length 50
- incorporationCountry CountryCoderequired
- incorporationDate Date | null
- status CustomerStatusrequiredread-only
  Fields of status
  CustomerStatus
- risk RiskRating | null
- approvedAt Timestamp | null
- closedAt Timestamp | null
- createdAt Timestamprequiredread-only
  Fields of createdAt
  Timestamp
- updatedAt Timestampread-only
  Fields of updatedAt
  Timestamp
- customerType CustomerType
- metadata Metadata
- accessStatus AccessStatusread-only
  Fields of accessStatus
  AccessStatus
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/customers" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Content-Type: application/json" \
  --data '{
  "legalName": "string",
  "incorporationCountry": "GB"
}'

const response = await fetch("https://bank.wirebloom.com/v1/customers", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "legalName": "string",
    "incorporationCountry": "GB"
  }),
});
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/customers",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Content-Type": "application/json",
    },
    json={
      "legalName": "string",
      "incorporationCountry": "GB"
    },
    timeout=30,
)
response.raise_for_status()

Get customer

GET /v1/customers/{customerId}

getCustomer
API key scope customers:read
Tenant any

X-Tenant-Id is the customer itself or its operator. customer.view is held by operator staff roles and by every customer role (own customer only).

API key scope: customers:read (operator-level keys only, X-Tenant-Id = the operator id).

Parameters

Name	In	Type	Description
`customerId`required	path	Uuid	Identifier (customerId).
`X-Tenant-Id`required	header	Uuid	Tenant context: the operator tenant id (staff operations) or customer tenant id (customer operations). Validated against the caller's memberships; mismatch → `403`. For API keys it must equal the key's customer id (customer-level keys are bound to one customer) or, for operator-level keys (P9-T08b), the operator id.
`X-Request-Id`	header	string	Client-supplied correlation id. Generated by the server when absent; always echoed in the response and in problem details.
`If-None-Match`	header	string	Conditional GET; `304` when unchanged.

Responses

200 OK application/json
Schema Customer
- id Uuidrequiredread-only
  Fields of id
  Uuid
- operatorId Uuidrequiredread-only
  Fields of operatorId
  Uuid
- number stringrequiredread-only
  8-digit display id, unique per operator.
  pattern ^[0-9]{8}$
- legalName stringrequired
  max length 200
- tradingName string | null
  max length 200
- identityType IdentityTyperequired
- registrationNumber string | null
  max length 50
- incorporationCountry CountryCoderequired
- incorporationDate Date | null
- status CustomerStatusrequiredread-only
  Fields of status
  CustomerStatus
- risk RiskRating | null
- approvedAt Timestamp | null
- closedAt Timestamp | null
- createdAt Timestamprequiredread-only
  Fields of createdAt
  Timestamp
- updatedAt Timestampread-only
  Fields of updatedAt
  Timestamp
- customerType CustomerType
- metadata Metadata
- accessStatus AccessStatusread-only
  Fields of accessStatus
  AccessStatus
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/customers/{customerId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/customers/{customerId}", {
  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/customers/{customerId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Account currencies (offered and enabled)

GET /v1/customers/{customerId}/settings/currencies

listCustomerCurrencies
API key scope balances:read
Tenant any

API key scope: balances:read.

Parameters

Name	In	Type	Description
`customerId`required	path	Uuid	Identifier (customerId).
`X-Tenant-Id`required	header	Uuid	Tenant context: the operator tenant id (staff operations) or customer tenant id (customer operations). Validated against the caller's memberships; mismatch → `403`. For API keys it must equal the key's customer id (customer-level keys are bound to one customer) or, for operator-level keys (P9-T08b), the operator id.
`X-Request-Id`	header	string	Client-supplied correlation id. Generated by the server when absent; always echoed in the response and in problem details.
`If-None-Match`	header	string	Conditional GET; `304` when unchanged.

Responses

200 OK application/json
Array of CurrencySetting
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/customers/{customerId}/settings/currencies" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/customers/{customerId}/settings/currencies", {
  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/customers/{customerId}/settings/currencies",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()