Beneficiaries

This feature is only available to customers using the Felloh managed trust.

A beneficiary represents a destination account that money can be paid out to from accounts that are linked with your Felloh account. Beneficiaries are associated with specific organisations and are crucial for managing payouts efficiently.

Beneficiaries Model

Properties

Name
id
Type
string
Description
Unique identifier for the object.
Name
organisation
Type
object
Description
A compact organisation object representing the organisation owner of the beneficiary.
Name
bank
Type
object
Description
A bank object detailing the destination account of the beneficiary.
Name
is_active
Type
boolean
Description
Indicates whether the beneficiary is active and can be used for distributing funds to.

{
  "id": "2e0acaee-0476-1982-8686-44b821b0a457",
  "organisation": {
    "id": "X9876",
    "name": "Felloh"
  },
  "bank": {
    "iban": "GB89BARC20040444858415",
    "account_number": "12345678",
    "sort_code": "102030",
    "name": "FELLOH"
  },
  "is_active": true
}

POST/ledger/beneficiaries

Fetch All

This endpoint retrieves all beneficiaries. Beneficiaries are sorted by creation date, with the most recent beneficiaries coming first.

Parameters

Name
organisationrequired
Type
string
Description
The organisation ID that you want to fetch beneficiaries for. You can find the organisation that you have access to by using the List all organisations method.
Name
skip
Type
integer
Description
Pagination offset. See pagination section for details.
Name
take
Type
integer
Description
The number of records to return. See pagination section for details.
Name
show-child-organisations
Type
boolean
Description
Whether to also show beneficiaries for any child organisations.
Name
type
Type
string
Description
Can be 'csv' or 'json', defaults to 'json'.

Returns

Returns an array of beneficiary models

Request

POST

/ledger/beneficiaries

import axios from 'axios';

const response = await axios.post(
  'https://api.felloh.com/ledger/beneficiaries',
  {
    organisation: 'X9876',
    skip: 10,
    take: 20
  },
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

JSON Response

{
  "data": [
    {
      "id": "2e0acaee-0476-1982-8686-44b821b0a457",
      "organisation": {
        "id": "X9876",
        "name": "Felloh"
      },
      "bank": {
        "iban": "GB89BARC20040444858415",
        "account_number": "12345678",
        "sort_code": "102030",
        "name": "FELLOH"
      },
      "is_active": true
    }
  ],
  "errors": {},
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6",
    "count": 1
  }
}

CSV Response

{
  "data": {
    "url": "https://ledger-production-reports.s3.eu-west-2.amazonaws.com/02803bec-dddf-4f3e-902d-ef0e42a856af.csv"
  },
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "02803bec-dddf-4f3e-902d-ef0e42a856af",
    "count": 184
  }
}

PUT/ledger/beneficiaries

Create One

This endpoint allows you to create a new beneficiary.

Parameters

Name
organisationrequired
Type
string
Description
The organisation ID that you want to create the beneficiary for.
Name
account_namerequired
Type
string
Description
The name of the bank account holder.
Name
account_numberrequired
Type
string
Description
The bank account number.
Name
sort_coderequired
Type
string
Description
The bank account sort code.

Returns

Name
id
Type
uuid
Description
The id of the beneficiary that was created.

Request

PUT

/ledger/beneficiaries

import axios from 'axios';

const response = await axios.put(
  'https://api.felloh.com/ledger/beneficiaries',
  {
    organisation: 'X9876',
    account_name: 'James Dean',
    account_number: '13354647',
    sort_code: '560003'
  },
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {
    "id": "226009ab-ffe9-4c80-922b-982e8e7849f8"
  },
  "errors": {},
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}

PUT/ledger/beneficiaries/:beneficiary_id/activate

Activate One

This endpoint allows you to activate a beneficiary.

Path Parameters

Name
beneficiary_id
Type
UUID
Description
The beneficiary id that you wish to activate.

Request

PUT

/ledger/beneficiaries/:beneficiary_id/activate

import axios from 'axios';

const beneficiaryID = '226009ab-ffe9-4c80-922b-982e8e7849f8';

const response = await axios.put(
  `https://api.felloh.com/ledger/beneficiaries/${beneficiaryID}/activate`,
  null,
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {},
  "errors": {},
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}