KintsugiKintsugi
API reference / Changelog / 2026

API changelog: 2026

Every change to the Kintsugi API in 2026, newest first. For the latest changes and every release, see the API changelog.

2026-11-17

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.
Kintsugi API Changelog: 2026