> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commenda.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Registration

> Create a new tax registration for a corporation in a specific jurisdiction

Create a registration to enable tax calculations and automated filing for a jurisdiction. Before calling this endpoint, use the [content endpoints](/engine/indirect-tax/registrations/content/content) to discover available jurisdictions and get the required `registration_content_id`.

## Request Body

<ParamField body="corporation_id" type="string" required>
  The unique identifier for the corporation. Must be a valid UUID.
</ParamField>

<ParamField body="registration_content_id" type="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)
</ParamField>

<ParamField body="tax_types" type="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.
</ParamField>

<ParamField body="frequency" type="string">
  Filing frequency for this registration.

  Values: `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUAL_CALENDAR_YEAR`, `FISCAL_YEAR`, `QUARTERLY_PREPAY_MONTHLY`, `MONTHLY_ACCELERATED_PREPAY_EARLY`

  **For 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.
</ParamField>

<ParamField body="effective_start_date" type="string">
  ISO date (YYYY-MM-DD) when the registration became or becomes effective. Optional for new registrations where the date isn't yet known.
</ParamField>

<ParamField body="tax_registration_id" type="string">
  Your state-issued tax registration ID, permit number, or account number. Required for validation but can be added later via update.
</ParamField>

<ParamField body="member_state_registration_id" type="string">
  The ID of an existing trade bloc registration to link this registration to. Required when creating a registration for an EU member state or any jurisdiction that belongs to a trade bloc.

  The referenced registration must:

  * Belong to the same corporation
  * Be active (not archived or closed)
  * Have a `registration_content_id` that is listed as an allowed member state for the target content

  When provided, the portal configuration is automatically inherited from the trade bloc registration.
</ParamField>

<ParamField body="credential_id" type="string">
  Reference to stored portal credentials. Can be added later via update before requesting validation.
</ParamField>

<ParamField body="portal_id" type="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.

  For member state registrations linked to a trade bloc, the portal is inherited automatically and does not need to be specified.
</ParamField>

## 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.

### Trade bloc registration rules

When creating a registration that requires a member state link:

| Requirement                          | Details                                                                                                   |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| **Trade bloc registration required** | The `member_state_registration_id` must reference an existing registration                                |
| **Same corporation**                 | The trade bloc registration must belong to the same corporation                                           |
| **Active registration**              | The trade bloc registration must not be archived or closed                                                |
| **Allowed content ID**               | The trade bloc registration's content ID must be listed as an allowed member state for the target content |

### Local registration rules

When creating a local registration (CITY, COUNTY, DISTRICT, etc.):

