# Entities

> The businesses whose books you keep. Each entity carries its own tax rates and bank accounts.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List entities

`GET /api/public/v1/entities`

SDK: `prosaic.entities.list(params)`

Returns all entities that the authenticated user has access to within their workspace. Optionally filter by entity ID or client ID.

**Important**: This endpoint is the primary source for entity-level reference data including:
- `taxRates[]` — Available tax rates (GST codes) for each entity. Use `taxRates[].code` when reconciling transactions or creating chart accounts.
- `bankAccounts[]` — Linked bank accounts for each entity. Each bank account includes its linked GL account at `bankAccounts[].entityAccount` (use `entityAccount.id` when posting journals or reconciling against the bank).
- `clients[]` — Client users associated with each entity.

**Chart of accounts**: The `currentTemplateId` field references the *template* the entity was provisioned from — it is **not** the entity's actual chart of accounts. To fetch the entity's GL accounts (including bank-account-linked accounts and any custom accounts), call `GET /api/public/v1/entities/{entityId}/charts`.

### Query parameters

- `entityId` (string): Filter entities by specific entity ID.
- `clientId` (string): Filter entities by client user ID (returns entities where the user is a member)

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `name` (string, required)
    - `type` (string, required)
    - `currentTemplateId` (string, nullable, required)
    - `defaultTaxAccountId` (string, nullable, required)
    - `createdAt` (string, date-time, required)
    - `isGstRegistered` (boolean, nullable, required)
    - `gstPeriodMonths` (number, nullable, required)
    - `gstBasis` (string, nullable, required)
    - `financialYearStartMonth` (number, required)
    - `currency` (string, required)
    - `bankAccounts` (array of objects, required)
      - `id` (string, required)
      - `entityId` (string, nullable, required)
      - `externalId` (string, required)
      - `name` (string, required)
      - `alias` (string, nullable, required)
      - `institution` (string, nullable, required)
      - `accountNumber` (string, nullable, required)
      - `logoUrl` (string, nullable, required)
      - `type` (string, required)
      - `sourceType` (string, nullable, required)
      - `entityAccount` (object, nullable, required)
        - `id` (string, required)
        - `updatedAt` (string)
        - `reportCategoryReviewedAt` (string, nullable)
        - `reportCategoryReviewVersion` (number)
        - `code` (string, required)
        - `name` (string, required)
        - `type` (string, required)
        - `subtype` (string, required)
        - `reportGroup` (object, nullable, required)
          - `id` (string, required)
          - `key` (string, required)
          - `name` (string, required)
          - `status` (string, required)
          - `accountType` (string, required)
        - `reportCategory` (object, nullable, required)
          - `id` (string, required)
          - `key` (string, required)
          - `name` (string, required)
          - `status` (string, required)
        - `taxCode` (string, required)
        - `description` (string, nullable, required)
        - `mappedCode` (string, nullable, required)
        - `isSystem` (boolean, required)
        - `systemRole` (string, nullable)
        - `parentId` (string, nullable)
        - `isExcluded` (boolean)
        - `isIncluded` (boolean)
        - `source` (string): One of: `template`, `overridden`, `custom`.
    - `clients` (array of objects, required)
      - `id` (string, required)
      - `email` (string, required)
      - `name` (string, nullable, required)
      - `tradingName` (string, nullable, required)
      - `createdAt` (string, date-time, required)
    - `taxRates` (array of objects, required)
      - `id` (string, required)
      - `code` (string, required)
      - `name` (string, required)
      - `description` (string, nullable, required)
      - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
  - `meta` (object)
    - `count` (number, required)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.entities.list();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/entities \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Create an entity

`POST /api/public/v1/entities`

SDK: `prosaic.entities.create(params)`

Creates a new entity in the workspace associated with the API key. Supports full entity configuration including GST settings, client assignment, and bank account linking.

### Request body

Content type: `application/json`

