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

Accepts a US ein that starts with 9 on PATCH /organization-details
FixOrganizations

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.

What to do
  • Stop rejecting an ein that starts with 9 before you send it.

2026-11-12

Adds bank accounts outside the US with countrySpecificFields
NewOrganizations

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.

What to do
  • To add a non-US account, send country and countrySpecificFields with the identifiers that country uses.
  • Read countrySpecificFields on each account in GET /bank-details, and use its type to tell which identifiers it holds.
  • Handle countrySpecificFields in 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-status
NewOrganizations

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.

What to do
  • Read these fields to tell a skipped step from a completed one, since the step's status field is true for both.

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

Sets an organization's debit account by id
NewOrganizations

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.

What to do
  • Call POST /bank-details/{bank_details_id}/set-primary with a user credential to change which account is the debit account.

2026-10-15

Breaking changes
Creates service API keys that belong to no user
NewOrganizations

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.

What to do
  • Send kind: "SERVICE" with an Organization-Id from a signed-in Owner or Admin to create a key that does not depend on a user.
  • Keep paging GET /api-keys until hasMore is false, and read kind to tell service keys from user keys.
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.
Makes bank details the debit account with makePrimary
NewOrganizations

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.

What to do
  • Send makePrimary: true from a signed-in Owner or Admin to set the debit account.
Checks whether an organization name is available
NewOrganizations

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.

What to do
  • Check a name before POST /organizations, and still handle 409 on create.
Returns externalId and isTest on organizations
NewOrganizations

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.

Lists a user's own organizations and pins one first
NewOrganizations

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.

What to do
  • Pass membersOnly to build an organization switcher, and selectedOrganizationId to keep the current organization on top.
Confirms an archive with the organization name
NewOrganizations

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.

What to do
  • Send the organization's name as organizationName when a person confirms the archive.

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.

2026-10-07

Updates an organization's bank details
NewOrganizations

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.

What to do
  • Send only the fields you want to change, and null for one you want to clear.

2026-10-05

Adds filing metrics to the organizations list
NewOrganizations

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.

What to do
  • Pass expand=filingMetrics to get each organization's filing status in the same call as the list.

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