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

Adds executedBy to filings and a managedBy filter to GET /filings and GET /filings/summary
NewFilings

Every filing now returns executedBy, KINTSUGI or PARTNER, saying who files the return. It is always present and is set when the filing is created, so a later change to the client's settings does not change it. GET /filings and GET /filings/summary accept a managedBy filter: a comma-separated list of KINTSUGI and PARTNER that matches any value listed. On GET /filings/summary, the counts and tax totals cover only the matching filings. A value other than KINTSUGI or PARTNER is rejected.

What to do
  • Read executedBy when you need to know who files a return.
  • Send managedBy on GET /filings or GET /filings/summary to list or count only the filings a given party files.
  • Accept executedBy in strict response models of filings.

2026-11-03

Accepts an API key that has no user on filing submission
Behavior changeFilings

Saving confirmation data as a draft, submitting it and marking a filing filed now work with an API key that is not tied to a user. These requests answered 404 for such a key before. Who may submit is unchanged: the organization's own filer, with self-managed filings enabled. A credential that carries neither a user nor a key identity is refused with 400.

What to do
  • Remove any handling that treats 404 from these calls as the sign of an API key without a user.
  • Keep sending an Organization-Id, Connection-Id or Entity-Id selector to say which organization the filing belongs to.

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

Returns issueReason on filings
NewFilings

Filings now return issueReason while status is ISSUE: INVALID_CREDENTIALS, MFA_ISSUE, NEGATIVES_ON_REPORTS, RATE_ISSUES or OTHER. It is null for any other status or when no reason is recorded. New codes may be added, so treat an unknown code like OTHER.

Refines the estimated penalties and interest on back filings
Behavior changeFilings

estimatedPenaltyInterest on BACK_FILING rows (estimated_penalty_interest on /v1) now includes flat late penalties that some states charge even when the tax is zero, so a zero-tax filing can show a value above zero. For a filed return the estimate stops at the filing date instead of continuing to accrue. null still means unknown, and 0 means the estimate found nothing owed. The field is display-only.

What to do
  • Do not treat estimatedPenaltyInterest as 0 for a zero-tax filing; read the value as returned.

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

Answers 409 while another mark-filed request is running
Behavior changeFilings

On Api-Version: 2026-10-06, POST /filings/{filing_id}/mark-filed answers 409 when another request to mark the same filing filed is still running, and nothing changes. Retry shortly: once the first request finishes, an identical repeat answers 200 with the filing.

What to do
  • Retry mark-filed after a short wait when it answers 409, and read the filing to confirm its status.
Moves a weekend or holiday payment deadline to a working day
Behavior changeFilings

For some jurisdictions, legalDeadline on GET /filings/{filing_id}/paymentInstructions is the nearest working day on or before the tax authority's deadline when that deadline falls on a weekend or bank holiday. Which holidays count depends on the jurisdiction. Other jurisdictions keep the authority's date. For those jurisdictions, the default deadline, the date to pay by, also counts working days.

What to do
  • Show legalDeadline and deadline as returned, without recomputing them from the filing's due date.

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

Recalculates a filing's amounts on request
NewFilings

POST /filings/{filing_id}/recalculate queues a recalculation of a filing's amounts from its transactions and answers 202 with filingId, countryCode and status QUEUED. The recalculation runs in the background, so read the filing again for the new amounts. Only US and Canadian filings that are not in FILING, SUBMITTED or FILED status can be recalculated; others answer 400 with code invalid_request. It is available only for organizations that file their own returns, to their Owners and Admins, their API keys and the portfolio that manages them; other callers receive 403. A filing that does not exist or belongs to an organization you cannot access answers 404. Send an Organization-Id, Connection-Id or Entity-Id selector to say which organization the filing belongs to.

What to do
  • After the 202, read GET /filings/{filing_id} to see the recalculated amounts.

2026-10-06

Returns a US filing's tax liability by local jurisdiction
NewFilings

