Skip to main content
An Entity is a legal company with its own books, functional currency, and integrations. Every ledger route in the API scopes by entityId. Every Entity belongs to exactly one Organization, and Users reach it through their Membership in that Organization. This page covers the Entity CRUD, ledger-lock date, Fiscal Year start, parent Entity, and Organization move endpoints. An Entity can have a parent Entity that controls it, and the Entities it controls are its subsidiaries. A parent Entity and its subsidiaries form a group, and a group stays inside one Organization: the parent is always an Entity of the same Organization. A Superadmin sets the structure from the Organization in the staff panel.
Open in the app. This resource has a page in the Sintropix web app at https://app.sintropix.com/{entityId}/home, where each id in braces is the same UUID as in the API route or response. Its settings are in its row on the Empresa page of its Organization, at /organizations/{organizationId}/settings. Take organizationId from the Entity. When you mention a record to a user, include that link. See Link to the App for the full URL grammar.

​
POST /api/entities

Create a new Entity in an Organization. The client supplies the idempotency id, so a retried POST with the same id is rejected as a conflict instead of creating a duplicate. Sintropix sets up your Entities for you: you can’t create one from the client app. A Superadmin creates it from the Organization in the staff panel.
  • Superadmin only, from a signed-in session. A request with an API key or an OAuth access token returns 403 with SUPERADMIN_SESSION_REQUIRED, and any other User, staff included, gets 403 with SUPERADMIN_REQUIRED. A Superadmin can create an Entity in any Organization without holding a Membership in it. List every Organization with GET /api/onboarding/organizations.
  • Creating an Entity opens none of its books to the Superadmin. Users reach it through a Membership of its Organization.
  • Creating an Entity also gives it its representing Partner: the Organization’s Partner with the Entity’s tax identity, which the other Entities use to name it as their counterparty. When the Organization already has a Partner with that tax identity, that Partner becomes the representing one.
  • An unknown organizationId returns 404 with ORGANIZATION_NOT_FOUND_ERROR.
  • An unknown country returns 400 with ENTITY_CREATION_COUNTRY_UNKNOWN_ERROR, and an unknown currency returns 400 with ENTITY_CREATION_CURRENCY_UNKNOWN_ERROR.
  • An Entity with the same country and taxId already exists: the request returns 409 with ENTITY_CREATION_TAX_ID_ALREADY_EXISTS_ERROR.
  • An unknown parentEntityId returns 404 with ENTITY_CREATION_PARENT_NOT_FOUND_ERROR. A parent in another Organization returns 409 with ENTITY_CREATION_PARENT_IN_ANOTHER_ORGANIZATION_ERROR.
  • Body:
  • Success response: the created Entity with organizationName, organizationWebsite, and organizationEmailDomain (see Response shape)
  • Status: 201

​
GET /api/entities

List every Entity the caller can access. You see every Entity of each Organization you hold a Membership in, whatever your Role. Being a Superadmin adds no Entities to this list. An OAuth access token sees only the Entities of the Organization it was approved for.
  • Success response: array of Entity objects, each with organizationName, organizationWebsite, and organizationEmailDomain (see Response shape). Group the rows by organizationId to show Entities per Organization.
  • Status: 200

​
GET /api/entities/:entityId/editability

Check whether the identity fields of an Entity (name, country, taxId, currency) are currently editable. Returns a single boolean flag.
  • Path param: entityId (UUID)
  • Success response:
  • Status: 200

​
PATCH /api/entities/:entityId

Update the core identity fields of an Entity. At least one field must be provided. To change the Organization, use PATCH /api/entities/:entityId/organization below. The update canonicalizes Chilean tax registrations and requires both country and taxId when either is supplied. A corrected country or taxId also corrects the Entity’s representing Partner. When another Partner of the Organization already holds the new tax identity, the update returns 409 with ENTITY_TAX_IDENTITY_TAKEN_ERROR, and params.partnerId names that Partner. Correct or clear that Partner’s tax ID first. Once the Entity has had a Ledger Entry, a change to country, taxId, or currency returns 409 with ENTITY_IDENTITY_FIELDS_LOCKED_ERROR. Check first with GET /api/entities/:entityId/editability. An unknown country returns 400 with UNKNOWN_COUNTRY_ERROR, an unknown currency returns 400 with UNKNOWN_CURRENCY_ERROR, and a country and taxId that another Entity already holds returns 409 with ENTITY_ALREADY_EXISTS_ERROR.
  • Path param: entityId (UUID)
  • Body:
  • Success response: the updated Entity (see Response shape)
  • Status: 200

