Entity Management

Create and manage entities with the Open Ledger API.

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.

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

Request Body

FieldTypeDescription
developerIdstringYour developer ID (required)
externalIdstringYour own identifier for the entity (optional)
legalNamestringLegal name of the entity (optional)
tinstringTax Identification Number (optional)
usStatestringUS state of incorporation (optional)
entityTypeenumLegal entity type: LLC, CORPORATION, PARTNERSHIP, SOLE_PROPRIETORSHIP, NON_PROFIT
phoneNumberstringContact phone number (optional)
clerkIdstringClerk ID (alternative to developerId)
statusenumentity 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.

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

Query Parameters

ParameterTypeDescription
entityIdstringEntity ID (optional - if omitted, returns all entities for the authenticated developer)
cursorstringPagination cursor (optional)
pageSizenumberNumber 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.

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

Query Parameters

ParameterTypeDescription
entityIdstringEntity 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.

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

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

Query Parameters

ParameterTypeDescription
entityIdstringEntity 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:

1Authorization: Bearer YOUR_JWT_TOKEN

You can generate a token using the Authentication API.

Error Handling

Status CodeDescription
400Bad Request - Invalid input parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Entity not found
409Conflict - Entity with same external ID already exists
500Internal 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: