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 #

Indirect Properties #

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)

print(response.text)

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);
    console.log(response.body);
});

$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>']], 
    $body
);
$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);
Console.WriteLine(response.Content);

Response #

{
    "status":"success",
    "message":"Entity: Acme Inc created successfully",
    "resource": {
        "name":"Acme Inc",
        "locale":"en_GB",
        "user_id":1,
        "id":1,
        "currency_id":1,
        "current_reporting_period": {
            "calendar_year":"2022",
            "period_count":1,
            "status":"OPEN",
            "entity_id":1,
            "id":1
        },
        "currency": {
            "currency_code":"USD",
            "name":"US Dollar",
            "user_id":1,
            "id":1
        },
        "reporting_periods":[]
    }
}

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.