Entity Management | Open Ledger Documentation

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   "name": "Acme Corporation",
5   "entity_type": "LLC",
6   "address": {
7     "street": "123 Main St",
8     "city": "San Francisco",
9     "state": "CA",
10     "zip": "94105",
11     "country": "US"
12   },
13   "settings": {
14     "smart_suggestions": true,
15     "smart_assistant": true,
16     "smart_summary": true,
17     "notification_frequency": "DAILY",
18     "accounting_method": "ACCRUAL",
19     "fiscal_year_start": "2023-01-01T00:00:00Z",
20     "default_currency": "USD"
21   },
22   "plaid_accounts": [],
23   "created_at": "2023-05-15T12:00:00Z",
24   "developer_id": "dev_12345",
25   "instance_id": "inst_54321",
26   "status": "ACTIVE"
27 }

Create an Entity

Create a new entity in your Open Ledger account.

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

Request Body

Field	Type	Description
`developerId`	string	Your developer ID (required)
`externalId`	string	Your own identifier for the entity (optional)
`legalName`	string	Legal name of the entity (optional)
`tin`	string	Tax Identification Number (optional)
`usState`	string	US state of incorporation (optional)
`entityType`	enum	Legal entity type: LLC, CORPORATION, PARTNERSHIP, SOLE_PROPRIETORSHIP, NON_PROFIT
`phoneNumber`	string	Contact phone number (optional)
`clerkId`	string	Clerk ID (alternative to developerId)
`status`	enum	entity status: ACTIVE, INACTIVE (default: ACTIVE)

1 {
2   "developerId": "dev_12345",
3   "externalId": "client123",
4   "legalName": "Acme Corporation",
5   "tin": "12-3456789",
6   "usState": "CA",
7   "entityType": "LLC",
8   "phoneNumber": "+14155551234",
9   "status": "ACTIVE"
10 }

Response

1 {
2   "entity": {
3     "id": "entity_123abc",
4     "externalId": "client123",
5     "legalName": "Acme Corporation",
6     "tin": "12-3456789",
7     "usState": "CA",
8     "entityType": "LLC",
9     "phoneNumber": "+14155551234",
10     "status": "ACTIVE",
11     "dateCreated": "2023-05-15T12:00:00Z",
12     "developerId": "dev_12345",
13     "clerkId": null,
14     "instanceId": "inst_54321"
15   }
16 }

Get Entity Details

Retrieve entity details. You can get a specific entity by ID or all entities for a developer.

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

Query Parameters

Parameter	Type	Description
`entityId`	string	Entity ID (optional - if omitted, returns all entities for the authenticated developer)
`cursor`	string	Pagination cursor (optional)
`pageSize`	number	Number of entities per page (optional, default: 25, max: 100)

Response - Single Entity

When entityId is provided:

1 {
2   "entity": {
3     "id": "entity_123abc",
4     "name": "Acme Corporation",
5     "external_id": "client123",
6     "entity_type": "LLC",
7     "address": {
8       "street": "123 Main St",
9       "city": "San Francisco", 
10       "state": "CA",
11       "zip": "94105",
12       "country": "US"
13     },
14     "settings": {
15       "smart_suggestions": true,
16       "smart_assistant": true,
17       "smart_summary": true
18     },
19     "plaid_accounts": [],
20     "created_at": "2023-05-15T12:00:00Z",
21     "developer_id": "dev_12345",
22     "instance_id": "inst_54321",
23     "status": "ACTIVE"
24   },
25   "nextCursor": null,
26   "hasMore": false
27 }

Response - Multiple Entities

When entityId is omitted (paginated):

1 {
2   "entities": [
3     {
4       "id": "entity_123abc",
5       "name": "Acme Corporation",
6       "external_id": "client123",
7       "entity_type": "LLC",
8       "address": null,
9       "settings": null,
10       "plaid_accounts": [],
11       "created_at": "2023-05-15T12:00:00Z",
12       "developer_id": "dev_12345",
13       "instance_id": "inst_54321",
14       "status": "ACTIVE"
15     }
16   ],
17   "nextCursor": "entity_456def",
18   "hasMore": true
19 }

Update an Entity

Update an existing entity.

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

Query Parameters

Parameter	Type	Description
`entityId`	string	Entity ID (required)

Request Body

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

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

Response

1 {
2   "entity": {
3     "id": "entity_123abc",
4     "externalId": "client123",
5     "legalName": "Acme Corporation Inc.",
6     "tin": "12-3456789",
7     "usState": "CA",
8     "entityType": "LLC",
9     "phoneNumber": "+14155559876",
10     "status": "ACTIVE",
11     "dateCreated": "2023-05-15T12:00:00Z",
12     "developerId": "dev_12345",
13     "updatedAt": "2023-05-16T10:30:00Z"
14   }
15 }

Delete an Entity

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

1 DELETE /v1/entities?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 (required)

Response

1 {
2   "message": "Entity deleted successfully"
3 }

Authentication

All entity management endpoints require a valid JWT token. Include it in the Authorization header:

1 Authorization: Bearer YOUR_JWT_TOKEN

You can generate a token using the Authentication API.

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
`500`	Internal Server Error

Example error response:

1 {
2   "error": {
3     "code": "ENTITY_NOT_FOUND",
4     "message": "Entity not found"
5   }
6 }

Next Steps

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

Transactions

Record financial transactions for your entities

Bank Connections

Connect bank accounts to import transaction data

Reports

Generate financial reports for your entities

AI Analysis

Use AI to categorize and analyze transactions