Compliance calendar preview - Commenda — Entity Management, Indirect Tax, Compliance & Corporate APIs for Multinationals

The Compliance Calendar Preview API generates a compliance calendar from a corporation profile without creating or persisting any records. It is intended for stateless preview experiences (for example, a marketing-site calculator or a pre-onboarding flow) where you want to show prospective customers which filings their entity would be subject to in a given fiscal year. Two endpoints are available:

POST /compliance/public/calendar — generate a preview calendar in memory.
GET /compliance/public/supported — enumerate the (country, jurisdiction, corporationType) combinations that the preview supports.

These endpoints are server-to-server only. They are not intended to be called directly from a browser and are not part of the standard partner API surface. Contact the Commenda team to obtain an API key.

Authentication

Pass your API key in the x-api-key header on every request.

curl --request POST \
  --url 'https://api.prod.commenda.io/api/v1/compliance/public/calendar' \
  --header 'x-api-key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

A missing or invalid key returns 401 Unauthorized.

Generate a preview calendar

POST /compliance/public/calendar Returns a list of compliance items (obligations) generated for the supplied corporation profile and target fiscal year. The response is computed in memory; no corporation, compliance, or filing records are created. Responses include Cache-Control: no-store.

Request body

incorporationCountry

string

required

ISO 3166-1 alpha-2 country code where the corporation is incorporated (for example, US).

jurisdiction

string

required

Sub-national jurisdiction code (for example, JUR_US_DE for Delaware). Use the /compliance/public/supported endpoint to discover supported values.

corporationType

string

required

Corporation type for the entity (for example, CCorp, LLC, SCorp). Supported values vary by jurisdiction — see /compliance/public/supported.

formationDate

string

required

ISO 8601 date the entity was formed, for example 2024-03-15. Must be a real calendar date with a year between 1900 and currentYear + 10.

fiscalYearStartDay

integer

required

Day of the month the fiscal year begins (1–31). Must combine with fiscalYearStartMonth to form a real calendar date — for example, (31, 4) (April 31) is rejected.

fiscalYearStartMonth

integer

required

Month the fiscal year begins (1–12).

fiscalYear

integer

required

The target fiscal year to generate obligations for. Must be >= 1900 and no more than 10 years in the future from the current UTC year.

taxElection

string

Optional federal tax election that overrides how the entity is treated when generating obligations. Supported values:

C_CORPORATION
S_CORPORATION
PARTNERSHIP
INDIVIDUAL_OR_SOLE_PROPRIETORSHIP
DISREGARDED_ENTITY
FOREIGN_CORPORATION
FOREIGN_PARTNERSHIP
NONPROFIT
TAX_EXEMPT_ENTITY
REIT
TRUST
COOPERATIVE
ESTATE
TAX_RESIDENT_COMPANY
LISTED_COMPANY

When set, the preview honors the elected classification (for example, an LLC with taxElection: C_CORPORATION returns the C-Corp obligation set).

complianceCategories

array

Optional array of obligation categories to filter by. When omitted or empty, all applicable categories are returned. Maximum size: 15.Active values:

DIRECT_TAX
INDIRECT_TAX
TRANSFER_PRICING
ENTITY_COMPLIANCE
PAYROLL_AND_EMPLOYMENT
CUSTOMS_AND_TRADE

The following values are accepted for backwards compatibility but are deprecated and no longer surface in current obligation content: HR_AND_PAYROLL, CORPORATE_SECRETARIAL, STATISTIC_AUTHORITY, CORPORATE_INCOME_TAX, OTHER, INDIRECT_TAX_COMPLIANCE, DIRECT_TAX_COMPLIANCE, PAYROLL_AND_EMPLOYMENT_COMPLIANCE, REGISTRATIONS_AND_IDENTIFIER, CORPORATE_COMPLIANCE_SECRETARIAL, FINANCIAL_REPORTING, LICENSES_AND_REGULATORY_COMPLIANCE. Prefer the active values above for new integrations.

Request example

curl --request POST \
  --url 'https://api.prod.commenda.io/api/v1/compliance/public/calendar' \
  --header 'x-api-key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "incorporationCountry": "US",
    "jurisdiction": "JUR_US_DE",
    "corporationType": "CCorp",
    "formationDate": "2024-03-15",
    "fiscalYearStartDay": 1,
    "fiscalYearStartMonth": 1,
    "fiscalYear": 2026
  }'

Response

