Please note that we are no longer onboarding new customers to this version of our API. Please visit our new documentation site https://docs.acquired.com
Get a test account Login

Beneficiaries

Create a beneficiary

Record a recipient’s details in the system in order to send them funds.

POST /accounts/customer/create_beneficiary
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Parameters

Parameter Format Length Description
ledger_id
Required		 string 36 The unique customer profile reference returned to you as part of the create.
Acceptable Characters: a-z A-Z , . – _
first_name
Required		 string 0-50 Beneficiaries first name.
Acceptable Characters: a-z A-Z , . – _ ’
middle_name string 0-50 Beneficiaries middle name.
Acceptable Characters: a-z A-Z , . – _ ’
last_name
Required		 string 0-50 Beneficiaries last name.
Acceptable Characters: a-z A-Z , . – _ ’
email
Recommended		 string 0-50 Beneficiaries email address.
Acceptable Characters: 0-9 a-z A-z _ – . @
phone_number
Recommended		 string 0-50 Beneficiaries phone number.
Acceptable Characters: 0-9 ( ) + –
address
Required		 object
number
Recommended		 string 1-11 Beneficiaries street number.
Acceptable Characters: a-z A-Z 0-9
refinement string 1-100 The address refinement, may include flat number, house name etc e.g. Suite 2, 4th Floor.
Acceptable Characters: a-z A-Z 0-9 . - _
street
Recommended		 string 1-100 Beneficiaries street address.
Acceptable Characters: a-z A-Z 0-9 , . - _
region string 1-100 The state, province, prefecture, or region.
Acceptable Characters: a-z A-Z 0-9 , . - _
city
Recommended		 string 1-100 Beneficiaries city.
Acceptable Characters: a-z A-Z 0-9 , . - _
postal_code
Recommended		 string 1-100 Beneficiaries ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
iso_country
Required		 string 2 Beneficiaries country, an ISO 3166 2-character code.
Acceptable Characters: a-z A-Z
account
Required		 object
account_number
Required		 int 0-9 Beneficiaries bank account number.
Acceptable Characters: 0-9
sort_code
Required		 string 0-9 Beneficiaries bank sort code.
Acceptable Characters: 0-9 -		 
{
    "customer_id": "22938286-283a-4594-b21c-afb1bd52d22c",
    "first_name": "Steve",
    "middle_name": "Anthony",
    "last_name": "Jobs",
    "email": "example@acquired.com",
    "phone": "0876543456",
    "address": {
        "number": "44",
        "refinement": "Suite 2, 4th Floor",
        "street": "Baker Street",
        "city": "London",
        "postal_code": "W1U7AL",
        "iso_country": "GB"
    },
    "account": {
        "account_number": "12345678",
        "sort_code": "123456"
    }
}

Response

Parameter Format Length Description
status int 1-2 The outcome of the request.
message string 0-100 Handy text describing the response_code or error for debugging.
beneficiary_id string 36 The unique customer profile reference returned to you as part of the create beneficiary procress. 
{
    "status": 1,
    "message": "Success",
    "beneficiary_id": "859f4eef-6a53-4110-8757-371844df8e8c"
}

Query a specific beneficiary

Use this to retrieve details for a specific beneficiary

GET /accounts/beneficiary/{beneficiary_id}
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Response

Parameter Format Length Description
status int 1-2 The outcome of the request.
message string 0-100 Handy text describing the response_code or error for debugging.
data object
customer_id string 36 The unique customer profile reference returned to you as part of the create.
first_name string 0-50 Beneficiaries first name.
middle_name string 0-50 Beneficiaries middle name.
last_name string 0-50 Beneficiaries last name.
email string 0-50 Beneficiaries email address.
phone_number string 0-50 Beneficiaries phone number.
address object
number string 1-11 Beneficiaries street number.
refinement string 1-100 The address refinement, may include flat number, house name etc e.g. Suite 2, 4th Floor.
street
string 1-100 Beneficiaries street address.
city string 1-100 Beneficiaries city.
postal_code string 1-100 Beneficiaries ZIP or postal code.
iso_country string 3 Beneficiaries country, an ISO 3166 2-character code.
account object
account_number int 0-9 Beneficiaries bank account number.
sort_code string 0-9 Beneficiaries bank sort code. 
{
    "status": 1,
    "message": "Success",
    "data": {
        "customer_id": "5e865d53-669c-4bbe-be49-09494cffc19d",
        "first_name": "Test",
        "middle_name": "",
        "last_name": "kk",
        "email": "peter@acquired.com",
        "phone": "07928267777",
        "address": {
            "number": "44",
            "refinement": "Suite 44, Flat 2",
            "street": "Baker Street",
            "city": "London",
            "postal_code": "SW4 2DJ",
            "iso_country": "FR"
        },
        "account": {
            "account_number": "12345678",
            "sort_code": "123445"
        }
    }
}

Get a list of beneficiaries

Use this to retrieve multiple records of beneficiary details.

GET /accounts/beneficiaries
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Response

Parameter Format Length Description
status int 1-2 The outcome of the request.
message string 0-100 Handy text describing the response_code or error for debugging.
data object
total int Count of objects in list.
list array
beneficiary_id string 36 The unique customer profile reference returned to you as part of the create beneficiary procress.
Acceptable Characters: a-z A-Z , . – _
merchant_customer_id string 36 The unique customer profile reference returned to you as part of the create.
Acceptable Characters: a-z A-Z , . – _
first_name string 0-50 Beneficiaries first name.
Acceptable Characters: a-z A-Z , . – _ ’
middle_name string 0-50 Beneficiaries middle name.
Acceptable Characters: a-z A-Z , . – _ ’
last_name string 0-50 Beneficiaries last name.
Acceptable Characters: a-z A-Z , . – _ ’
email string 0-50 Beneficiaries email address.
Acceptable Characters: 0-9 a-z A-z _ – . @
phone string 0-50 Beneficiaries phone number.
Acceptable Characters: 0-9 ( ) + –
address object
number string 1-11 Beneficiaries street number.
Acceptable Characters: a-z A-Z 0-9
refinement string 1-100 The address refinement, may include flat number, house name etc e.g. Suite 2, 4th Floor.
Acceptable Characters: a-z A-Z 0-9 . - _
street string 1-100 Beneficiaries street address.
Acceptable Characters: a-z A-Z 0-9 , . - _
city string 1-100 Beneficiaries city.
Acceptable Characters: a-z A-Z 0-9 , . - _
postal_code string 1-100 Beneficiaries ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
iso_country string 3 Beneficiaries country, an ISO 3166 2-character code.
Acceptable Characters: a-z A-Z
account object
account_number int 0-9 Beneficiaries bank account number.
Acceptable Characters: 0-9
sort_code string 0-9 Beneficiaries bank sort code.
Acceptable Characters: 0-9 -		 
{
    "status": 1,
    "message": "Success",
    "data": {
        "total": 1,
        "list": [{
            "beneficiary_id": "22938286-283a-4594-b21c-afb1bd52d22c",
            "merchant_customer_id": "32938286-283a-4594-b21c-afb1bd52d22c",
            "first_name": "Joe",
            "middle_name": "Anthony",
            "last_name": "Bloggs",
            "email": "example@acquired.com",
            "phone": "0876543456",
            "account": {
                "account_number": "12345678",
                "sort_code": "123456"
            }
        }]
    }
}