API changelog

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.

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.

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.

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.

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.

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.