GET /filings/{filing_id}/enhanced-data returns a US filing's actual tax liability: summary totals, jurisdictionBreakdown per local jurisdiction, deductions and exemptions, refunds, and state-specific breakdowns such as county groupings and use tax where the state reports them. Send the filing's two-letter state as jurisdiction. The data is built on request. When it is ready the response is 200 with status DONE and the data in data; while it builds the response is 202 with IN_PROGRESS, so poll until it is DONE. A failed build answers 200 with FAILED and is not retried until you ask. A filing with no transactions answers DONE with data set to null. POST /filings/{filing_id}/enhanced-data/rebuild starts a fresh build even when one is stored and answers 202, or reports the build already running. Rebuilding is open to the same callers as PUT /filings/{filing_id}/submission, for organizations that file their own returns; others receive 403. It allows 10 requests a minute per portfolio, or per organization outside a portfolio, then answers 429. Both endpoints answer 404 for a filing you cannot access, 400 with code invalid_request when jurisdiction does not match the filing, and 400 with the new code unsupported_jurisdiction for a state without this data.

What to do
  • Poll the GET endpoint while it answers 202, and call rebuild after a FAILED result.
  • If your client accepts only known error code values, add unsupported_jurisdiction.

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.
Records the confirmation and documents for a return you file yourself
NewFilings

Two endpoints let an organization that files its own returns record each one in Kintsugi. PUT /filings/{filing_id}/submission takes an action of save_draft, which saves the confirmation details and keeps the filing in FILING, or mark_filed, which saves them and marks the filing FILED. Its optional fields are returnConfirmationId, paymentConfirmationId, amountAdjusted, amountFees, amountPenalties and amountDiscounts, with amounts as decimal strings; a field you leave out is unchanged and a field sent as null is cleared. It returns the updated filing, or 409 when the filing is not in FILING. PUT /filings/{filing_id}/artifacts/{artifact_type} stores the RETURN or PAYMENT confirmation as a PDF of up to 10 MB, sent in the file part of a multipart/form-data body, replacing any document already stored for that type. It answers 409 unless the filing is FILING or FILED, 413 for a larger file and 422 for a file that is not a PDF. Both endpoints are available only for organizations set up to file their own returns, to their Owners and Admins, their API keys and the portfolio that manages them; other callers receive 403.

What to do
  • Upload the return and payment confirmations while the filing is in FILING, then call the submission endpoint with action: "mark_filed".
  • Download a stored document with GET /attachments/{attachment_id}/download.

2026-10-02

Checks the length of a pause reason before pausing
FixFilings

A pauseReason is saved in a note on the filing, and the note, including a short label Kintsugi adds, holds up to 500 characters. A longer reason used to fail with a server error, sometimes after the filing was already paused. It now answers 400 with code invalid_request before anything changes, and POST /filings/bulk/pause refuses the whole request.

What to do
  • Keep pauseReason comfortably under 500 characters.

2026-09-30

Requests back filings for past periods through v1
NewFilings

Three v1 endpoints, now documented, let you ask Kintsugi to file returns for periods before your regular filing schedule began. GET /v1/filings/back-filing-request/options lists each active US registration with the periods it can request: periods that have ended, start on or after the registration's tax collection start, end before its first regular filing period, and are not already covered by a filing. Each period has a start_date, an end_date and a label, and each registration a remittance_tag (Paid with return, State bills you later or null) saying how the state collects penalties and interest. POST /v1/filings/back-filing-request takes requests, each a registration_id with its periods, and optional notes. It creates one BACK_FILING filing with status UNFILED per period and returns them in created_filings, with their count in total_created, and 200. Every period is checked before anything is created, so one invalid period refuses the whole request with 400. An unknown registration_id answers 404, an organization without a payment method on file receives 402, and an organization without back filing available receives 404 from both request endpoints. Nothing is filed until each filing is approved with the current terms from GET /v1/filings/back-filing-terms/current, which returns their id, version and text.

What to do
  • Request only the start_date and end_date pairs that the options endpoint lists for each registration.
  • Show the current terms to the person approving, then approve each filing with PUT /v1/filings/{filing_id}/approve, sending the terms id as back_filing_terms_id. Missing or outdated terms answer 400.

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