Fiscal Periods API

The Fiscal Periods API provides comprehensive management of fiscal years and periods, including period open/close workflows, year-end close, and date constraints for journal entries.

Base Path

/api/v1/organizations/{organizationId}/companies/{companyId}

All endpoints require authentication with a valid session token.

Period Status Model

Fiscal periods use a simple 2-state model:

Open - Accepts journal entries and modifications
Closed - No journal entries allowed (read-only)

Periods can be reopened with full audit trail tracking.

Period 13 (Adjustment Period)

All fiscal years automatically include Period 13 - a mandatory adjustment period for year-end adjustments and consolidation compatibility per US GAAP.

Fiscal Years

List Fiscal Years

Retrieve all fiscal years for a company.

GET /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years

curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years" \
  -H "Authorization: Bearer your-session-token"

{
  "fiscalYears": [
    {
      "id": "fy_123e4567-e89b-12d3-a456-426614174000",
      "companyId": "comp_123e4567-e89b-12d3-a456-426614174000",
      "year": 2025,
      "name": "FY 2025",
      "startDate": "2025-01-01",
      "endDate": "2025-12-31",
      "status": "Open",
      "includesAdjustmentPeriod": true,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": "fy_987e6543-e21b-12d3-a456-426614174000",
      "companyId": "comp_123e4567-e89b-12d3-a456-426614174000",
      "year": 2024,
      "name": "FY 2024",
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "status": "Closed",
      "includesAdjustmentPeriod": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 2
}

Get Fiscal Year

Retrieve a single fiscal year by ID.

GET /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years/{fiscalYearId}

curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years/{fiscalYearId}" \
  -H "Authorization: Bearer your-session-token"

Create Fiscal Year

Create a new fiscal year with auto-generated monthly periods (1-12) plus Period 13.

POST /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years

curl -X POST "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 2026,
    "name": "FY 2026",
    "startDate": "2026-01-01",
    "endDate": "2026-12-31"
  }'

year

integer

required

Fiscal year number (1900-2999)

name

string

Optional custom name (defaults to “FY ”)

startDate

string

required

Fiscal year start date (ISO 8601: YYYY-MM-DD)

endDate

string

required

Fiscal year end date (ISO 8601: YYYY-MM-DD)

Period 13 (adjustment period) is always created automatically. This is mandatory for consolidation compatibility and audit compliance.

Close Fiscal Year (Year-End Close)

Execute year-end closing workflow:

Generate closing journal entries to transfer income statement balances to retained earnings
Close all open periods
Set fiscal year status to Closed

POST /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years/{fiscalYearId}/close

curl -X POST "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years/{fiscalYearId}/close" \
  -H "Authorization: Bearer your-session-token"

{
  "fiscalYearId": "fy_123e4567-e89b-12d3-a456-426614174000",
  "closedAt": "2026-01-15T10:30:00Z",
  "closedBy": "user_123e4567-e89b-12d3-a456-426614174000",
  "closingJournalEntries": [
    {
      "id": "je_close_revenue",
      "description": "Year-end close: Revenue accounts to Retained Earnings",
      "amount": "1500000.00"
    },
    {
      "id": "je_close_expense",
      "description": "Year-end close: Expense accounts to Retained Earnings",
      "amount": "1200000.00"
    }
  ],
  "netIncome": "300000.00",
  "retainedEarningsAccountId": "acc_retain_123"
}

Prerequisites:

Retained earnings account must be configured in Company Settings
Trial balance must be balanced
Fiscal year must be Open

Reopen Fiscal Year

Reverse year-end close by creating reversal entries and reopening all periods.

POST /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years/{fiscalYearId}/reopen

curl -X POST "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years/{fiscalYearId}/reopen" \
  -H "Authorization: Bearer your-session-token"

Use with caution - this is typically for correction scenarios only.

Preview Year-End Close

Get a preview of year-end close without making changes.

GET /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years/{fiscalYearId}/close/preview

curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years/{fiscalYearId}/close/preview" \
  -H "Authorization: Bearer your-session-token"

{
  "netIncome": "300000.00",
  "totalRevenue": "1500000.00",
  "totalExpenses": "1200000.00",
  "retainedEarningsAccountId": "acc_retain_123",
  "retainedEarningsAccountName": "Retained Earnings",
  "canClose": true,
  "blockers": []
}

Fiscal Periods

List Fiscal Periods

Retrieve all periods for a fiscal year.

GET /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods

curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods" \
  -H "Authorization: Bearer your-session-token"

status

enum

Filter by status: Open, Closed

{
  "periods": [
    {
      "id": "fp_123e4567-e89b-12d3-a456-426614174000",
      "fiscalYearId": "fy_123e4567-e89b-12d3-a456-426614174000",
      "periodNumber": 1,
      "periodName": "January 2025",
      "periodType": "Regular",
      "startDate": "2025-01-01",
      "endDate": "2025-01-31",
      "status": "Open",
      "reopenCount": 0,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": "fp_period13",
      "fiscalYearId": "fy_123e4567-e89b-12d3-a456-426614174000",
      "periodNumber": 13,
      "periodName": "Period 13 (Adjustments)",
      "periodType": "Adjustment",
      "startDate": "2025-12-31",
      "endDate": "2025-12-31",
      "status": "Open",
      "reopenCount": 0,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 13
}

Get Fiscal Period

Retrieve a single period by ID.

GET /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods/{periodId}

curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods/{periodId}" \
  -H "Authorization: Bearer your-session-token"

Open Fiscal Period

Transition a period from Closed to Open status.

POST /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods/{periodId}/open

curl -X POST "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods/{periodId}/open" \
  -H "Authorization: Bearer your-session-token"

Requires fiscal_period:manage permission.

Close Fiscal Period

Transition a period from Open to Closed status. No journal entries allowed after close.

POST /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods/{periodId}/close

curl -X POST "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods/{periodId}/close" \
  -H "Authorization: Bearer your-session-token"

Get Period Reopen History

Retrieve the audit history of all times a period has been reopened.

GET /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods/{periodId}/reopen-history

curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-years/{fiscalYearId}/periods/{periodId}/reopen-history" \
  -H "Authorization: Bearer your-session-token"

{
  "history": [
    {
      "reopenedAt": "2025-02-05T14:30:00Z",
      "reopenedBy": "user_123e4567-e89b-12d3-a456-426614174000",
      "reason": "Correcting misposted entry",
      "reclosedAt": "2025-02-05T16:00:00Z"
    }
  ],
  "total": 1
}

Date Picker Support

Get Period Status for Date

Check the fiscal period status for a specific date.

GET /api/v1/organizations/{organizationId}/companies/{companyId}/period-status?date=2025-03-15

curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/period-status?date=2025-03-15" \
  -H "Authorization: Bearer your-session-token"

date

string

required

Date to check (ISO 8601: YYYY-MM-DD)

{
  "status": "Open",
  "allowsJournalEntries": true,
  "allowsModifications": true
}

Get Periods Summary

Retrieve all periods with computed date ranges for date picker constraints.

GET /api/v1/organizations/{organizationId}/companies/{companyId}/fiscal-periods/summary

curl -X GET "https://your-instance.accountability.app/api/v1/organizations/{orgId}/companies/{companyId}/fiscal-periods/summary" \
  -H "Authorization: Bearer your-session-token"

{
  "periods": [
    {
      "fiscalYearId": "fy_2025",
      "fiscalYear": 2025,
      "periodId": "fp_2025_01",
      "periodNumber": 1,
      "periodName": "January 2025",
      "periodType": "Regular",
      "startDate": "2025-01-01",
      "endDate": "2025-01-31",
      "status": "Open"
    }
  ],
  "openDateRanges": [
    { "startDate": "2025-01-01", "endDate": "2025-03-31" }
  ],
  "closedDateRanges": [
    { "startDate": "2024-01-01", "endDate": "2024-12-31" }
  ]
}

Use this endpoint to:

Enable dates in open periods
Disable dates in closed periods with tooltip “Period is closed”
Disable dates with no period with tooltip “No fiscal period defined”

Error Responses

Fiscal Year Not Found (404)

{
  "_tag": "FiscalYearNotFoundError",
  "fiscalYearId": "fy_123e4567-e89b-12d3-a456-426614174000",
  "message": "Fiscal year not found"
}

Fiscal Period Not Found (404)

{
  "_tag": "FiscalPeriodNotFoundError",
  "fiscalPeriodId": "fp_123e4567-e89b-12d3-a456-426614174000",
  "message": "Fiscal period not found"
}

Fiscal Year Already Exists (409)

{
  "_tag": "FiscalYearAlreadyExistsError",
  "companyId": "comp_123e4567-e89b-12d3-a456-426614174000",
  "year": 2025,
  "message": "Fiscal year 2025 already exists for this company"
}

Invalid Status Transition (400)

{
  "_tag": "InvalidStatusTransitionError",
  "currentStatus": "Open",
  "targetStatus": "Closed",
  "message": "Invalid status transition from Open to Closed"
}

Retained Earnings Not Configured (400)

{
  "_tag": "RetainedEarningsNotConfiguredError",
  "companyId": "comp_123e4567-e89b-12d3-a456-426614174000",
  "message": "Retained earnings account must be configured in Company Settings before closing the fiscal year"
}

Year Already Closed (409)

{
  "_tag": "YearAlreadyClosedError",
  "fiscalYearId": "fy_123e4567-e89b-12d3-a456-426614174000",
  "closedAt": "2026-01-15T10:30:00Z",
  "message": "Fiscal year is already closed"
}

Overview

Core Endpoints

Consolidation

Reporting

Currency

Fiscal Periods API

Fiscal Periods API

Base Path

Period Status Model

Period 13 (Adjustment Period)

Fiscal Years

List Fiscal Years

Get Fiscal Year

Create Fiscal Year

Close Fiscal Year (Year-End Close)

Reopen Fiscal Year

Preview Year-End Close

Fiscal Periods

List Fiscal Periods

Get Fiscal Period

Open Fiscal Period

Close Fiscal Period

Get Period Reopen History

Date Picker Support

Get Period Status for Date

Get Periods Summary

Error Responses

Build docs developers (and LLMs) love

Overview

Core Endpoints

Consolidation

Reporting

Currency

​Fiscal Periods API

​Base Path

​Period Status Model

​Period 13 (Adjustment Period)

​Fiscal Years

​List Fiscal Years

​Get Fiscal Year

​Create Fiscal Year

​Close Fiscal Year (Year-End Close)

​Reopen Fiscal Year

​Preview Year-End Close

​Fiscal Periods

​List Fiscal Periods

​Get Fiscal Period

​Open Fiscal Period

​Close Fiscal Period

​Get Period Reopen History

​Date Picker Support

​Get Period Status for Date

​Get Periods Summary

​Error Responses

Build docs developers (and LLMs) love

Fiscal Periods API

Base Path

Period Status Model

Period 13 (Adjustment Period)

Fiscal Years

List Fiscal Years

Get Fiscal Year

Create Fiscal Year

Close Fiscal Year (Year-End Close)

Reopen Fiscal Year

Preview Year-End Close

Fiscal Periods

List Fiscal Periods

Get Fiscal Period

Open Fiscal Period

Close Fiscal Period

Get Period Reopen History

Date Picker Support

Get Period Status for Date

Get Periods Summary

Error Responses