KintsugiKintsugi
API reference / Changelog

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-02

Breaking changes
Answers 409 when you approve a filing that is being recalculatedBreaking change
Breaking changeFilings

Approving a filing now answers 409 while the filing is being recalculated, instead of approving it on amounts that may be out of date. On the Tenanted releases the error code is recalculation_in_progress, a new value of the error code enum. The recalculation finishes within moments, so the same request succeeds when you retry it.

What to do
  • Handle 409 on an approval by waiting a few seconds and sending the same request again.
  • On the Tenanted releases, tell this 409 apart from the duplicate-period 409 by its code, and treat an unknown code as a failure rather than a retry.

2026-10-27

Breaking changes
Removes the filing enhanced data endpointsBreaking change
Breaking changeFilings

GET /filings/{filing_id}/enhanced-data and POST /filings/{filing_id}/enhanced-data/rebuild are no longer available on any Tenanted release, including integrations pinned to 2026-07-21 or 2026-10-06. Requests to them answer 404. Read a filing's totals from GET /filings/{filing_id}.

What to do
  • Stop calling GET /filings/{filing_id}/enhanced-data and POST /filings/{filing_id}/enhanced-data/rebuild.
  • Read filing amounts from GET /filings/{filing_id} instead.

2026-10-20

Breaking changes
Shows Kintsugi's own task files only as payment receiptsBreaking change
Breaking changeFilings

An attachment Kintsugi adds while working on your account is now visible to you only when it is the state's payment receipt for a balance that is paid. GET /attachments leaves every other such file out. GET /attachments/{attachment_id} and GET /attachments/{attachment_id}/download answer 404 for it, the same answer as an id that does not exist. Files you upload yourself are unchanged.

What to do
  • Treat 404 from the attachment endpoints as final for a file that is not shared with you, and do not retry it.
  • Read payment receipts from paymentConfirmationAttachmentIds on a PAID proposal outcome from GET /proposals.

2026-10-14

Breaking changes
Splits the filing submission into a draft PATCH and a mark-filed POST on 2026-10-06Breaking change
Breaking changeFilings

On Api-Version: 2026-10-06, PUT /filings/{filing_id}/submission no longer exists and answers 405. PATCH /filings/{filing_id}/submission saves the confirmation fields as a draft and leaves the filing status unchanged. POST /filings/{filing_id}/mark-filed stores any confirmation fields you send and marks the filing FILED. Neither takes action. Repeating a mark-filed request for a filing already filed with the same values answers 200 with the filing and does nothing more, where the PUT answered 409. Both new endpoints answer 409 when the filing is not in FILING or SUBMITTED status. 2026-07-21 keeps the PUT with action. On every Api-Version, amountAdjusted, amountFees, amountPenalties and amountDiscounts now answer 422 when sent as null; before, null was stored as 0.00. Send an amount, including "0.00", or leave it out. returnConfirmationId and paymentConfirmationId still clear when sent as null.

What to do
  • On Api-Version: 2026-10-06, call PATCH /filings/{filing_id}/submission to save a draft and POST /filings/{filing_id}/mark-filed to mark the filing filed.
  • Retry mark-filed after a timeout without checking the filing first: an identical repeat answers 200.
  • Stop sending null for an amount. Send "0.00" for zero, or leave the amount out.

2026-10-08

Breaking changes
Removes retail delivery fee fields from v1 filings and registrationsBreaking change
Breaking changeFilings

A retail delivery fee is now its own registration and its own filing, so v1 no longer returns the fields that flagged it on a sales tax record. is_rdf is gone from filing responses, and retail_delivery_fee_obligated and retail_delivery_fee_effective_from are gone from registration responses. Read tax_type instead: a retail delivery fee registration or filing has tax_type RETAIL_DELIVERY_FEE, and it appears beside the state's sales tax record rather than inside it. On POST /v1/registrations for Colorado, retail_delivery_fee_obligated still asks for a retail delivery fee registration, opened beside the sales registration, but the value is no longer stored or returned on the sales registration. It is available to paid organizations with this feature enabled; for any other organization, a request that sets it answers 400.

What to do
  • Stop reading is_rdf, retail_delivery_fee_obligated and retail_delivery_fee_effective_from from v1 responses.
  • Identify a retail delivery fee filing or registration by tax_type RETAIL_DELIVERY_FEE.

2026-10-05

Breaking changes
Limits pausing a filing to the window before its due dateBreaking change
Breaking changeFilings

Pausing a filing now follows the same window as the Kintsugi app. After the 15th of the month a filing is due, it can no longer be paused with any pauseIntent, including assistance and skip, which were accepted before. A review pause also needs a pausedUntilDate from today through the 15th of the due month; a date in the past, accepted before, is now refused. A date that is still today anywhere in the world counts as today. POST /filings/{filing_id}/pause answers a refused pause with 400 and code invalid_request, and POST /filings/bulk/pause still answers 200, listing each refused filing in failed.

What to do
  • Pause a filing no later than the 15th of the month it is due.
  • For a review pause, send a pausedUntilDate no earlier than today and no later than the 15th of the due month.
  • After a bulk pause, check failed for filings that were not paused.

