Entities
List and create the entities of a workspace, and read, update, or delete a single entity.
An entity is one legal business inside a workspace, and a workspace can hold several. Listing and creation address the target workspace by its uuid, in the workspaceId query parameter for reads and in the body for creation. bookkeepingStartDate is the first day Kick keeps books for the entity.
Creating an entity also seeds its chart of accounts, and the optional chartOfAccounts field picks the setup. It takes an object with a type, not a bare string:
{ "type": "standard" }, the default when the field is left out, seeds the full standard Kick chart of accounts.{ "type": "custom" }seeds only the accounts Kick automations require, such as clearing accounts and uncategorized income and expenses, and leaves the rest for you to create through Chart of Accounts.
A new entity keeps its books on a cash ledger. To post and report on an accrual basis as well, open the accrual ledger through Ledgers.
Updates are partial and cover name and bookkeepingStartDate, at least one of which has to be present. Moving bookkeepingStartDate regenerates the entity's journal entries, so it is refused with 400 once the books have been anchored: when accounts under the entity carry opening balances or bank reconciliations, or when the new date does not fall after the end of a completed accounting migration.
Deleting an entity is permanent and takes its books with it, including its financial accounts, transactions, and documents. To remove the whole client instead, delete the workspace.
Returns the entities of the workspace given by workspaceId. Results are paged with limit/offset.
Organization access token issued by Kick, sent as Authorization: Bearer kick_org_....
1000200
400
401
404
429
GET /api/platform/v1/entities?workspaceId=123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Host: use.kick.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"bookkeepingStartDate": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"legalType": "sole_proprietorship",
"name": "text",
"workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}
],
"pagination": {
"limit": 1,
"offset": 1,
"total": 1
}
}Creates an entity in the workspace given by workspaceId. bookkeepingStartDate is the first day Kick keeps books for the entity. chartOfAccounts selects the chart of accounts setup: standard (default) seeds the full standard Kick chart, custom seeds only the accounts Kick automations require and leaves the rest to be created manually.
Organization access token issued by Kick, sent as Authorization: Bearer kick_org_....
A unique key that makes the request idempotent. Retrying with the same key within 24 hours replays the original response (marked with Idempotent-Replayed: true) instead of executing again.
Chart of accounts setup for the new entity. Defaults to standard when omitted.
201
400
401
404
409
429
POST /api/platform/v1/entities HTTP/1.1
Host: use.kick.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 170
{
"bookkeepingStartDate": "text",
"chartOfAccounts": {
"type": "standard"
},
"legalType": "sole_proprietorship",
"name": "text",
"workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}{
"entity": {
"bookkeepingStartDate": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"legalType": "sole_proprietorship",
"name": "text",
"workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}
}Returns a single entity. An entity outside the organization's book of business reads as not found.
Organization access token issued by Kick, sent as Authorization: Bearer kick_org_....
200
401
404
429
GET /api/platform/v1/entities/{entityId} HTTP/1.1
Host: use.kick.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"entity": {
"bookkeepingStartDate": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"legalType": "sole_proprietorship",
"name": "text",
"workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}
}Updates the fields present in the body and leaves the others untouched. Changing bookkeepingStartDate regenerates the entity's journal entries; the change is rejected when accounts under the entity have opening balances or bank reconciliations, or when the new date falls inside a completed accounting migration period.
Organization access token issued by Kick, sent as Authorization: Bearer kick_org_....
A unique key that makes the request idempotent. Retrying with the same key within 24 hours replays the original response (marked with Idempotent-Replayed: true) instead of executing again.
First day Kick keeps books for the entity, as YYYY-MM-DD.
200
400
401
404
429
PATCH /api/platform/v1/entities/{entityId} HTTP/1.1
Host: use.kick.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 45
{
"bookkeepingStartDate": "text",
"name": "text"
}{
"entity": {
"bookkeepingStartDate": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"legalType": "sole_proprietorship",
"name": "text",
"workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}
}Permanently deletes an entity together with all of its financial accounts, transactions and documents. This cannot be undone.
Organization access token issued by Kick, sent as Authorization: Bearer kick_org_....
A unique key that makes the request idempotent. Retrying with the same key within 24 hours replays the original response (marked with Idempotent-Replayed: true) instead of executing again.
200
No content
400
401
404
429
DELETE /api/platform/v1/entities/{entityId} HTTP/1.1
Host: use.kick.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Last updated
Was this helpful?