KintsugiKintsugi

Preview registering a jurisdiction

POST/registration-preflights

Report what a DIRECT_REQUEST POST /registrations for a jurisdiction would do, without creating anything. Send an Organization-Id, Connection-Id or Entity-Id header to say which organization it is for

result is OK when a new registration would be opened, ABSORBED when an existing sales-tax registration would cover the jurisdiction instead (returned as registration), PLAN_UPGRADE_REQUIRED when the organization's plan does not include the registration, or SALES_TAX_REGISTRATION_REQUIRED when a retail delivery fee registration needs an active sales-tax registration in the jurisdiction first

It assumes the jurisdiction has a nexus, like the register dialog, which only previews jurisdictions the organization is exposed in. A jurisdiction with no nexus reports OK

This is read-only: it stores nothing and never creates a registration.

Authorization

Api-KeystringRequired

Your secret API key. Include it with every request.

Headers

Api-Versiondate

Release date, as YYYY-MM-DD. Defaults to 2026-07-21.

Organization-Idstring

Target organization id (Organization-Id selector).

Connection-Idstring

Target connection id; resolves to its organization.

Entity-Idstring

Platform entity id; resolves to a connection's organization.

Entity-Sourcestring

Optional source to disambiguate an Entity-Id.

Body

countryCodestringRequired

ISO 3166-1 alpha-2 country to check.

stateCodestring

State or province code within countryCode. Omit it for a country-level check.

taxTypePublicTaxTypeEnum

Which taxes the prospective registration would cover.

Available options:SALES_TAXUSE_TAXSALES_AND_USE_TAXRETAIL_DELIVERY_FEE

Response

resultPublicRegisterPreflightResultEnumRequired

OK to open a new registration, ABSORBED when a sales-tax registration would cover it, PLAN_UPGRADE_REQUIRED when the plan does not include it, or SALES_TAX_REGISTRATION_REQUIRED when the retail delivery fee needs an active sales-tax registration first.

Available options:OKABSORBEDPLAN_UPGRADE_REQUIREDSALES_TAX_REGISTRATION_REQUIRED
registrationRegistration

The existing sales-tax registration that would absorb this one. Present only when result is ABSORBED, null otherwise.

200

Successful Response

400

The request was invalid.

401

Authentication failed or was missing.

403

The credential is not permitted for this request.

404

The requested resource was not found.

409

The request conflicts with existing state.

422

The request failed validation.

cURL
POST /registration-preflights
-H "Api-Key: ***"
-H "Api-Version: 2026-07-21"
{
"countryCode": "US",
"stateCode": "CA",
"taxType": "SALES_TAX"
}
Response
{
"result": "OK",
"registration": {
"id": "regs_2mNpQr7Ls8f3k",
"organizationId": "orgn_2mNpQr7Ls8f3k",
"organizationName": "Acme Corp",
"countryCode": "US",
"stateCode": "CA",
"stateName": "California",
"status": "REGISTERED",
"isPreCollecting": false,
"registrationType": "EU_OSS",
"registrationCategory": "REGULAR",
"taxType": "SALES_TAX",
"filingFrequency": "UNKNOWN",
"scheduledFilingFrequency": "UNKNOWN",
"filingFrequencyEffectiveDate": "2027-01-01",
"registrationDate": "2026-01-01",
"createFilingsFrom": "2026-01-01",
"registrationRequested": "2026-07-28T12:00:00Z",
"registrationCompleted": "2026-07-28T12:00:00Z",
"deregistrationRequested": "2026-07-28T12:00:00Z",
"deregistrationCompleted": "2026-07-28T12:00:00Z",
"deregistrationClosureDate": "2026-02-15",
"deregistrationReason": "FULL_BUSINESS_CLOSURE",
"deregistrationAcknowledgedAt": "2026-07-28T12:00:00Z",
"registrationEmail": "tax@example.com",
"salesTaxId": "123-456789",
"iorNumber": "123456789",
"iorDate": "2026-01-01",
"comment": "Reviewed and approved.",
"registrationsRegime": "STANDARD",
"changeRegimeStatus": "REQUESTED",
"ossType": "UNION",
"ossMemberStateOfIdentificationCode": "IE",
"filingWebsiteUrl": "https://onlineservices.cdtfa.ca.gov/",
"amountFees": "150.00",
"amountFeesCurrency": "USD",
"vda": false,
"doNotFile": false,
"imported": false,
"autoRegistered": false
}
}
Preview registering a jurisdiction (2026-07-21) | Kintsugi API Reference