Entity Management

The entity management endpoints allow you to create, retrieve, update, and delete entities in your Open Ledger account. An entity represents a financial entity (like a company or organization) that you want to manage accounting data for.

Entity Object

An entity in Open Ledger represents a financial entity with the following structure:

1 {
2   "id": "entity_12345",
3   "external_id": "client123",
4   "legal_name": "Acme Corporation",
5   "tin": "12-3456789",
6   "us_state": "DE",
7   "entity_type": "CORPORATION",
8   "phone_number": "+14155551234",
9   "developer_id": "dev_12345",
10   "clerk_id": "clerk_67890",
11   "date_created": "2023-05-15T12:00:00Z",
12   "status": "ACTIVE",
13   "instance_id": "inst_54321",
14   "address": {
15     "street": "123 Main St",
16     "city": "San Francisco",
17     "state": "CA",
18     "zip": "94105",
19     "country": "US"
20   },
21   "settings_id": 42
22 }

Create an Entity

Create a new entity in your Open Ledger account.

1 POST /v1/entity
2 Authorization: Bearer {access_token}
3 Content-Type: application/json

Request Body

Field	Type	Description
`external_id`	string	Your own identifier for the entity (required)
`legal_name`	string	Legal name of the entity (required)
`tin`	string	Tax Identification Number (optional)
`us_state`	string	US state of incorporation (optional)
`entity_type`	enum	Legal entity type: LLC, CORPORATION, PARTNERSHIP, SOLE_PROPRIETORSHIP, NON_PROFIT
`phone_number`	string	Contact phone number (optional)
`developer_id`	string	Your developer ID (required)
`status`	enum	entity status: ACTIVE, INACTIVE (default: ACTIVE)

1 {
2   "external_id": "client123",
3   "legal_name": "Acme Corporation",
4   "tin": "12-3456789",
5   "us_state": "DE",
6   "entity_type": "CORPORATION",
7   "phone_number": "+14155551234",
8   "developer_id": "dev_12345",
9   "status": "ACTIVE"
10 }

Response

1 {
2   "id": "entity_123abc",
3   "external_id": "client123",
4   "legal_name": "Acme Corporation",
5   "tin": "12-3456789",
6   "us_state": "DE",
7   "entity_type": "CORPORATION",
8   "phone_number": "+14155551234",
9   "status": "ACTIVE",
10   "date_created": "2023-05-15T12:00:00Z",
11   "developer_id": "dev_12345"
12 }

Get an Entity

Retrieve a specific entity by ID.

1 GET /v1/entity?entityId={entity_id}
2 Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`entityId`	string	entity ID

Response

1 {
2   "id": "entity_123abc",
3   "external_id": "client123",
4   "legal_name": "Acme Corporation",
5   "tin": "12-3456789",
6   "us_state": "DE",
7   "entity_type": "CORPORATION",
8   "phone_number": "+14155551234",
9   "status": "ACTIVE",
10   "date_created": "2023-05-15T12:00:00Z",
11   "developer_id": "dev_12345",
12   "instance_id": "inst_789ghi",
13   "settings_id": 42,
14   "address": {
15     "street": "123 Main St",
16     "city": "San Francisco",
17     "state": "CA",
18     "zip": "94105",
19     "country": "US"
20   }
21 }

Update an Entity

Update an existing entity.

1 PUT /v1/entity?entityId={entity_id}
2 Authorization: Bearer {access_token}
3 Content-Type: application/json

Query Parameters

Parameter	Type	Description
`entityId`	string	entity ID

Request Body

You only need to include the fields you want to update.

1 {
2   "legal_name": "Acme Corporation Inc.",
3   "phone_number": "+14155559876",
4   "status": "ACTIVE"
5 }

Response

1 {
2   "id": "entity_123abc",
3   "external_id": "client123",
4   "legal_name": "Acme Corporation Inc.",
5   "tin": "12-3456789",
6   "us_state": "DE",
7   "entity_type": "CORPORATION",
8   "phone_number": "+14155559876",
9   "status": "ACTIVE",
10   "date_created": "2023-05-15T12:00:00Z",
11   "developer_id": "dev_12345"
12 }

Delete an Entity

Delete an entity by ID. This is a permanent operation and cannot be undone.

1 DELETE /v1/entity?entityId={entity_id}
2 Authorization: Bearer {access_token}

Deleting an entity will also delete all associated data, including accounts, transactions, and reports. This action cannot be undone.

Query Parameters

Parameter	Type	Description
`entityId`	string	entity ID

Response

A successful request will return a 204 No Content response with no body.

Entity Settings

entity settings control various aspects of the entity’s behavior, including accounting preferences and features.

Get Entity Settings

Get settings for a specific entity.

1 GET /v1/entity/settings?entityId={entity_id}
2 Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`entityId`	string	entity ID

Response

1 {
2   "smartSuggestions": true,
3   "smartAssistant": true,
4   "smartSummary": true,
5   "notificationFrequency": "DAILY",
6   "accountingMethod": "ACCRUAL",
7   "fiscalYearStart": "2023-01-01T00:00:00Z",
8   "defaultCurrency": "USD"
9 }

Update Entity Settings

Update settings for a specific entity.

1 PUT /v1/entity/settings?entityId={entity_id}
2 Authorization: Bearer {access_token}
3 Content-Type: application/json

Query Parameters

Parameter	Type	Description
`entityId`	string	entity ID

Request Body

1 {
2   "smartSuggestions": true,
3   "smartAssistant": true,
4   "smartSummary": false,
5   "notificationFrequency": "WEEKLY",
6   "accountingMethod": "CASH",
7   "fiscalYearStart": "2023-02-01T00:00:00Z",
8   "defaultCurrency": "USD"
9 }

Response

Returns the updated settings object.

Export Entity Data

Export entity data for backup or analysis purposes.

1 POST /v1/entity/{id}/export

Path Parameters

Parameter	Type	Description
`id`	string	entity ID

Response

1 {
2   "export_id": "export_123abc",
3   "status": "processing",
4   "download_url": null,
5   "created_at": "2024-01-01T00:00:00Z"
6 }

Get Export Status

Check the status of an export.

1 GET /v1/entity/{id}/export/{export_id}

Path Parameters

Parameter	Type	Description
`id`	string	entity ID
`export_id`	string	Export ID

Response

1 {
2   "export_id": "export_123abc",
3   "status": "completed",
4   "download_url": "https://openledger-exports.s3.amazonaws.com/entity_123abc/2024-01-01.zip",
5   "expires_at": "2024-02-01T00:00:00Z"
6 }

Error Handling

Status Code	Description
`400`	Bad Request - Invalid input parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - entity not found
`409`	Conflict - entity with same external ID already exists
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Next Steps

Now that you understand how to manage entities, you can explore other areas of the API:

Ledger Accounts

Manage your chart of accounts

Transactions

Record financial transactions