- `accountTemplateId` (string, required)
- `type` (string, required): One of: `individual`, `company`, `trust`, `partnership`, `rental`, `other`.
- `name` (string, required)
- `workspaceDimensionIds` (array of strings)
- `isGstRegistered` (boolean)
- `areGstReportsAutomated` (boolean)
- `gstNumber` (string)
- `irdNumber` (string)
- `gstPeriod` (string): One of: `2`, `1`, `3`, `6`, `12`.
- `gstFilingStartDate` (string)
- `nzbn` (string)
- `industryCode` (string)
- `conversionDate` (string, nullable)
- `clientIds` (array of strings)
- `bankAccountIds` (array of strings)
- `isDemo` (boolean)
- `demoType` (string)
- `parties` (array of objects)
  - `name` (string, required)
  - `roles` (array of strings, required)
  - `id` (string)
  - `isOrganisation` (boolean)
  - `nzbn` (string)
  - `shares` (number)
  - `source` (string): One of: `manual`, `nzbn`.
  - `sourceReferences` (array of objects)
    - `source` (string, required): One of: `nzbn-role`.
    - `sourceEntityNzbn` (string, required)
    - `uniqueIdentifier` (string, required)
- `registeredAddress` (string)
- `postalAddress` (string)
- `email` (string)
- `phone` (string)
- `website` (string)
- `tradingNames` (array of strings)
- `registrationDate` (string)
- `entityStatus` (string)
- `entityTypeDescription` (string)
- `companyNumber` (string)

### Responses

- `201`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `type` (string, required)
    - `currentTemplateId` (string, nullable, required)
    - `defaultTaxAccountId` (string, nullable, required)
    - `createdAt` (string, date-time, required)
    - `isGstRegistered` (boolean, nullable, required)
    - `gstPeriodMonths` (number, nullable, required)
    - `gstBasis` (string, nullable, required)
    - `financialYearStartMonth` (number, required)
    - `currency` (string, required)
    - `bankAccounts` (array of objects, required)
      - `id` (string, required)
      - `entityId` (string, nullable, required)
      - `externalId` (string, required)
      - `name` (string, required)
      - `alias` (string, nullable, required)
      - `institution` (string, nullable, required)
      - `accountNumber` (string, nullable, required)
      - `logoUrl` (string, nullable, required)
      - `type` (string, required)
      - `sourceType` (string, nullable, required)
      - `entityAccount` (object, nullable, required)
        - `id` (string, required)
        - `updatedAt` (string)
        - `reportCategoryReviewedAt` (string, nullable)
        - `reportCategoryReviewVersion` (number)
        - `code` (string, required)
        - `name` (string, required)
        - `type` (string, required)
        - `subtype` (string, required)
        - `reportGroup` (object, nullable, required)
          - `id` (string, required)
          - `key` (string, required)
          - `name` (string, required)
          - `status` (string, required)
          - `accountType` (string, required)
        - `reportCategory` (object, nullable, required)
          - `id` (string, required)
          - `key` (string, required)
          - `name` (string, required)
          - `status` (string, required)
        - `taxCode` (string, required)
        - `description` (string, nullable, required)
        - `mappedCode` (string, nullable, required)
        - `isSystem` (boolean, required)
        - `systemRole` (string, nullable)
        - `parentId` (string, nullable)
        - `isExcluded` (boolean)
        - `isIncluded` (boolean)
        - `source` (string): One of: `template`, `overridden`, `custom`.
    - `clients` (array of objects, required)
      - `id` (string, required)
      - `email` (string, required)
      - `name` (string, nullable, required)
      - `tradingName` (string, nullable, required)
      - `createdAt` (string, date-time, required)
    - `taxRates` (array of objects, required)
      - `id` (string, required)
      - `code` (string, required)
      - `name` (string, required)
      - `description` (string, nullable, required)
      - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic.
  - `meta` (object)
    - `count` (number, required)
- `400`: Validation failed, or system account setup is missing or invalid (SYSTEM_ACCOUNT_VALIDATION).
  - `error` (string)
  - `code` (string)
  - `details` (array of objects)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `403`: Forbidden. Either the token is scoped to a single entity
(`TOKEN_ENTITY_SCOPE`), or the token's workspace role is not a firm
staff role — advisor, admin or workspace owner (`INSUFFICIENT_ROLE`).

  - `error` (string)
  - `code` (string)
- `404`: Workspace not found or access denied
  - `error` (string)
  - `code` (string)
- `409`: One or more of the supplied `bankAccountIds` is already linked to a
different entity (`BANK_ACCOUNT_ASSIGNED_TO_DIFFERENT_ENTITY`). Bank
accounts may only be linked while unassigned.

  - `error` (string)
  - `code` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.entities.create({
  accountTemplateId: 'ACCOUNT_TEMPLATE_ID',
  type: 'individual',
  name: 'Example Ltd',
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountTemplateId": "ACCOUNT_TEMPLATE_ID",
    "type": "individual",
    "name": "Example Ltd"
  }'
```