| Requirement                   | Details                                                                             |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| **Parent state required**     | Must have an active state-level registration first                                  |
| **Parent must be configured** | Parent state must have `tax_types` and `frequency` set                              |
| **Inheritance**               | If you omit `tax_types` or `frequency`, they are inherited from the parent state    |
| **Matching**                  | If you provide `tax_types` or `frequency`, they must exactly match the parent state |

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```json Minimal theme={null}
  {
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_content_id": "CCT_US_STATE_CEN_48_RST",
    "tax_types": ["RST"]
  }
  ```

  ```json Basic theme={null}
  {
    "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"
  }
  ```

  ```json Complete theme={null}
  {
    "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",
    "tax_registration_id": "123-456789-00",
    "portal_id": "PORTAL_CA_CDTFA",
    "credential_id": "cred_abc123def456"
  }
  ```

  ```json EU Member State theme={null}
  {
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_content_id": "<member_state_vat_content_id>",
    "tax_types": ["VAT"],
    "frequency": "QUARTERLY",
    "effective_start_date": "2024-01-01",
    "member_state_registration_id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 - Invalid Request Body theme={null}
  {
    "message": "Failed to parse request body.",
    "error": {
      "type": "CLIENT_INVALID_REQUEST_BODY",
      "title": "Failed to validate the request body",
      "detail": "corporation_id is required; registration_content_id is required",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Content Not Found theme={null}
  {
    "error": {
      "type": "REGISTRATION_CONTENT_NOT_FOUND",
      "title": "Registration content not found.",
      "detail": "The registration_content_id 'INVALID_ID' does not exist.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Duplicate Registration theme={null}
  {
    "error": {
      "type": "DUPLICATE_REGISTRATIONS_FOUND",
      "title": "A registration already exists for this jurisdiction.",
      "detail": "You already have an active registration in California. Update the existing registration instead.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Invalid Tax Type theme={null}
  {
    "error": {
      "type": "REGISTRATION_INVALID_TAX_TYPE",
      "title": "Invalid tax type for this jurisdiction.",
      "detail": "Tax type 'XYZ' is not valid for California. Valid options: RST, RUT, DTT.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Parent Registration Required theme={null}
  {
    "error": {
      "type": "REGISTRATION_PARENT_REQUIRED",
      "title": "State-level registration required.",
      "detail": "You must have an active California state registration before registering for Los Angeles County.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Parent Missing Tax Types theme={null}
  {
    "error": {
      "type": "REGISTRATION_PARENT_NOT_CONFIGURED",
      "title": "Parent state registration not configured.",
      "detail": "The parent state registration does not have tax_types configured. Please configure the state registration first.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Parent Missing Frequency theme={null}
  {
    "error": {
      "type": "REGISTRATION_PARENT_NOT_CONFIGURED",
      "title": "Parent state registration not configured.",
      "detail": "The parent state registration does not have frequency configured. Please configure the state registration first.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Frequency Mismatch with Parent theme={null}
  {
    "error": {
      "type": "FREQUENCY_MISMATCH_WITH_PARENT",
      "title": "Frequency must match parent state.",
      "detail": "Frequency 'MONTHLY' does not match the parent state registration frequency 'QUARTERLY'.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Tax Type Not in Parent theme={null}
  {
    "error": {
      "type": "TAX_TYPE_MISMATCH_WITH_PARENT",
      "title": "Tax type not registered at state level.",
      "detail": "Tax type 'RUT' is not registered at the state level. State tax types: [RST, DTT].",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Missing Required Tax Type from Parent theme={null}
  {
    "error": {
      "type": "TAX_TYPE_MISMATCH_WITH_PARENT",
      "title": "Missing required tax type from state.",
      "detail": "Tax type 'DTT' from the state registration must be included.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Invalid Effective Date Format theme={null}
  {
    "error": {
      "type": "CLIENT_INVALID_REQUEST_BODY",
      "title": "Invalid effective_start_date format.",
      "detail": "Date must be in ISO format (YYYY-MM-DD).",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Member State Registration Required theme={null}
  {
    "error": {
      "type": "MEMBER_STATE_REGISTRATION_REQUIRED",
      "title": "Member state registration required.",
      "detail": "A member state registration is required for this registration content.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Invalid Member State Registration theme={null}
  {
    "error": {
      "type": "INVALID_MEMBER_STATE_REGISTRATION",
      "title": "Invalid member state registration.",
      "detail": "The selected member state registration is not allowed for this registration content.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```

  ```json 400 - Member State Not Allowed theme={null}
  {
    "error": {
      "type": "MEMBER_STATE_REGISTRATION_NOT_ALLOWED",
      "title": "Member state registration not accepted.",
      "detail": "This registration content does not accept a member state registration.",
      "status": 400,
      "instance": "/api/v1/registrations"
    }
  }
  ```
</ResponseExample>

## Related

* [Registration Content API](/engine/indirect-tax/registrations/content/content) — Discover jurisdictions and get content IDs
* [Update Registration](/engine/indirect-tax/registrations/registrations-id-POST) — Add credentials before validation
* [Request Validation](/engine/indirect-tax/registrations/registrations-id-request-validation-POST) — Enable automated filing
* [Tax Registrations Overview](/engine/indirect-tax/registrations/registrations) — Full workflow