Create an entity: its database file, its schema, its commodities and its opening chart
const url = 'https://example.com/v1/entities';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"entity_id":"acme-holdings","legal_name":"example","legal_form":"example","country":"example","base_currency":"example","base_precision":1,"commodities":[{"code":"example","precision":1}],"starter_chart":false,"tax_regime":{},"reason":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/entities \ --header 'Content-Type: application/json' \ --data '{ "entity_id": "acme-holdings", "legal_name": "example", "legal_form": "example", "country": "example", "base_currency": "example", "base_precision": 1, "commodities": [ { "code": "example", "precision": 1 } ], "starter_chart": false, "tax_regime": {}, "reason": "example" }'Create a new set of books and serve them from this process immediately.
The reply is one EntitySummary, the same object GET /v1/entities lists and
GET /v1/entities/{entity_id} returns, so the caller can follow links.capabilities straight into the
new book.
Creating an entity that is already served is not an update. The id is its permanent address and the books
behind it are somebody’s accounts, so a second creation is refused rather than merged. A retry of the same
creation (same credential, same Idempotency-Key, same body) replays the original 201, so it is safe to
retry over a connection that dropped after the books were written.
Request Bodyrequired
Section titled “Request Bodyrequired”Create one entity: its database file, its schema, its commodities and its opening chart.
Everything here is supplied by the caller, because every part of it is permanent or nearly so. The id is the entity’s address in every URL and the name of the file it lives in, so it is a plain slug with no second spelling.
base_precision is explicit, as initialize_entity requires: defaulting to two decimals would silently
hold a zero-decimal currency to hundredths, and every later amount would be wrong by a factor of a hundred
without anything reporting it.
starter_chart defaults to false. A book about to be imported or authored wants its own chart, and
accounts added by a default would have to be noticed and archived. Either way, the equity account an
opening balance lands in is created by initialize_entity; without it an entity cannot take an opening
balance at all.
object
The entity’s permanent address: 1-63 characters of lower-case letters, digits and hyphens
The registered name, as it appears on the statements
E.g. Ltd, Inc, B.V., S.L.
ISO country code
The currency this entity’s statements are presented in
Decimal places for the base currency; 2 for USD, 0 for JPY
Further commodities beyond the base currency
object
The commodity’s code, e.g. USD
Decimal places this commodity is held to; 2 for USD, 0 for JPY
Add the generic starter chart (cash, receivables, payables, general expenses, sales) as well as the retained-earnings equity account
Responses
Section titled “Responses”Successful Response
object
object
Example generated
{ "entity_id": "example", "legal_name": "example", "legal_form": "example", "country": "example", "base_currency": "example", "commodities": [ "example" ], "lock_through": "example", "lock_version": 1, "lock_close_id": "example", "live_close_eligible": true, "links": { "additionalProperty": "example" }}Bad Request
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Unauthorized
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Forbidden
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Not Found
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Conflict
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Precondition Failed
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Unprocessable Content
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Internal Server Error
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Service Unavailable
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}