Beneficiaries

A beneficiary represents a destination account that money can be paid out to from accounts that are linked with your Felloh account.

An example of a Beneficiaries Object

{
  "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
}

idstring

Unique identifier for the object.

organisationobject

A compact organisation object representing the organisation owner of the beneficiary.

bankobject

A bank object detailing the destination account of the beneficiary.

is_activestring

Whether the beneficiary is active and can be used for distributing funds to.

---

Fetch all

POST/ledger/beneficiaries

import axios from 'axios';

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

JSON RESPONSE Defined by type parameter being NULL or 'json'

{
  "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
    },
    {
      "id": "84ce4f5e-0100-11ed-b939-0242ac120002",
      "organisation": {
        "id": "X9876",
        "name": "Felloh"
      },
      "bank": {
        "iban": "GB93BARC20038469823592",
        "account_number": "87654321",
        "sort_code": "405060",
        "name": "Jelloh LTD"
      },
      "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 Defined by type parameter being 'csv'

{
  "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
  }
}

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

HTTP Method

POST

HTTP Endpoint

PRODhttps://api.felloh.com/ledger/beneficiaries

SANDBOXhttps://sandbox.felloh.com/ledger/beneficiaries

Payload

Parameter	Required	Type	Description
organisation	true	string	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.
skip	false	Integer	See pagination section for details
take	false	Integer	See pagination section for details
show-child-organisations	fasle	Boolean	Whether to also show beneficiaries for any of the requested organisations child organisations
type	fasle	string	Can be 'csv' or 'json', defaults to json

Response

Returns an array of Beneficiary Objects

---

Create one

PUT/ledger/beneficiaries

import axios from 'axios';

const response = await axios(
  {
    method: 'put',
    url: `https://api.felloh.com/ledger/beneficiaries`,
    data : JSON.stringify({
        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"
  }
}

This endpoint allows you to create a new beneficiary

HTTP Method

PUT

HTTP Endpoint

PRODhttps://api.felloh.com/ledger/beneficiaries

SANDBOXhttps://sandbox.felloh.com/ledger/beneficiaries

Payload

Parameter	Required	Type	Description
organisation	true	string	The organisation ID that you want to create the beneficiary for.
account_name	true	string	The name of the bank account holder.
sort_code	true	string	The bank account sort code
account_number	true	string	The bank account number

Response

Parameter	Type	Description
id	UUID	The ID of the beneficiary that you have created

---

Activate one

POST/ledger/beneficiaries/226009ab-ffe9-4c80-922b-982e8e7849f8/activate

import axios from 'axios';

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

const response = await axios(
  {
    method: 'put',
    url: `https://api.felloh.com/ledger/beneficiaries/${beneficiaryID}/activate`,
    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"
  }
}

This endpoint allows you to activate a beneficiary

HTTP Method

PUT

HTTP Endpoint

PRODhttps://api.felloh.com/ledger/beneficiaries/<BENEFICIARY ID>/activate

SANDBOXhttps://sandbox.felloh.com/ledger/beneficiaries/<BENEFICIARY ID>/activate

Path Parameters

Parameter	Required	Type	Description
beneficiary	true	UUID	The beneficiary id that you wish to activate