{
  "compliances": [
    {
      "id": "5b2f6f1d-1c2a-4f0e-9c3a-3a3c1b8b9a3f",
      "complianceType": "US-DE-CCorp-FORM-1120",
      "title": "US Federal Income Tax Return (Form 1120)",
      "description": "",
      "category": "FEDERAL_INCOME_TAX",
      "frequency": "ANNUAL",
      "version": "FY2026",
      "formNumber": "1120",
      "state": "DE",
      "dueDate": "2027-04-15",
      "effectiveStartDate": "2026-01-01",
      "effectiveEndDate": "2026-12-31",
      "effectiveYear": 2026
    }
  ]
}

compliances

array

Array of preview compliance items generated for the supplied profile and fiscal year. The array is empty when no obligations apply.

Show Compliance item

string

A synthetic UUID generated for this preview row. Not persisted; do not rely on it across calls.

complianceType

string

Composite identifier of the underlying obligation rule, for example US-DE-CCorp-FORM-1120.

title

string

Human-readable name of the obligation.

description

string

Long-form description of the obligation. Currently always returns an empty string.

Error responses

Status	Code	Description
`400`	`UNSUPPORTED_JURISDICTION`	The `(incorporationCountry, jurisdiction, corporationType)` combination is not supported. The response body echoes the values you submitted.
`400`	(validation)	One or more fields failed validation (missing field, invalid enum, out-of-range fiscal year, impossible `fiscalYearStartDay`/`fiscalYearStartMonth`, unknown field).
`401`	—	Missing or invalid `x-api-key` header.

UNSUPPORTED_JURISDICTION example:

{
  "code": "UNSUPPORTED_JURISDICTION",
  "message": "We don't yet generate compliance calendars for US / JUR_US_XX / CCorp."
}

Unknown fields in the request body are rejected with 400. Submit only the documented properties.

Enumerate supported jurisdictions

GET /compliance/public/supported Returns the list of (country, jurisdiction, corporationType) tuples that produce a non-empty calendar from POST /compliance/public/calendar. Use it to constrain pickers and dropdowns in your UI rather than probing the calendar endpoint and handling UNSUPPORTED_JURISDICTION errors. Responses include Cache-Control: max-age=3600, must-revalidate. The set changes only when a jurisdiction is added or removed, so caching for an hour is safe.

Request example

curl --request GET \
  --url 'https://api.prod.commenda.io/api/v1/compliance/public/supported' \
  --header 'x-api-key: <your_api_key>'

Response

{
  "supported": [
    {
      "country": "US",
      "jurisdiction": "JUR_US_DE",
      "corporationType": "CCorp",
      "jurisdictionDisplayName": "Delaware",
      "corporationTypeDisplayName": "C Corporation"
    },
    {
      "country": "US",
      "jurisdiction": "JUR_US_DE",
      "corporationType": "LLC",
      "jurisdictionDisplayName": "Delaware",
      "corporationTypeDisplayName": "Limited Liability Company"
    }
  ]
}

supported

array

Array of supported tuples.

Show Supported tuple

country

string

ISO 3166-1 alpha-2 country code.

jurisdiction

string

Jurisdiction enum value. Country-level entries (where there is no sub-national jurisdiction) use JUR_ZZ__UNKNOWN.

corporationType

string

Corporation type enum value (for example, CCorp, LLC, SCorp).

jurisdictionDisplayName

string

Human-readable jurisdiction name suitable for use as a UI label.

corporationTypeDisplayName

string

Human-readable corporation-type name suitable for use as a UI label.

Error responses

Status	Description
`401`	Missing or invalid `x-api-key` header.

When to use this API

Marketing-site previews — generate a quick “what would my compliance calendar look like?” preview for prospects without creating an entity.
Pre-onboarding flows — show new customers the obligations they would inherit before they commit to onboarding.
Form constraint — drive country, jurisdiction, and corporation-type pickers from GET /compliance/public/supported so callers cannot submit unsupported tuples.

Preview results are computed from the same obligation rules that power the production compliance engine, but no compliance items, filings, or corporation records are created. To produce a persisted, trackable calendar, use the authenticated POST /compliance/calendar endpoint with a real corporation.

Documentation Index

​Authentication

​Generate a preview calendar

​Request body

​Request example

​Response

​Error responses

​Enumerate supported jurisdictions

​Request example

​Response

​Error responses

​When to use this API

Authentication

Generate a preview calendar

Request body

Request example

Response

Error responses

Enumerate supported jurisdictions

Request example

Response

Error responses

When to use this API