Entities #

An Entity is a means for the centralization of Transactions, Accounts and Financial Reports. It represents a person (Natural or Artificial) engaged in a Business Activity for whom Financial Reports are to be be prepared.

Properties #

Direct Properties #

NameStringThe legal name of the Business
LocaleString (ISO language code)The language used to format Currency Amounts. Defaults to en_GB
Multi CurrencyBooleanDetermines whether the Business transacts in Foreign Currencies. Defaults to false
Year StartInteger (1 - 12)The Calendar month when the Financial Year of the Business begins. Defaults to 1 (January)
Mid Year BalancesBooleanDetermines whether opening Balances are allowed for the Business for dates within the current Reporting Period. Defaults to false

Indirect Properties #

CurrencyDictionaryThe Reporting Currency of the Entity
Current Reporting PeriodDictionaryThe Entity’s currently running Reporing Period
Reporting PeriodListThe Reporting Periods that the Entity has had so far
CurrenciesListCurrencies registered for the Entity

Basics #

The minimum parameters required to create a new Entity Resource is the name and an ISO currency code. The currency Resource is created automatically from the currency code. A Reporting Period is also created with the default Year Start (January).

Request #

curl --location --request POST 'https://api.microbooks.io/books/v1/entity' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "name": "Acme Inc",
        "currency_code": "USD",
import requests

url = "https://api.microbooks.io/books/v1/entity"
body = {"name": "Acme Inc", "currency_code": "USD"}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/entity',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "name": "Acme Inc", 
        "currency_code": "USD", 
request(options, function (error, response) {
    if (error) throw new Error(error);
$client = new Client();
$body = '{
    "name": "Acme Inc",
    "currency_code": "USD",
$request = new Request('POST', 'https://api.microbooks.io/books/v1/entity', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/entity");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"name\": \"Acme Inc\", 
    \"currency_code\": \"USD\", 
request.AddParameter("text/plain", body,  ParameterType.RequestBody);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);

Response #

    "message":"Entity: Acme Inc created successfully",
    "resource": {
        "name":"Acme Inc",
        "current_reporting_period": {
        "currency": {
            "name":"US Dollar",

Variations #

Multi Currency #

To enable the Business record Transactions in Currencies other than the reporting currency, set the multi_currency to true when creating/updating the resource.

    "name": "Acme Inc",
    "currency_code": "USD",,
    "multi_currency": "true",

Custom Year Start #

If the Business' financial year starts in the middle of the calendar year, set the year_start to the number representing the starting month when creating/updating the resource.

    "name": "Acme Inc",
    "currency_code": "USD",,
    "year_start": "4", // April

Mid Year Balances #

If you wish for Balances to be recorded in the middle of the current Reporting Period for the Business, set the mid_year_balances to true when creating/updating the resource.

    "name": "Acme Inc",
    "currency_code": "USD",,
    "mid_year_balances": "true",

Custom Amount Formatting #

To format the currency amounts in the Financial Reports of the Business with a custom language, set the locale to the ISO code of the language when creating/updating the resource.

    "name": "Acme Inc",
    "currency_code": "USD",,
    "locale": "ar_BH", // Bahrain Arabic

Errors #

Below are the Errors that are returned by the Entity Resource.

Detail CodeNameDefinition
100Orphaned ItemsCannot recycle the Entity Resource because it has dependent Resources
101Unconfigured LocaleA Currency Amount converion was attempted for a Locale that has not been configured
102Missing Reporting CurrencyAn Entity requires at least one Currency Resource to serve as the currency in which Financial Statements are prepared