Skip to main content

​
Companies API

The Companies API provides endpoints for managing organizations (top-level containers) and companies (legal entities). Each organization can contain multiple companies, each with its own Chart of Accounts.

​
Base Path

/api/v1
All endpoints require authentication with a valid session token.

​
Organizations

Organizations are the top-level container for companies and shared settings like reporting currency.

​
List Organizations

Retrieve all organizations accessible by the current user.
GET /api/v1/organizations
curl -X GET "https://your-instance.accountability.app/api/v1/organizations" \
  -H "Authorization: Bearer your-session-token"

{
  "organizations": [
    {
      "id": "org_123e4567-e89b-12d3-a456-426614174000",
      "name": "Acme Corporation",
      "reportingCurrency": "USD",
      "settings": {
        "fiscalYearEnd": { "month": 12, "day": 31 }
      },
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

​
Get Organization

Retrieve a single organization by ID.
GET /api/v1/organizations/{id}
curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}" \
  -H "Authorization: Bearer your-session-token"

​
Create Organization

Create a new organization. The current user becomes the organization owner.
POST /api/v1/organizations
curl -X POST "https://your-instance.accountability.app/api/v1/organizations" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Company Group",
    "reportingCurrency": "USD",
    "settings": {
      "fiscalYearEnd": { "month": 12, "day": 31 }
    }
  }'
​
name
string
required
Organization name (must be unique)
​
reportingCurrency
string
required
ISO 4217 currency code for consolidated reporting (e.g., “USD”, “EUR”)
​
settings
object
Organization settings
  • fiscalYearEnd: Object with month (1-12) and day (1-31) for fiscal year end date

​
Update Organization

Update an existing organization. Only provided fields are updated.
PUT /api/v1/organizations/{id}
curl -X PUT "https://your-instance.accountability.app/api/v1/organizations/{orgId}" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Organization Name",
    "reportingCurrency": "EUR"
  }'

​
Delete Organization

Delete an organization. Organizations can only be deleted if they contain no companies.
DELETE /api/v1/organizations/{id}
curl -X DELETE "https://your-instance.accountability.app/api/v1/organizations/{orgId}" \
  -H "Authorization: Bearer your-session-token"
Organizations with companies cannot be deleted. You must first delete or move all companies.

​
Companies

Companies are legal entities within an organization, each with its own Chart of Accounts, fiscal periods, and financial data.

​
List Companies

Retrieve a paginated list of companies for an organization.
GET /api/v1/companies
curl -X GET "https://your-instance.accountability.app/api/v1/companies?organizationId={orgId}&isActive=true&limit=50" \
  -H "Authorization: Bearer your-session-token"
​
organizationId
string
required
Organization UUID
​
isActive
boolean
Filter by active status
​
jurisdiction
string
Filter by jurisdiction code (e.g., “US”, “GB”)
​
limit
integer
default:"50"
Maximum items per page
​
offset
integer
default:"0"
Number of items to skip
{
  "companies": [
    {
      "id": "comp_123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
      "name": "Acme Inc.",
      "legalName": "Acme Incorporated",
      "jurisdiction": "US-DE",
      "taxId": "12-3456789",
      "incorporationDate": "2020-01-15",
      "registrationNumber": "DE12345678",
      "registeredAddress": {
        "line1": "123 Business St",
        "line2": "Suite 100",
        "city": "Wilmington",
        "region": "DE",
        "postalCode": "19801",
        "country": "US"
      },
      "industryCode": "5112",
      "companyType": "Corporation",
      "incorporationJurisdiction": "US-DE",
      "functionalCurrency": "USD",
      "reportingCurrency": "USD",
      "fiscalYearEnd": { "month": 12, "day": 31 },
      "retainedEarningsAccountId": "acc_retain_123",
      "isActive": true,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

​
Get Company

Retrieve a single company by ID.
GET /api/v1/organizations/{organizationId}/companies/{id}
curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}" \
  -H "Authorization: Bearer your-session-token"

​
Create Company

Create a new company within an organization.
POST /api/v1/companies
curl -X POST "https://your-instance.accountability.app/api/v1/companies" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Inc.",
    "legalName": "Acme Incorporated",
    "jurisdiction": "US-DE",
    "taxId": "12-3456789",
    "incorporationDate": "2020-01-15",
    "registrationNumber": "DE12345678",
    "registeredAddress": {
      "line1": "123 Business St",
      "city": "Wilmington",
      "region": "DE",
      "postalCode": "19801",
      "country": "US"
    },
    "industryCode": "5112",
    "companyType": "Corporation",
    "incorporationJurisdiction": "US-DE",
    "functionalCurrency": "USD",
    "reportingCurrency": "USD",
    "fiscalYearEnd": { "month": 12, "day": 31 }
  }'
​
organizationId
string
required
Organization UUID
​
name
string
required
Company display name
​
legalName
string
required
Legal entity name
​
jurisdiction
string
required
Jurisdiction code (e.g., “US-DE”, “GB”, “FR”)
​
taxId
string
Tax identification number
​
incorporationDate
string
Date of incorporation (ISO 8601: YYYY-MM-DD)
​
registrationNumber
string
Company registration number
​
registeredAddress
object
Registered address
  • line1 (string, required)
  • line2 (string, optional)
  • city (string, required)
  • region (string): State/province code
  • postalCode (string, required)
  • country (string, required): ISO 3166-1 alpha-2 code
​
industryCode
string
NAICS industry code
​
companyType
enum
Company type: Corporation, LLC, Partnership, SoleProprietor, NonProfit, Trust, Other
​
incorporationJurisdiction
string
Jurisdiction where company is incorporated
​
functionalCurrency
string
required
ISO 4217 currency code for day-to-day operations (e.g., “USD”)
​
reportingCurrency
string
required
ISO 4217 currency code for financial reporting (e.g., “USD”)
​
fiscalYearEnd
object
required
Fiscal year end date
  • month (integer, 1-12): Month
  • day (integer, 1-31): Day

​
Update Company

Update an existing company. Only provided fields are updated.
PUT /api/v1/organizations/{organizationId}/companies/{id}
curl -X PUT "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Company Name",
    "reportingCurrency": "EUR",
    "isActive": true
  }'
Functional currency cannot be changed after creation as it would affect all historical transactions.

​
Deactivate Company

Deactivate a company (soft delete). Companies with unposted journal entries cannot be deactivated.
DELETE /api/v1/organizations/{organizationId}/companies/{id}
curl -X DELETE "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}" \
  -H "Authorization: Bearer your-session-token"

​
Error Responses

{
  "_tag": "OrganizationNotFoundError",
  "organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
  "message": "Organization not found"
}

{
  "_tag": "CompanyNotFoundError",
  "companyId": "comp_123e4567-e89b-12d3-a456-426614174000",
  "message": "Company not found"
}

{
  "_tag": "OrganizationHasCompaniesError",
  "organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
  "companyCount": 3,
  "message": "Cannot delete organization with 3 companies"
}

{
  "_tag": "CompanyNameAlreadyExistsError",
  "name": "Acme Inc.",
  "organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
  "message": "A company with the name 'Acme Inc.' already exists in this organization"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us