Beneficiaries

Beneficiaries are the businesses or individuals that clients send payments to. They are a combination of personal/company information and external banking details.

Overview

Depending on where in the world a beneficiary is located and the type of payment being sent to them, different banking details are required. For example, a beneficiary in the UK will require a sort code and account number, while a beneficiary in the EU will require an IBAN.

All beneficiaries can accept payments via SWIFT using a BIC/SWIFT code and an IBAN if they are provided.

When modifying a beneficiary, any payments not yet Sent will use the updated beneficiary information.

View a Beneficiary

GET/v1/beneficiaries/{id}

Retrieves a beneficiary.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the beneficiary.

Request

GET

/v1/beneficiaries/{id}

  curl -G https://api.flowbrite.io/v1/beneficiaries/{id} \
  -H "X-API-KEY: {api_key}"

Responses

200 - OK

400 - Bad Request

404 - Not Found

Response Body

Name
data
Type
object
Type
Description
Show data properties

Example Responses

{
  "data": {
    "id": "ben_D01JTK7HZWS9E5XR4J819XF4KS5",
    "client": {
      "id": "cli_D01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "Joanna Bloggs"
    },
    "beneficiaryType": "INDIVIDUAL",
    "displayName": "Chase Account",
    "email": null,
    "individual": {
      "firstName": "Joe",
      "lastName": "Bloggs",
      "dateOfBirth": null
    },
    "company": null,
    "address": {
      "lines": ["66, HATTON GARDENS"],
      "city": "LONDON",
      "state": null,
      "postalCode": null,
      "countryCode": "GB"
    },
    "identificationType": null,
    "identificationValue": null,
    "bankAccount": {
      "bankName": "J.P. MORGAN EUROPE LIMITED",
      "bankAddress": ["25, BANK STREET\nLONDON"],
      "bankCountryCode": "GB",
      "ccyCode": "GBP",
      "accountNumber": "12345678",
      "accountHolderName": "Joe Bloggs",
      "bicSwiftCode": "CHASGB22XXX",
      "iban": null,
      "routingCodeType1": "SORT_CODE",
      "routingCode1": "608407",
      "routingCodeType2": null,
      "routingCode2": null,
      "accountType": null,
      "supportedPaymentTypes": "REGULAR"
    },
    "isSnapshot": false,
    "status": "ACTIVE",
    "statusHistory": [],
    "auditHistory": null
  }
}

View a Beneficiary Snapshot

GET/v1/beneficiary-snapshots/{beneficiarySnapshotId}

Retrieves a beneficiary snapshot. Snapshots are point-in-time copies of a beneficiary's details taken at the time a payment was sent. They can be identified by the bss_ ID prefix and the isSnapshot: true property.

Path Parameters

Name
beneficiarySnapshotId
Type
string
Required
Type
Description
The unique ID of the beneficiary snapshot. Snapshot IDs begin with bss_.

Request

GET

/v1/beneficiary-snapshots/{beneficiarySnapshotId}

  curl -G https://api.flowbrite.io/v1/beneficiary-snapshots/{beneficiarySnapshotId} \
  -H "X-API-KEY: {api_key}"

Responses

200 - OK

400 - Bad Request

404 - Not Found

Response Body

Name
data
Type
object
Type
Description
Show data properties

Example Responses

{
  "data": {
    "id": "bss_D01JTK7HZWS9E5XR4J819XF4KS5",
    "client": {
      "id": "cli_D01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "Joanna Bloggs"
    },
    "beneficiaryType": "INDIVIDUAL",
    "displayName": "Chase Account",
    "email": null,
    "individual": {
      "firstName": "Joe",
      "lastName": "Bloggs",
      "dateOfBirth": null
    },
    "company": null,
    "address": {
      "lines": ["66, HATTON GARDENS"],
      "city": "LONDON",
      "state": null,
      "postalCode": null,
      "countryCode": "GB"
    },
    "identificationType": null,
    "identificationValue": null,
    "bankAccount": {
      "bankName": "J.P. MORGAN EUROPE LIMITED",
      "bankAddress": ["25, BANK STREET\nLONDON"],
      "bankCountryCode": "GB",
      "ccyCode": "GBP",
      "accountNumber": "12345678",
      "accountHolderName": "Joe Bloggs",
      "bicSwiftCode": "CHASGB22XXX",
      "iban": null,
      "routingCodeType1": "SORT_CODE",
      "routingCode1": "608407",
      "routingCodeType2": null,
      "routingCode2": null,
      "accountType": null,
      "supportedPaymentTypes": "REGULAR"
    },
    "isSnapshot": true,
    "status": "ACTIVE",
    "statusHistory": [],
    "auditHistory": null
  }
}

Search Beneficiaries

GET/v1/beneficiaries

Search for beneficiaries.

Please refer to the Search Guide for information on how to construct queries.

Search Parameters

It is possible to search for beneficiaries by the following fields. Please refer to the data object definition in the Response Body below for details on each field.

Show search fields

Request

GET

/v1/beneficiaries

  curl -G https://api.flowbrite.io/v1/beneficiaries \
  -H "X-API-KEY: {api_key}" \
  -d 'q=displayName!~"Ski"' \
  -d "sortBy=displayName:DESC" \
  -d "offset=0" \
  -d "limit=10"

Responses

200 - OK

400 - Bad Request

Response Body

Name
data
Type
object[]
This is an array
Type
Description
Show data properties
Name
meta
Type
object
Type
Description
Metadata about the beneficiary search results.
Show meta properties

Example Responses

{
  "data": [
    {
      "id": "ben_D01JTK7JT75ZSAEQ726SB7ZRZP2",
      "client": {
        "id": "cli_D01JTK7H381MG2MYZ6Z9TAFJSBQ",
        "name": "ABC Tours"
      },
      "beneficiaryType": "COMPANY",
      "displayName": "New Safaris (Pty) Ltd",
      "email": null,
      "individual": null,
      "company": {
        "name": "New Safaris (Pty) Ltd",
        "website": null,
        "natureOfBusiness": null,
        "dateOfIncorporation": null
      },
      "address": {
        "lines": ["4, Cape Drive"],
        "city": "Johannesburg",
        "state": null,
        "postalCode": null,
        "countryCode": "ZA"
      },
      "identificationType": null,
      "identificationValue": null,
      "bankAccount": {
        "bankName": "FIRSTRAND BANK LIMITED",
        "bankAddress": ["4, CORNER FREDMAN DRIVE AND RIVONIA R"],
        "bankCountryCode": "ZA",
        "ccyCode": "ZAR",
        "accountNumber": "12345678901",
        "accountHolderName": "New Safaris (Pty) Ltd",
        "bicSwiftCode": "FIRNZAJJ",
        "iban": null,
        "routingCodeType1": null,
        "routingCode1": null,
        "routingCodeType2": null,
        "routingCode2": null,
        "accountType": null,
        "supportedPaymentTypes": "PRIORITY"
      },
      "isSnapshot": false,
      "status": "ACTIVE",
      "statusHistory": [],
      "auditHistory": null
    }
  ],
  "meta": {
    "query": "AND(displayName^=\"New\",ccyCode==\"GBP\")",
    "sortBy": ["displayName:ASC"],
    "offset": 0,
    "limit": 1,
    "count": 1,
    "totalCount": 2,
    "timestamp": "2025-06-06T16:14:39.7943701Z"
  }
}