API changelog
Every change to the Kintsugi API and every release, newest first. Breaking changes carry the Breaking change mark. Tenanted releases are dated, and you choose one with the Api-Version header.
Changes
2026-11-16
Breaking changesRemoves sltr_elected and single_local_tax_rate from the Texas fields on POST /v1/registrationsRegistrationsBreaking change
The Texas jurisdiction_specific_fields on POST /v1/registrations no longer include sltr_elected or single_local_tax_rate. Requests that still send them succeed, and the values are ignored, so a Texas registration created on v1 does not elect the single local tax rate.
- Stop sending
sltr_electedandsingle_local_tax_ratefor Texas registrations. - Remove both fields from request models generated from the earlier
v1spec.
2026-11-14
Elects the Texas single local tax rate with POST /registrations/{registration_id}/single-local-tax-rate-electionRegistrations
POST /registrations/{registration_id}/single-local-tax-rate-election opts a Texas remote seller into the single local tax rate and returns the updated registration. The request has no body, and Kintsugi sets the date the rate starts. A registration still being set up starts on its registrationDate, or on the date nexus was reached when that is blank. An unconfirmed import starts on its first filing period. An active registration starts on the first day of the next filing period, and Kintsugi files the election with the Texas Comptroller. Send an Organization-Id, Connection-Id or Entity-Id selector to say which organization the registration belongs to. The endpoint answers 404 when the registration does not exist or belongs to an organization your credential cannot access, 400 when the registration cannot elect, and 409 when an active registration already has a start date.
- Call the endpoint with the Texas registration's id to elect the rate, then read the returned registration for the result.
- Treat
409as already elected: the registration keeps the date it has.
2026-11-10
Adds registrationExecutedBy, filingExecutedBy and a managedBy filter to registrationsRegistrations
Every registration now returns registrationExecutedBy and filingExecutedBy, each KINTSUGI or PARTNER, saying who registers with the jurisdiction and who files its returns. Both are always present and are set when the registration is created. GET /registrations accepts a managedBy filter: a comma-separated list of KINTSUGI and PARTNER that matches any value listed. While a registration is PROCESSING, VALIDATING or AWAITING_CLARIFICATION, managedBy compares against registrationExecutedBy; in every other status it compares against filingExecutedBy. A value other than KINTSUGI or PARTNER is rejected.
- Read
registrationExecutedByandfilingExecutedBywhen you need to know who handles a registration. - Send
managedByonGET /registrationsto list only the registrations a given party handles now.
2026-11-06
Breaking changesLimits who can reveal or overwrite stored registration credentials on v1RegistrationsBreaking change
Using reveal on GET /v1/registrations/{registration_id}, and sending a value for or clearing a credential that is already stored on PUT /v1/registrations/{registration_id}, now need an Owner of the organization or a Kintsugi Portfolio user who can open it. An API key counts as the user it belongs to, and a service key as the user who created it. Any other caller, and any automated assistant integration, gets 403, even when the PUT sends the value that is already stored. Before, any caller who could read or edit the registration could do both. The credentials covered are the username, password, security questions and portal access codes. A caller who can edit the registration can still fill a credential that has no stored value, except that a stored password also protects the username and security questions. Without reveal, credential fields come back masked.
- Handle
403fromGET /v1/registrations/{registration_id}when you sendreveal, and fromPUT /v1/registrations/{registration_id}when the body sets or clears a stored credential. - Use credentials that belong to an Owner of the organization, or a service key, for integrations that reveal or replace stored credentials.
- Stop sending credential fields back unchanged on
PUT /v1/registrations/{registration_id}, since that is refused when a value is stored.
Requires an Owner behind an organization API key that reads or changes registration credentialsRegistrationsBreaking change
POST /registrations/{registration_id}/credentials/reveal, PUT and PATCH /registrations/{registration_id}/credentials and POST /registrations/{registration_id}/send-password now accept an organization's own API key only while an Owner stands behind it: the user the key belongs to or, for a key with no user, the user who created it. Before, any key for the organization could. Other keys get 403. An Owner is checked against their current role, so an Owner who is demoted or removed loses access at once instead of when their sign-in token expires. When the role cannot be confirmed, the endpoints answer 503 with a Retry-After header.
- PUT/registrations/{registration_id}/credentials2026-07-21
- PATCH/registrations/{registration_id}/credentials2026-10-06
- POST/registrations/{registration_id}/credentials/reveal2026-07-21
- POST/registrations/{registration_id}/credentials/reveal2026-10-06
- POST/registrations/{registration_id}/send-password2026-07-21
- POST/registrations/{registration_id}/send-password2026-10-06
- Create the API keys that call these endpoints as an Owner of the organization, or use a service key created by an Owner.
- Handle
403from these endpoints for a key whose user is not an Owner. - On
503, wait for theRetry-Afterdelay and send the request again.
2026-11-04
Adds a list of Colorado home-rule cities for a registrationRegistrations
GET /registrations/{registration_id}/home-rule-cities returns cities, the Colorado home-rule cities that appear on committed sales on the registration's filings, as display names sorted A to Z. Sales that are archived are left out, and filings count in every status. A registration that is not Colorado sales tax, or that has no matching sales, returns an empty list. The registration is found across every organization your credential owns, so no selector header is needed. An id that does not exist or is not visible to your credential answers 404. When the lookup is briefly unavailable the endpoint answers 503 with a Retry-After header.
- Call it before you confirm a Colorado sales tax deregistration, to show the home-rule cities the registration has sales in.
- On
503, wait for theRetry-Afterdelay and send the request again.
2026-11-02
Returns a held filing to the queue after new credentials only when it is still eligibleRegistrations
Saving a new registration credential returns a held filing to the filing queue only if the organization's plan includes managed filings, the filing's jurisdiction is enabled, and its amounts have not changed since it was held. Otherwise the filing stays on hold until support moves it. The response is unchanged.
- Do not assume a new login releases a held filing; check the filing's status after you save it.
2026-10-30
Returns a held filing to the queue when you save new registration credentialsRegistrations
Saving a new value for username, password, pin, securityQuestions or jurisdictionSpecificFields on a registration can return a filing to the filing queue: one you already approved, held because the jurisdiction's portal sign-in failed, and waiting on you. Sending the stored value again does not. The new login is not tested; if it fails again, the filing goes back on hold. The response is unchanged.
- Check the new login before you save it: a filing returned to the queue goes back on hold if the sign-in fails again.
2026-10-21
Shows whether Kintsugi Mail is on file for a registrationRegistrations
A registration now returns kintsugi_mail_on_file, true once the Kintsugi Mail address is on file with the state for that registration and false otherwise, and kintsugi_mail_confirmed_at, the date it was recorded as on file, or null when it is not. Both fields are read-only: they appear on every registration response and are not accepted in a request.
- Read
kintsugi_mail_on_fileandkintsugi_mail_confirmed_atto show whether state mail reaches Kintsugi Mail for a registration.
2026-10-18
Offsets United Kingdom quarterly periods with period_end_monthRegistrations
period_end_month on POST /v1/registrations now accepts a month from 1 to 12 for United Kingdom (GB) registrations that file QUARTERLY, so a filer whose quarters do not follow the calendar can anchor each period end to that month. Before, a GB registration with period_end_month was rejected with 400. For a GB registration with any other filing frequency, a value still answers 400. null, the default, keeps the standard calendar quarters.
- Send
period_end_monthwithfiling_frequencyQUARTERLYto create aGBregistration with offset quarters.
2026-10-14
Breaking changesUpdates registration credentials with PATCH on 2026-10-06 and lets null clear a credentialRegistrationsBreaking change
On Api-Version: 2026-10-06, PATCH /registrations/{registration_id}/credentials replaces PUT, which now answers 405. A credential you leave out keeps its stored value, and null clears it. That covers username, password, pin and securityQuestions, where null or [] clears the stored set. In jurisdictionSpecificFields, a string sets cdtfaThirdPartyAccessSecurityCode or accessCode and null clears that key, while null for the whole object answers 422. PUT ignored null, so it could never clear a credential. 2026-07-21 keeps PUT with its previous behavior, where null and an empty securityQuestions list leave the stored values unchanged.
- On
Api-Version: 2026-10-06, callPATCHinstead ofPUTto save credentials. - Send
nullonly for a credential you want removed, and leave out every credential you want to keep.
2026-10-13
Breaking changesRejects null on replace-only registration fields and a lone createFilingsFromRegistrationsBreaking change
PATCH /registrations/{registration_id} now answers 422 when filingFrequency, autoRegistered, doNotFile, isPreCollecting, registrationsRegime or changeRegimeStatus is sent as null. Those fields only change when you send a value; before, a null was cleared or failed with a server error. Dates, timestamps and free-text fields still clear when sent as null. Where Kintsugi derives the first filing period, createFilingsFrom is recalculated when filingFrequency or registrationDate changes, and sending createFilingsFrom without either change now answers 400 instead of succeeding and being ignored. This applies to every Api-Version.
- Stop sending
nullforfilingFrequency,autoRegistered,doNotFile,isPreCollecting,registrationsRegimeandchangeRegimeStatus. Leave a field out to keep its value. - Do not send
createFilingsFromon its own. ChangefilingFrequencyorregistrationDateand read the recalculated value from the response.
2026-10-09
Breaking changesReplaces the Colorado retail delivery fee flag with tax_type on registration importRegistrationsBreaking change
POST /v1/registrations now takes tax_type for every jurisdiction, defaulting to SALES_TAX, and no longer reads retail_delivery_fee_obligated. A Colorado request that sets only retail_delivery_fee_obligated is created as a sales tax registration and no retail delivery fee registration opens. To import a retail delivery fee registration, send tax_type RETAIL_DELIVERY_FEE: it opens beside the organization's existing sales tax registration in that state, which must not be cancelled or deregistered, and a request without one answers 400. A tax_type the jurisdiction does not allow also answers 400. GET /v1/registrations/jurisdiction-specific-fields now returns tax_types, the values you can send for that jurisdiction: SALES_TAX is always listed, and USE_TAX, SALES_AND_USE_TAX and RETAIL_DELIVERY_FEE appear where the jurisdiction and your organization support them.
- Replace
retail_delivery_fee_obligated: truewithtax_typeRETAIL_DELIVERY_FEE, and import the state's sales tax registration first. - Read
tax_typesfromGET /v1/registrations/jurisdiction-specific-fieldsto see which values a jurisdiction accepts.
Sets California and Idaho account fields before saving an access codeRegistrations
PUT /registrations/{registration_id}/jurisdiction-fields sets the account fields a California or Idaho registration needs before PUT /registrations/{registration_id}/credentials can store its access code. Send registrationType, businessName and salesTaxId, all required and not blank. California accepts SALES_TAX or REMOTE_SELLER; Idaho accepts SALES_TAX only. An access code already stored is left unchanged. A blank sales tax id on the registration is filled from the request; one that is already set must be sent unchanged, because a different value is rejected so an imported account number is not replaced. The response is the registration. Only an owner of the organization or an API key scoped to it may call it. A registration that does not exist or belongs to an organization you cannot access answers 404; a registration outside US California and Idaho, REMOTE_SELLER on Idaho, or a changed salesTaxId answers 400; and a credential that can read the organization but not change it answers 403.
- For a registration created without these fields, call
PUT /registrations/{registration_id}/jurisdiction-fieldsfirst, then save the access code with the credentials endpoint (PATCHon 2026-10-06).
2026-10-05
Saves California and Idaho portal access codes with registration credentialsRegistrations
PUT /registrations/{registration_id}/credentials accepts jurisdictionSpecificFields: cdtfaThirdPartyAccessSecurityCode for a California registration and accessCode for an Idaho registration, named as in the credentials reveal response. Only the keys you send change, and leaving the field out or sending null keeps the saved values. The codes are stored encrypted, are never returned by this endpoint, and can be read back with POST /registrations/{registration_id}/credentials/reveal. An unsupported key or a blank value answers 422. A code for a different state than the registration's answers 400, as does a registration that does not yet have its business name, registration type and sales tax id on file.
2026-09-22
Breaking changesRequires a request body to deregister a registrationRegistrationsBreaking change
Deregistering now records when and why the registration closes. POST /v1/registrations/{registration_id}/deregister requires a JSON body with closure_date, reason and final_return_acknowledged, so a request with no body, which succeeded before, is now rejected with 422. The 2026-07-21 release changed the same way, with the fields closureDate, reason and finalReturnAcknowledged.
- Send
closure_date: the date the registration closes with the jurisdiction, as YYYY-MM-DD. Past and future dates are accepted. - Send
reason:FULL_BUSINESS_CLOSUREorCLOSING_NEXUS_IN_STATE. - Send
final_return_acknowledged: true, confirming that a final return is still owed.
Releases
2026-10-06
LatestTenanted APIConsistent country codes, empty values and status casing
2026-10-06 makes the Tenanted API more predictable to build on. Every country code is now countryCode, a value that is not set is null rather than an empty string, and status and type values are uppercase throughout. Integrations pinned to 2026-07-21 are unaffected until you choose to move, and the table below lists everything that changes when you do.
Compared with 2026-07-21
| Change | Applies to | 2026-07-21 | 2026-10-06 |
|---|---|---|---|
| Country code field | Addresses, customers, transactions, tax estimates and billing usage, in requests and responses | country | countryCode. Query parameters named country keep their name. |
| Batch address update method | /addresses/transactions | PUT | PATCH. The other method returns 405. |
| Omitted fields in a batch address update | PATCH /addresses/transactions | A field you leave out is cleared | Kept. null clears a text field, and isUnincorporated: null or an unknown countryCode returns 422. |
| Address revalidation method | /addresses/revalidation | PUT | POST. The other method returns 405. |
| Registration credentials method | /registrations/{registration_id}/credentials | PUT, where null leaves a credential unchanged | PATCH, where null clears a credential. The other method returns 405. |
| Filing submission methods | /filings/{filing_id}/submission | PUT with action | PATCH saves a draft and POST /filings/{filing_id}/mark-filed marks it filed. PUT returns 405. |
| Bunny connection refresh method | /connections/bunny/{conn_id}/refresh | PATCH | POST. The other method returns 405. |
| Default country field on connections | Connections, connection settings, PATCH /connections/{conn_id}/settings and POST /connections/apideck/{service_id}/connect | defaultCountry | defaultCountryCode |
| Incorporation country field | GET /organization-details and PATCH /organization-details | incorporationCountry | incorporationCountryCode |
| State on nexus exposure events | GET /nexus/{nexus_id}/exposure-history | state | stateCode, always present |
| State of a country-level filing | stateCode and stateName on every filing | Empty string | null |
| Organization state and country when not set | state and countryCode on organizations, and state in organization lists | Empty string, always present | null, and may be omitted |
| Exemption with no match on a certificate upload | exemptionId on missing-certificate upload results | Empty string | null |
| Missing-certificate status values | Upload, upload status and public confirm-upload results | Lowercase: processing, satisfied, rejected | Uppercase: PROCESSING, SATISFIED, REJECTED, plus PENDING on the public landing page |
| Exemption type when approving certificate imports | POST /certificate-imports/{certificate_import_id}/approve and POST /certificate-imports/bulk-approve | Any text, defaulting to customer | CUSTOMER, WHOLESALE, TRANSACTION or REVERSE_CHARGE, defaulting to CUSTOMER. Any other value returns 422. |
| Security questions in a credential reveal | fields on POST /registrations/{registration_id}/credentials/reveal | security_questions | securityQuestions |
| Line item with no product name | productName on transaction lines | null | Empty string |
| Help article label on back-filing options | GET /filings/backFilingRequest/options | Text or null | Always text |
| Job ID on bulk filing results | POST /filings/bulk/approve and POST /filings/bulk/pause | jobId, always null | Removed |
Moving an integration from 2026-07-21
- Send
Api-Version: 2026-10-06with each request you move. Requests without it keep running against 2026-07-21. - Rename
countrytocountryCodewherever you send or read an address, customer, transaction or tax estimate, and renamedefaultCountryandincorporationCountrytodefaultCountryCodeandincorporationCountryCode. - Call
PATCH /addresses/transactionsfor batch address updates, sendingnullfor any text field you want cleared, andPOST /addresses/revalidationto re-queue invalid addresses. - Treat
nullas "not set" for filing and organization locations and for an unmatchedexemptionId, and an emptyproductNameas "no product name". - Compare missing-certificate statuses in uppercase, and send
exemptionTypein uppercase when you approve certificate imports. - Read
stateCodeon nexus exposure events, requestsecurityQuestionswhen you reveal registration credentials, and stop readingjobIdon bulk filing results. - Call
PATCHto save registration credentials,PATCHandPOST /filings/{filing_id}/mark-filedin place ofPUTfor a filing submission, andPOSTto refresh a Bunny connection.
2026-07-21
Tenanted APIIntroducing the Tenanted API
A fresh foundation for building on Kintsugi. The Tenanted API is versioned by date, and you choose the release you build against. It speaks one consistent dialect from end to end: clean paths, camelCase fields, exact decimal amounts, and a single error format. And it is built for scale, with one credential reaching every organization it owns.
Compared with v1
| Topic | v1 | 2026-07-21 |
|---|---|---|
| Versioning | The /v1 path prefix | The Api-Version header, dated YYYY-MM-DD. Optional; without it, a request runs against the launch release |
| Paths | /v1/transactions | /transactions |
| Authentication | x-api-key | Api-Key. Endpoints that manage people accept a signed-in session token instead |
| Choosing an organization | x-organization-id, required on almost every request | One credential reaches every organization it owns. Narrow a request with Organization-Id, Connection-Id, or Entity-Id |
| Field names | snake_case | camelCase |
| Money and rates | Decimal strings out, numbers or strings in | Decimal strings at a fixed scale: amounts to 2 places, rates to 9 |
| Timestamps | No single documented format | RFC 3339 in UTC, always ending in Z |
| Errors | Shapes vary by endpoint | One envelope everywhere: code, message, requestId, and errors |
| Portfolio | Not available | Portfolio and Portfolio Reseller endpoints, for partner accounts |
Moving an integration from v1
- Send
Api-Versionwith every request, pinned to the release you build against (the newest is2026-10-06), so your integration stays on it until you decide to move. - Drop
/v1from your paths. - Send your key as
Api-Key, and replacex-organization-idwithOrganization-Idwherever you target one organization. - Rename fields to camelCase, and read every amount as a decimal string, never a float.
- Branch on the error
code, not the message or the HTTP status, and quoterequestIdwhen you contact support.
Creating a transaction answers 202 Accepted straight away, and tax is calculated just after. Check processingStatus before you read the tax totals.
v1
LegacyThe original Kintsugi API, versioned in the path. It is documented exactly as before, so existing integrations can keep running with confidence. New integrations should start on the newest Tenanted API release.