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-14
Accepts a US ein that starts with 9 on PATCH /organization-detailsOrganizations
A US ein that starts with 9 is now accepted on PATCH /organization-details and stored in the XX-XXXXXXX form. The other checks are unchanged: an ein must be nine digits, with or without the dash, and an all-zero value answers 400.
- Stop rejecting an
einthat starts with9before you send it.
2026-11-12
Adds bank accounts outside the US with countrySpecificFieldsOrganizations
POST /bank-details now accepts an account in Canada, the United Kingdom, Australia, New Zealand, Mexico and the EU, as well as the US. For these countries, send the account's identifiers in countrySpecificFields instead of accountNumber and routingNumber: for example institutionNumber, transitNumber and accountNumber for Canada, sortCode or iban and bic for the United Kingdom and the EU, bsb for Australia, and clabe for Mexico. countrySpecificFields is required for these countries and not accepted for the US. A country that debits under a mandate also needs mandateCopyId, the id of the latest mandate text the user accepted; any other country refuses it with 400 and code bank_mandate_not_required. Only a user's own sign-in can send mandateCopyId. PATCH /bank-details/{bank_details_id} keeps the account's country and replaces all stored identifiers when you send countrySpecificFields, so send every field the country needs. Responses return countrySpecificFields as an object whose type is CA, GB, AU, NZ, MX, SEPA or US, with each identifier masked to its last four characters in a field ending Last4, or null when none are captured yet.
- To add a non-US account, send
countryandcountrySpecificFieldswith the identifiers that country uses. - Read
countrySpecificFieldson each account inGET /bank-details, and use itstypeto tell which identifiers it holds. - Handle
countrySpecificFieldsin strict response models: it is an object whose fields depend on the country.
2026-11-11
Returns how each setup step finished on GET /onboarding/steps-statusOrganizations
GET /onboarding/steps-status now returns primaryProductsCompletedVia, planStepCompletedVia, mailStepCompletedVia, ecmStepCompletedVia and analyticsStepCompletedVia. Each is done when the step was completed, skipped when it was skipped, and null when the step is not yet complete or does not apply to the organization's plan. A step that was skipped and later completed reads done.
- Read these fields to tell a skipped step from a completed one, since the step's status field is
truefor both.
2026-10-29
Breaking changesValidates US routing and account numbers on bank account writesOrganizationsBreaking change
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.
- Send a routing number of 9 digits that passes the ABA checksum, and an account number of 4 to 17 digits.
- Handle a
422from these endpoints by showing the message for the field named inerrors.
2026-10-28
Breaking changesSets the debit account with isPrimary on PATCH /bank-details/{bank_details_id}OrganizationsBreaking change
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.
- Stop calling
POST /bank-details/{bank_details_id}/set-primary. - Call
PATCH /bank-details/{bank_details_id}withisPrimary: trueto change which account is the debit account.
Validates a US ein on PATCH /organization-detailsOrganizationsBreaking change
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.
- Send a US
einas nine digits orXX-XXXXXXX, and never one that starts with9or is all zeros. - Handle a
400fromPATCH /organization-detailsby asking the user to correct the number.
2026-10-16
Sets an organization's debit account by idOrganizations
POST /bank-details/{bank_details_id}/set-primary makes the named bank account the organization's debit account, so an organization with several accounts can switch between them. It returns the account with the account and routing numbers masked to their last four characters. It needs a signed-in Owner or Admin of the organization selected by Organization-Id, Connection-Id or Entity-Id; an API key is refused. It answers 404 when the organization has no bank account with that id. makePrimary on PATCH /bank-details still applies only to the account that request updates.
- Call
POST /bank-details/{bank_details_id}/set-primarywith a user credential to change which account is the debit account.
2026-10-15
Breaking changesCreates service API keys that belong to no userOrganizations
POST /api-keys accepts kind: USER, the default, creates a key tied to you, and SERVICE creates a key with no user, for server-to-server use. A service key keeps working when the person who created it leaves, and it does not count against the per-user key limit. Only a signed-in Owner or Admin can create one; an Api-Key cannot, and the request needs an Organization-Id. An organization can hold at most 10 active service keys, and the 11th answers 409. On this API a service key can authenticate only to revoke itself: DELETE /api-keys/{api_key_id} with its own token as the Api-Key and its own id in the path answers success, and any other id answers 401. Every key now returns kind, and GET /api-keys for an organization includes its service keys. A page can hold fewer keys than limit, even none, while hasMore is true, so follow nextCursor until it is false.
- Send
kind: "SERVICE"with anOrganization-Idfrom a signed-in Owner or Admin to create a key that does not depend on a user. - Keep paging
GET /api-keysuntilhasMoreisfalse, and readkindto tell service keys from user keys.
Limits how fast an organization can send invitationsOrganizationsBreaking change
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.
- Wait the number of seconds in
Retry-Afterbefore retrying a429. - Space out bulk invitations, and do not retry a refused invitation in a loop.
2026-10-14
Breaking changesRejects null on organization settings, exemption reminder settings and user role updatesOrganizationsBreaking change
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.
- 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 updateOrganizationsBreaking change
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.
- Handle a
nullresponse body, and do not rely on400to detect an update with no fields.
Makes bank details the debit account with makePrimaryOrganizations
PATCH /bank-details accepts makePrimary, a boolean that defaults to false. When true, the account becomes the organization's debit account. It can be sent with other fields or on its own: on its own it applies to the stored record and answers 404 when no bank details exist. Only an Owner or Admin signed in as a user may send true; an API key answers 403, while an API key can still update the other fields.
- Send
makePrimary: truefrom a signed-in Owner or Admin to set the debit account.
Checks whether an organization name is availableOrganizations
GET /organizations/name-availability?name= answers { "available": true } when no organization has that name. The comparison ignores letter case and surrounding spaces and covers every organization, not only the ones your credential can access, so any authenticated credential learns whether a name is taken, as POST /organizations already does with 409. name is required, 1 to 255 characters. A name that is available now can still be taken by the time you create the organization.
- Check a name before
POST /organizations, and still handle409on create.
Returns externalId and isTest on organizationsOrganizations
Organizations now include externalId, the organization's identifier in the sign-in service, which you use to request a token scoped to it, and isTest, whether it is a test organization. Both are always present, on each row of GET /organizations and on the organization returned by GET /organizations/{org_id}, PATCH /organizations/{org_id}, POST /organizations and POST /organizations/{org_id}/archive. Only credentials that can read the organization see them.
- GET/organizations2026-07-21
- GET/organizations2026-10-06
- GET/organizations/{org_id}2026-07-21
- GET/organizations/{org_id}2026-10-06
- PATCH/organizations/{org_id}2026-07-21
- PATCH/organizations/{org_id}2026-10-06
- POST/organizations2026-07-21
- POST/organizations2026-10-06
- POST/organizations/{org_id}/archive2026-07-21
- POST/organizations/{org_id}/archive2026-10-06
Lists a user's own organizations and pins one firstOrganizations
GET /organizations accepts membersOnly for a signed-in user. true lists only the organizations the user belongs to directly. false lists those plus every organization the user reaches through a portfolio, without duplicates. Without it, a user who belongs to several organizations still answers 400 unless a selector header narrows the request. It is not available to an API key, which answers 400. selectedOrganizationId shows one organization first, ahead of the name order, when it is in the list and matches search and status. The first page then holds limit organizations plus that one, and later pages never repeat it. An id you cannot access is ignored.
- Pass
membersOnlyto build an organization switcher, andselectedOrganizationIdto keep the current organization on top.
Confirms an archive with the organization nameOrganizations
POST /organizations/{org_id}/archive accepts an optional organizationName, up to 255 characters. When you send it, it must match the organization's current name, ignoring letter case and surrounding spaces; otherwise the request answers 400 and archives nothing. Leave it out to archive without confirmation, as before.
- Send the organization's name as
organizationNamewhen a person confirms the archive.
2026-10-09
Breaking changesUpdates organization details one field at a timeOrganizationsBreaking change
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.
- Send only the fields you want to change. To keep a value, leave the field out.
- Stop sending
nullto mean "leave unchanged": it now clears the field, or answers422where the field cannot be cleared. - Set the incorporation country before, or with,
taxId.
2026-10-07
Updates an organization's bank detailsOrganizations
PATCH /bank-details changes bankName, accountNumber, accountType (CHECKING or SAVINGS), accountHolderName and routingNumber. A field you leave out keeps its stored value, a field sent as null is cleared, and the record is created when none exists. Text values are trimmed and cannot be blank, bankName holds up to 100 characters, and an unknown field is refused. The response never returns full numbers: accountNumberLast4 and routingNumberLast4 hold the last four characters, or **** for a number of four characters or fewer, and are null when not captured. A user must be an Owner or Admin of the organization; an API key that reaches the organization is accepted. Select the organization with Organization-Id, Connection-Id or Entity-Id.
- Send only the fields you want to change, and
nullfor one you want to clear.
2026-10-05
Adds filing metrics to the organizations listOrganizations
GET /organizations accepts expand=filingMetrics, which adds a filingMetrics object to each organization: totalFilings, filed, pendingApproval (unfiled returns not yet past their due date), overdue (unfiled returns past their due date) and liabilityByCurrency, one { currency, amount } entry per currency. Returns marked do not file are left out of pendingApproval and overdue. Currencies are listed in code order, with returns that have no currency yet last as currency: null, and amounts are decimal strings that are never converted between currencies. An organization with no returns gets zero counts and an empty liabilityByCurrency. Without expand the response is unchanged, an unknown expand value answers 422, and a cursor stays valid with or without expand.
- Pass
expand=filingMetricsto get each organization's filing status in the same call as the list.
Releases
2026-10-06
LatestTenanted APIConsistent 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
| Change | Applies to | 2026-07-21 | 2026-10-06 |
|---|---|---|---|
| Country code field | Addresses, customers, transactions, tax estimates and billing usage, in requests and responses | country | countryCode. Query parameters named country keep their name. |
| Batch address update method | /addresses/transactions | PUT | PATCH. The other method returns 405. |
| Omitted fields in a batch address update | PATCH /addresses/transactions | A field you leave out is cleared | Kept. null clears a text field, and isUnincorporated: null or an unknown countryCode returns 422. |
| Address revalidation method | /addresses/revalidation | PUT | POST. The other method returns 405. |
| Registration credentials method | /registrations/{registration_id}/credentials | PUT, where null leaves a credential unchanged | PATCH, where null clears a credential. The other method returns 405. |
| Filing submission methods | /filings/{filing_id}/submission | PUT with action | PATCH saves a draft and POST /filings/{filing_id}/mark-filed marks it filed. PUT returns 405. |
| Bunny connection refresh method | /connections/bunny/{conn_id}/refresh | PATCH | POST. The other method returns 405. |
| Default country field on connections | Connections, connection settings, PATCH /connections/{conn_id}/settings and POST /connections/apideck/{service_id}/connect | defaultCountry | defaultCountryCode |
| Incorporation country field | GET /organization-details and PATCH /organization-details | incorporationCountry | incorporationCountryCode |
| State on nexus exposure events | GET /nexus/{nexus_id}/exposure-history | state | stateCode, always present |
| State of a country-level filing | stateCode and stateName on every filing | Empty string | null |
| Organization state and country when not set | state and countryCode on organizations, and state in organization lists | Empty string, always present | null, and may be omitted |
| Exemption with no match on a certificate upload | exemptionId on missing-certificate upload results | Empty string | null |
| Missing-certificate status values | Upload, upload status and public confirm-upload results | Lowercase: processing, satisfied, rejected | Uppercase: PROCESSING, SATISFIED, REJECTED, plus PENDING on the public landing page |
| Exemption type when approving certificate imports | POST /certificate-imports/{certificate_import_id}/approve and POST /certificate-imports/bulk-approve | Any text, defaulting to customer | CUSTOMER, WHOLESALE, TRANSACTION or REVERSE_CHARGE, defaulting to CUSTOMER. Any other value returns 422. |
| Security questions in a credential reveal | fields on POST /registrations/{registration_id}/credentials/reveal | security_questions | securityQuestions |
| Line item with no product name | productName on transaction lines | null | Empty string |
| Help article label on back-filing options | GET /filings/backFilingRequest/options | Text or null | Always text |
| Job ID on bulk filing results | POST /filings/bulk/approve and POST /filings/bulk/pause | jobId, always null | Removed |
Moving an integration from 2026-07-21
- Send
Api-Version: 2026-10-06with each request you move. Requests without it keep running against 2026-07-21. - Rename
countrytocountryCodewherever you send or read an address, customer, transaction or tax estimate, and renamedefaultCountryandincorporationCountrytodefaultCountryCodeandincorporationCountryCode. - Call
PATCH /addresses/transactionsfor batch address updates, sendingnullfor any text field you want cleared, andPOST /addresses/revalidationto re-queue invalid addresses. - Treat
nullas "not set" for filing and organization locations and for an unmatchedexemptionId, and an emptyproductNameas "no product name". - Compare missing-certificate statuses in uppercase, and send
exemptionTypein uppercase when you approve certificate imports. - Read
stateCodeon nexus exposure events, requestsecurityQuestionswhen you reveal registration credentials, and stop readingjobIdon bulk filing results. - Call
PATCHto save registration credentials,PATCHandPOST /filings/{filing_id}/mark-filedin place ofPUTfor a filing submission, andPOSTto refresh a Bunny connection.
2026-07-21
Tenanted APIIntroducing 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
| Topic | v1 | 2026-07-21 |
|---|---|---|
| Versioning | The /v1 path prefix | The Api-Version header, dated YYYY-MM-DD. Optional; without it, a request runs against the launch release |
| Paths | /v1/transactions | /transactions |
| Authentication | x-api-key | Api-Key. Endpoints that manage people accept a signed-in session token instead |
| Choosing an organization | x-organization-id, required on almost every request | One credential reaches every organization it owns. Narrow a request with Organization-Id, Connection-Id, or Entity-Id |
| Field names | snake_case | camelCase |
| Money and rates | Decimal strings out, numbers or strings in | Decimal strings at a fixed scale: amounts to 2 places, rates to 9 |
| Timestamps | No single documented format | RFC 3339 in UTC, always ending in Z |
| Errors | Shapes vary by endpoint | One envelope everywhere: code, message, requestId, and errors |
| Portfolio | Not available | Portfolio and Portfolio Reseller endpoints, for partner accounts |
Moving an integration from v1
- Send
Api-Versionwith every request, pinned to the release you build against (the newest is2026-10-06), so your integration stays on it until you decide to move. - Drop
/v1from your paths. - Send your key as
Api-Key, and replacex-organization-idwithOrganization-Idwherever you target one organization. - Rename fields to camelCase, and read every amount as a decimal string, never a float.
- Branch on the error
code, not the message or the HTTP status, and quoterequestIdwhen 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
LegacyThe 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.