​
PATCH /api/entities/:entityId/ledger-lock-date

Set, move, or clear the ledger lock date. A date freezes the ledger up to and including that date; null clears the lock. The lock date cannot move to a date on or after any Scheduled Entry’s Entry Date.
  • Path param: entityId (UUID)
  • Body:
  • Success response: the updated Entity (see Response shape)
  • Status: 200

​
PATCH /api/entities/:entityId/fiscal-year-start

Set the month the Entity’s Fiscal Year starts in. The Fiscal Year is the twelve months over which the Entity measures its result. It starts on day 1 of the start month, and every Entity starts in January until you change it. The Fiscal Year decides where income and expense accounts restart at zero, and which account carries the result of earlier years. See The Fiscal Year in reports. Sintropix posts no closing entry: every report derives the close when it reads the balances.
  • Path param: entityId (UUID)
  • Body:
  • Success response: the updated Entity (see Response shape)
  • Status: 200
  • A month outside 1 to 12 returns 400. PATCH /api/entities/:entityId doesn’t take fiscalYearStartMonth: it returns 400 when the body carries it.
  • While the Entity has a ledger lock date, the start can’t change. The request returns 409 with ENTITY_FISCAL_YEAR_START_LOCKED_ERROR, and params.ledgerLockDate names the lock date. Clear the lock date, set the start, and set the lock date again.
  • A new start re-cuts every past Fiscal Year, so every report reads the earlier years with the new start too.
In the app, set it in the Entity’s row on the Empresa page of its Organization, under Inicio del año fiscal.
A refusal while a lock date is set:

​
PATCH /api/entities/:entityId/parent

Set, change, or clear the parent Entity that controls this one. An id names the controlling Entity; null makes it a root. The parent must exist, must be in the same Organization, must not be the Entity itself, and must not create a cycle.
  • Superadmin only, from a signed-in session. A request with an API key or an OAuth access token returns 403 with SUPERADMIN_SESSION_REQUIRED, and any other User, staff included, gets 403 with SUPERADMIN_REQUIRED. A Superadmin can set the parent of any Entity without holding a Membership in its Organization.
  • The checks run in this order:
    1. An unknown parent returns 404 with ENTITY_PARENT_NOT_FOUND_ERROR.
    2. A parent in another Organization returns 409 with ENTITY_PARENT_IN_ANOTHER_ORGANIZATION_ERROR.
    3. The Entity as its own parent returns 400 with ENTITY_SELF_PARENT_ERROR.
    4. A parent that is one of the Entity’s own subsidiaries, at any depth, returns 400 with ENTITY_PARENT_CYCLE_ERROR.
  • Path param: entityId (UUID)
  • Body:
  • Success response: the updated Entity (see Response shape)
  • Status: 200

​
PATCH /api/entities/:entityId/organization

Move an Entity to another Organization. Members of the old Organization lose access to the Entity. Members of the new Organization gain it with their Role there.
  • Superadmin only, from a signed-in session. A request with an API key or an OAuth access token returns 403 with SUPERADMIN_SESSION_REQUIRED, and any other User gets 403 with SUPERADMIN_REQUIRED. A Superadmin can move any Entity without holding a Membership in either Organization.
  • Path param: entityId (UUID)
  • Body:
  • Status: 204
  • An unknown organizationId returns 404 with ORGANIZATION_NOT_FOUND_ERROR.
  • An Entity in a group can’t move: an Entity with a parent Entity or any subsidiary returns 409 with ENTITY_MOVE_IN_GROUP_ERROR. Clear those links with PATCH /api/entities/:entityId/parent first, then move it.
  • An Entity that shares its Organization’s data can’t move, because Partners, Dimensions, and Integrations belong to the Organization:
    • The move returns 409 with ENTITY_MOVE_USES_ORGANIZATION_DATA_ERROR when the Entity:
      • Uses Partners of its Organization.
      • Has Ledger Lines that carry a Dimension Value.
      • Has a Source Feed or a bank feed that routes an Integration of its Organization.
      • Has a Book that a Google Sheets Integration exports.
      • Has Ledger Accounts, because each one maps to a Group Account of its Organization.
    • An Entity whose representing Partner another Entity uses returns 409 with ENTITY_MOVE_REPRESENTING_PARTNER_IN_USE_ERROR. params.partnerId names that Partner.
    • When the target Organization already has a Partner with the Entity’s tax identity, the move returns 409 with ENTITY_MOVE_TAX_IDENTITY_TAKEN_ERROR. params.partnerId names that Partner.

​
Response shape

Every endpoint on this page that returns an Entity uses this shape:

​
Domain error codes

​
Status codes