Skip to main content
POST
/
api
/
v1
/
registrations
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_content_id": "CCT_US_STATE_CEN_06_RST",
    "tax_types": ["RST", "DTT"],
    "frequency": "QUARTERLY",
    "effective_start_date": "2024-01-15"
  }'

{
  "message": "Successfully created registration.",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_content_id": "CCT_US_STATE_CEN_06_RST",
    "jurisdiction_id": "JUR_US_STATE_CA",
    "jurisdiction_type": "STATE_OR_PROVINCE",
    "jurisdiction_name": "California",
    "country": "US",
    "state_or_province": "CA",
    "tax_types": ["RST", "DTT"],
    "frequency": "QUARTERLY",
    "effective_start_date": "2024-01-15",
    "registration_status": "REGISTERED",
    "validation_status": "PENDING",
    "registration_type": "EXISTING",
    "registered_by": "API",
    "email_alias": "tax-ca@acme.commenda.io",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
Create a registration to enable tax calculations and automated filing for a jurisdiction. Before calling this endpoint, use the content endpoints to discover available jurisdictions and get the required registration_content_id.

​
Request Body

​
corporation_id
string
required
The unique identifier for the corporation. Must be a valid UUID.
​
registration_content_id
string
required
The content ID identifying the jurisdiction and tax type combination. Obtain this from the /registrations/content/registration-input-options endpoint.Example: CCT_US_STATE_CEN_06_RST (California Retail Sales Tax)
​
tax_types
array
Array of tax types to register for. Must be valid for the selected registration_content_id.Common values:
  • RST — Retail Sales Tax
  • RUT — Retailer’s Use Tax
  • DTT — District Transaction Tax
  • SST — Simplified Sellers Use Tax
For state registrations: Required. Check related_tax_types from the registration options endpoint for required combinations.For local registrations: Optional. If not provided, inherited from parent state. If provided, must exactly match the parent state’s tax types.
​
frequency
string
Filing frequency for this registration.Values: MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUAL_CALENDAR_YEAR, FISCAL_YEAR, QUARTERLY_PREPAY_MONTHLY, MONTHLY_ACCELERATED_PREPAY_EARLYFor state registrations: Can be set later before validation.For local registrations: Optional. If not provided, inherited from parent state. If provided, must exactly match the parent state’s frequency.
​
effective_start_date
string
ISO date (YYYY-MM-DD) when the registration became or becomes effective. Optional for new registrations where the date isn’t yet known.
​
tax_registration_id
string
Your state-issued tax registration ID, permit number, or account number. Required for validation but can be added later via update.
​
credential_id
string
Reference to stored portal credentials. Can be added later via update before requesting validation.
​
portal_id
string
The portal ID for the state’s tax filing portal. Must be a valid portal for the selected registration content. Get available portals from the /registrations/content/portal-fields endpoint.

​
Workflow

  1. Get the registration_content_id — Use /registrations/content/available-jurisdictions to find jurisdictions, then /registrations/content/registration-input-options to get content IDs and valid tax types.
  2. Create the registration — Call this endpoint with required fields. At minimum: corporation_id, registration_content_id, and tax_types.
  3. Complete the registration — Use POST /registrations/{id} to add tax_registration_id, credential_id, and other fields.
  4. Request validation — Once complete, call POST /registrations/{id}/request-validation to begin automated filing.

​
Validation Rules

  • Tax types: Must be valid for the jurisdiction. Invalid combinations return REGISTRATION_INVALID_TAX_TYPE.
  • Frequency: Must be one of the frequencies allowed for the jurisdiction.
  • Portal ID: If provided, must be a valid portal for the registration content.
  • Duplicate prevention: Only one registration per jurisdiction per corporation is allowed.

​
Local Registration Rules

When creating a local registration (CITY, COUNTY, DISTRICT, etc.):
RequirementDetails
Parent state requiredMust have an active state-level registration first
Parent must be configuredParent state must have tax_types and frequency set
InheritanceIf you omit tax_types or frequency, they are inherited from the parent state
MatchingIf you provide tax_types or frequency, they must exactly match the parent state
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_content_id": "CCT_US_STATE_CEN_06_RST",
    "tax_types": ["RST", "DTT"],
    "frequency": "QUARTERLY",
    "effective_start_date": "2024-01-15"
  }'

{
  "message": "Successfully created registration.",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_content_id": "CCT_US_STATE_CEN_06_RST",
    "jurisdiction_id": "JUR_US_STATE_CA",
    "jurisdiction_type": "STATE_OR_PROVINCE",
    "jurisdiction_name": "California",
    "country": "US",
    "state_or_province": "CA",
    "tax_types": ["RST", "DTT"],
    "frequency": "QUARTERLY",
    "effective_start_date": "2024-01-15",
    "registration_status": "REGISTERED",
    "validation_status": "PENDING",
    "registration_type": "EXISTING",
    "registered_by": "API",
    "email_alias": "tax-ca@acme.commenda.io",
    "created_at": "2024-01-15T10:30:00Z"
  }
}