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-10-29

Breaking changes
Validates US routing and account numbers on bank account writesBreaking change
Breaking changeOrganizations

POST /bank-details, PATCH /bank-details/{bank_details_id} and PATCH /bank-details now check a US routing number or account number you add or change. A routing number must be 9 digits with a valid checksum, and an account number 4 to 17 digits. Spaces and dashes are removed before the check, and the digits are stored. A value that fails answers 422 with the field named in errors; it was stored as sent before. A number identical to the one already stored is not checked again, so saving other fields does not fail on an older value.

What to do
  • Send a routing number of 9 digits that passes the ABA checksum, and an account number of 4 to 17 digits.
  • Handle a 422 from these endpoints by showing the message for the field named in errors.

2026-10-28

Breaking changes
Sets the debit account with isPrimary on PATCH /bank-details/{bank_details_id}Breaking change
Breaking changeOrganizations

POST /bank-details/{bank_details_id}/set-primary is removed on every Tenanted release, including integrations pinned to 2026-07-21 or 2026-10-06. Send isPrimary: true on PATCH /bank-details/{bank_details_id} to make that account the organization's debit account, alone or together with field updates. false or omitted leaves the debit account unchanged. Unlike set-primary, this request accepts an API key as well as an Owner or Admin user credential. It still answers 404 when the organization has no account with that id. makePrimary on PATCH /bank-details is unchanged.

What to do
  • Stop calling POST /bank-details/{bank_details_id}/set-primary.
  • Call PATCH /bank-details/{bank_details_id} with isPrimary: true to change which account is the debit account.
Validates a US ein on PATCH /organization-detailsBreaking change
Breaking changeOrganizations

When the organization is incorporated in the US, ein on PATCH /organization-details must be 9 digits, with or without the dash (XX-XXXXXXX). The value is stored with the dash. A value that is malformed, starts with 9 or is all zeros answers 400; it was stored as sent before. An ein identical to the stored value is not checked again, so saving unrelated fields does not fail on an older value. Changing the incorporation country to the US checks the stored value. Outside the US, ein stays a free-form business ID. Blank ein on a US organization is ignored, and null for taxId removes the tax id as before.

What to do
  • Send a US ein as nine digits or XX-XXXXXXX, and never one that starts with 9 or is all zeros.
  • Handle a 400 from PATCH /organization-details by asking the user to correct the number.

2026-10-15

Breaking changes
Limits how fast an organization can send invitationsBreaking change
Breaking changeOrganizations

POST /users/invites now counts against a limit per organization, which it shares with the legacy invite endpoint. A request over the limit answers 429 with the error code rate_limited and a Retry-After header that gives the seconds to wait. Before, there was no limit. Every request that passes validation counts, including one that repeats an existing invitation or is refused for its role. This applies to every Api-Version.

What to do
  • Wait the number of seconds in Retry-After before retrying a 429.
  • Space out bulk invitations, and do not retry a refused invitation in a loop.

2026-10-14

Breaking changes
Rejects null on organization settings, exemption reminder settings and user role updatesBreaking change
Breaking changeOrganizations

PATCH /organization-settings and PATCH /organization-settings/exemption-reminders now answer 422 when any field is sent as null; before, they answered 200 and changed nothing. PATCH /users/{user_id} answers 422 when additionalRoles is null; before, null was treated as omitted and kept the member's additional roles. A field you leave out is unchanged, false is written as sent, and additionalRoles: [] still clears the additional roles. This applies to every Api-Version.

What to do
  • Leave out a setting you do not want to change instead of sending null.
  • Send additionalRoles: [] to remove a member's additional roles, and leave the field out to keep them.
Answers 200 with the stored record to an empty bank details updateBreaking change
Breaking changeOrganizations

PATCH /bank-details with an empty body now changes nothing and answers 200 with the stored record, or null when none exists. Before, it answered 400. It does not create a record. A client that reads the response must handle null. This applies to every Api-Version.

What to do
  • Handle a null response body, and do not rely on 400 to detect an update with no fields.

2026-10-09

Breaking changes
Updates organization details one field at a timeBreaking change
Breaking changeOrganizations

PATCH /organization-details now changes only the fields you send. Before, a section you sent replaced the whole section, so its identity fields were required and an omitted optional such as address2 was cleared. Now an omitted section or field is left unchanged, and a sent field is written as sent, including an empty string, 0 and false. null clears a field whose description says it accepts null, which now includes taxId, homeStateRegistration, naics, businessPhone, businessEmail and businessFiscalYearEnd, so a null that was ignored before now removes the stored value. null on any other field answers 422. Sending taxId needs an incorporation country, sent in the same request or already stored, or the request answers 400. This applies to every Api-Version.

What to do
  • Send only the fields you want to change. To keep a value, leave the field out.
  • Stop sending null to mean "leave unchanged": it now clears the field, or answers 422 where the field cannot be cleared.
  • Set the incorporation country before, or with, taxId.

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