Releases

2026-10-06

LatestTenanted API

Consistent 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

ChangeApplies to2026-07-212026-10-06
Country code fieldAddresses, customers, transactions, tax estimates and billing usage, in requests and responsescountrycountryCode. Query parameters named country keep their name.
Batch address update method/addresses/transactionsPUTPATCH. The other method returns 405.
Omitted fields in a batch address updatePATCH /addresses/transactionsA field you leave out is clearedKept. null clears a text field, and isUnincorporated: null or an unknown countryCode returns 422.
Address revalidation method/addresses/revalidationPUTPOST. The other method returns 405.
Registration credentials method/registrations/{registration_id}/credentialsPUT, where null leaves a credential unchangedPATCH, where null clears a credential. The other method returns 405.
Filing submission methods/filings/{filing_id}/submissionPUT with actionPATCH saves a draft and POST /filings/{filing_id}/mark-filed marks it filed. PUT returns 405.
Bunny connection refresh method/connections/bunny/{conn_id}/refreshPATCHPOST. The other method returns 405.
Default country field on connectionsConnections, connection settings, PATCH /connections/{conn_id}/settings and POST /connections/apideck/{service_id}/connectdefaultCountrydefaultCountryCode
Incorporation country fieldGET /organization-details and PATCH /organization-detailsincorporationCountryincorporationCountryCode
State on nexus exposure eventsGET /nexus/{nexus_id}/exposure-historystatestateCode, always present
State of a country-level filingstateCode and stateName on every filingEmpty stringnull
Organization state and country when not setstate and countryCode on organizations, and state in organization listsEmpty string, always presentnull, and may be omitted
Exemption with no match on a certificate uploadexemptionId on missing-certificate upload resultsEmpty stringnull
Missing-certificate status valuesUpload, upload status and public confirm-upload resultsLowercase: processing, satisfied, rejectedUppercase: PROCESSING, SATISFIED, REJECTED, plus PENDING on the public landing page
Exemption type when approving certificate importsPOST /certificate-imports/{certificate_import_id}/approve and POST /certificate-imports/bulk-approveAny text, defaulting to customerCUSTOMER, WHOLESALE, TRANSACTION or REVERSE_CHARGE, defaulting to CUSTOMER. Any other value returns 422.
Security questions in a credential revealfields on POST /registrations/{registration_id}/credentials/revealsecurity_questionssecurityQuestions
Line item with no product nameproductName on transaction linesnullEmpty string
Help article label on back-filing optionsGET /filings/backFilingRequest/optionsText or nullAlways text
Job ID on bulk filing resultsPOST /filings/bulk/approve and POST /filings/bulk/pausejobId, always nullRemoved

Moving an integration from 2026-07-21

  1. Send Api-Version: 2026-10-06 with each request you move. Requests without it keep running against 2026-07-21.
  2. Rename country to countryCode wherever you send or read an address, customer, transaction or tax estimate, and rename defaultCountry and incorporationCountry to defaultCountryCode and incorporationCountryCode.
  3. Call PATCH /addresses/transactions for batch address updates, sending null for any text field you want cleared, and POST /addresses/revalidation to re-queue invalid addresses.
  4. Treat null as "not set" for filing and organization locations and for an unmatched exemptionId, and an empty productName as "no product name".
  5. Compare missing-certificate statuses in uppercase, and send exemptionType in uppercase when you approve certificate imports.
  6. Read stateCode on nexus exposure events, request securityQuestions when you reveal registration credentials, and stop reading jobId on bulk filing results.
  7. Call PATCH to save registration credentials, PATCH and POST /filings/{filing_id}/mark-filed in place of PUT for a filing submission, and POST to refresh a Bunny connection.

2026-07-21

Tenanted API

Introducing 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

Topicv12026-07-21
VersioningThe /v1 path prefixThe Api-Version header, dated YYYY-MM-DD. Optional; without it, a request runs against the launch release
Paths/v1/transactions/transactions
Authenticationx-api-keyApi-Key. Endpoints that manage people accept a signed-in session token instead
Choosing an organizationx-organization-id, required on almost every requestOne credential reaches every organization it owns. Narrow a request with Organization-Id, Connection-Id, or Entity-Id
Field namessnake_casecamelCase
Money and ratesDecimal strings out, numbers or strings inDecimal strings at a fixed scale: amounts to 2 places, rates to 9
TimestampsNo single documented formatRFC 3339 in UTC, always ending in Z
ErrorsShapes vary by endpointOne envelope everywhere: code, message, requestId, and errors
PortfolioNot availablePortfolio and Portfolio Reseller endpoints, for partner accounts

Moving an integration from v1

  1. Send Api-Version with every request, pinned to the release you build against (the newest is 2026-10-06), so your integration stays on it until you decide to move.
  2. Drop /v1 from your paths.
  3. Send your key as Api-Key, and replace x-organization-id with Organization-Id wherever you target one organization.
  4. Rename fields to camelCase, and read every amount as a decimal string, never a float.
  5. Branch on the error code, not the message or the HTTP status, and quote requestId when 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

Legacy

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

Kintsugi API Changelog