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>`,
      },
  }
);

use GuzzleHttp\Client;

function getLedgerBeneficiaries($token) {
  $client = new Client();
  $response = $client->post('https://api.felloh.com/ledger/beneficiaries', [
    'headers' => [
      'Content-Type' => 'application/json',
      'Authorization' => 'Bearer ' . $token,
    ],
    'json' => [
      'organisation' => 'X9876',
      'skip' => 10,
      'take' => 20,
    ],
  ]);

  $data = json_decode($response->getBody(), true);
  return $data;
}

$token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
$response = getLedgerBeneficiaries($token);

import requests
import json

def post_ledger_beneficiaries(organisation, skip, take, access_token):
    api_url = 'https://api.felloh.com/ledger/beneficiaries'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}'
    }

    data = {
        'organisation': organisation,
        'skip': skip,
        'take': take
    }

    response = requests.post(api_url, headers=headers, data=json.dumps(data))

    response.raise_for_status()

    return response.text


response_data = post_ledger_beneficiaries('X9876', 10, 20, '<YOUR TOKEN HERE>')
print(response_data)

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var response = await PostLedgerBeneficiaries("X9876", 10, 20, "<YOUR TOKEN HERE>");

        Console.WriteLine(response);
    }

    static async Task<string> PostLedgerBeneficiaries(string organisation, int skip, int take, string accessToken)
    {
        using (HttpClient client = new HttpClient())
        {
            string apiUrl = "https://api.felloh.com/ledger/beneficiaries";
            client.DefaultRequestHeaders.Add("Content-Type", "application/json");
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");

            var requestData = new
            {
                organisation = organisation,
                skip = skip,
                take = take
            };

            var content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestData), Encoding.UTF8, "application/json");

            var httpResponse = await client.PostAsync(apiUrl, content);

            httpResponse.EnsureSuccessStatusCode();

            return await httpResponse.Content.ReadAsStringAsync();
        }
    }
}

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>`,
    },
  }
);

use GuzzleHttp\Client;

function createLedgerBeneficiary($token) {
  $client = new Client();
  $response = $client->put('https://api.felloh.com/ledger/beneficiaries', [
    'headers' => [
      'Content-Type' => 'application/json',
      'Authorization' => 'Bearer ' . $token,
    ],
    'json' => [
      'organisation' => 'X9876',
      'account_name' => 'James Dean',
      'account_number' => '13354647',
      'sort_code' => '560003',
    ],
  ]);

  $data = json_decode($response->getBody(), true);
  return $data;
}

$token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
$response = createLedgerBeneficiary($token);

import requests
import json

def put_ledger_beneficiaries(organisation, account_name, account_number, sort_code, access_token):
    api_url = 'https://api.felloh.com/ledger/beneficiaries'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}'
    }

    data = {
        'organisation': organisation,
        'account_name': account_name,
        'account_number': account_number,
        'sort_code': sort_code
    }

    response = requests.put(api_url, headers=headers, data=json.dumps(data))

    response.raise_for_status()

    return response.text


response_data = put_ledger_beneficiaries('X9876', 'James Dean', '13354647', '560003', '<YOUR TOKEN HERE>')
print(response_data)

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var response = await PutLedgerBeneficiaries("X9876", "James Dean", "13354647", "560003", "<YOUR TOKEN HERE>");

        Console.WriteLine(response);
    }

    static async Task<string> PutLedgerBeneficiaries(string organisation, string accountName, string accountNumber, string sortCode, string accessToken)
    {
        using (HttpClient client = new HttpClient())
        {
            string apiUrl = "https://api.felloh.com/ledger/beneficiaries";
            client.DefaultRequestHeaders.Add("Content-Type", "application/json");
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");

            var requestData = new
            {
                organisation = organisation,
                account_name = accountName,
                account_number = accountNumber,
                sort_code = sortCode
            };

            var content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestData), Encoding.UTF8, "application/json");

            var httpResponse = await client.PutAsync(apiUrl, content);

            httpResponse.EnsureSuccessStatusCode();

            return await httpResponse.Content.ReadAsStringAsync();
        }
    }
}

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>`,
    },
  }
);

use GuzzleHttp\Client;

function activateBeneficiary($token, $beneficiaryID) {
  $url = 'https://api.felloh.com/ledger/beneficiaries/' . $beneficiaryID . '/activate';
  $client = new Client();
  $response = $client->put($url, [
    'headers' => [
      'Content-Type' => 'application/json',
      'Authorization' => 'Bearer ' . $token,
    ],
  ]);

  $data = json_decode($response->getBody(), true);
  return $data;
}

$token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
$beneficiaryID = '226009ab-ffe9-4c80-922b-982e8e7849f8'; // Replace with the actual beneficiary ID
$response = activateBeneficiary($token, $beneficiaryID);

import requests

def put_activate_beneficiary(beneficiary_id, access_token):
    api_url = f'https://api.felloh.com/ledger/beneficiaries/{beneficiary_id}/activate'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}'
    }

    response = requests.put(api_url, headers=headers)

    response.raise_for_status()

    return response.text


beneficiary_id = '226009ab-ffe9-4c80-922b-982e8e7849f8'
response_data = put_activate_beneficiary(beneficiary_id, '<YOUR TOKEN HERE>')
print(response_data)

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string beneficiaryID = "226009ab-ffe9-4c80-922b-982e8e7849f8";
        var response = await PutActivateBeneficiary(beneficiaryID, "<YOUR TOKEN HERE>");

        Console.WriteLine(response);
    }

    static async Task<string> PutActivateBeneficiary(string beneficiaryID, string accessToken)
    {
        using (HttpClient client = new HttpClient())
        {
            string apiUrl = $"https://api.felloh.com/ledger/beneficiaries/{beneficiaryID}/activate";
            client.DefaultRequestHeaders.Add("Content-Type", "application/json");
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");

            var httpResponse = await client.PutAsync(apiUrl, null);

            httpResponse.EnsureSuccessStatusCode();

            return await httpResponse.Content.ReadAsStringAsync();
        }
    }
}

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