API reference Beneficiaries

Beneficiaries

On this page:

GET[base]/accounts/{accountId}/beneficiaries

Use this method to obtain information about the beneficiaries of a specified account that the PSU has authorized to access.

Request

Header parameters:

Authorization: The authorization token as per https://tools.ietf.org/html/rfc6750.
x-fapi-financial-id required: The unique identifier of the ASPSP issued by the Open Banking system.
x-fapi-customer-last-logged-time: The date and time when the PSU has last logged in system using a TPP application.
x-fapi-customer-ip-address: The IP address of the PSU who has logged in system using the TPP application.
x-fapi-interaction-id: The unique identifier of the initiating party (as per RFC4122 UID) used as a correlation identifier.
x-customer-user-agent: The user-agent used by the PSU.

Path parameters:

AccountId required: The account identifier.

GET[base]/accounts/{accountId}/beneficiaries

GET /accounts/account-Id-example/beneficiaryId HTTP/1.1
Authorization: Bearer <token>
x-fapi-financial-id: b621cec4-e775-49ab-980a-1900c6a09620
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Response

Body:

Beneficiary object

This object provides the following data:

Expand fields

AccountId string

The account identifier.

BeneficiaryId string

The beneficiary identifier.

Reference string

The unique reference to the payment transaction assigned by the creditor.

If available, the initiating party should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money.

CreditorAgent object

This object provides the following data:

Expand fields

SchemeName string

The name of a scheme.

Identification string

The identifier of a financial institution of an agent.

Name string

The name of an agent.

PostalAddress object

This object provides the following data:

Expand fields

AddressType string

The address type of an agent. Possible values:

Business
Correspondence
DeliveryTo
MailTo
POBox
Postal
Residential
Statement

Department string

The department of the building of an agent.

SubDepartment string

The subdepartment of the building of an agent.

StreetName string

The name of the street of an agent.

BuildingNumber string

The number of the building of an agent.

PostCode string

The postal code of an agent.

TownName string

The name the town of an agent.

CountrySubDivision string

The subdivision of the country of an agent.

Country string

The country of an agent.

AddressLine array

The address line of an agent.

CreditorAccount object

This object provides the following data:

Expand fields

SchemeName string

The name of a scheme.

Example:

"UK.OBIE.BBAN"
"UK.OBIE.IBAN"
"UK.OBIE.PAN"
"UK.OBIE.Paym"
"UK.OBIE.SortCodeAccountNumber"

Identification string

The identifier of the financial institution of a creditor account.

Name string

The name of an account.

SecondaryIdentification string

The secondary identification of an account assigned by the account servicing institution.

HTTP status codes:

The eqwire API uses standard HTTP response codes to indicate the success or failure of a request.

To view a full list of valid response codes, refer to HTTP response codes.

    RESPONSE EXAMPLE
  
{
    "Data": {
      "Beneficiary": [
        {
          "AccountId": "22289",
          "BeneficiaryId": "Ben1",
          "Reference": "Towbar Club",
          "CreditorAgent": {
            "SchemeName": [
              "UK.OBIE.BICFI"
            ],
            "Identification": "87562298675421",
            "Name": "Mrs Juniper",
            "PostalAddress": {
              "AddressType": "Business",
              "Department": "Wessex",
              "SubDepartment": "Wessex",
              "StreetName": "Acacia Lodge",
              "BuildingNumber": "235",
              "PostCode": "GU31 2ZZ",
              "TownName": "Sparsholt",
              "CountrySubDivision": "Wessex",
              "Country": "UK",
              "AddressLine": [
                "Flat 7",
                "Acacia Lodge"
              ]
            }
          },
          "CreditorAccount": {
            "SchemeName": [
              "UK.OBIE.BBAN",
              "UK.OBIE.IBAN",
              "UK.OBIE.PAN",
              "UK.OBIE.Paym",
              "UK.OBIE.SortCodeAccountNumber"
            ],
            "Identification": "80200112345675",
            "Name": "Mrs Juniper",
            "SecondaryIdentification": "00021"
          }
        }
      ]
    },
    "Links": {
      "Self": "https://example.com",
      "First": "https://example.com",
      "Prev": "https://example.com",
      "Next": "https://example.com",
      "Last": "https://example.com"
    },
    "Meta": {
      "TotalPages": 5,
      "FirstAvailableDateTime": "2023-01-23T05:52:49.418Z",
      "LastAvailableDateTime": "2023-01-23T05:52:49.418Z"
    }
  }

Beneficiaries

Get a list of beneficiaries