KintsugiKintsugi

Create registration

POST/v1/registrations

The Create Registration API allows users to create a new registration for tracking and managing tax filings efficiently across multiple jurisdictions.

Authorization

x-api-keystringRequired

Your secret API key. Include it with every request.

Body

registration_import_typestring

Specifies this is a regular jurisdiction registration import.

registration_datestring

The date when the registration was created. Format: YYYY-MM-DD.

registration_emailstring

Email address associated with the registration.

registration_requestedstring

Timestamp when the registration was requested.

registration_completedstring

Timestamp when the registration was completed.

deregistration_requestedstring

Timestamp when deregistration was requested.

deregistration_completedstring

Timestamp when the deregistration was completed.

auto_registeredboolean

Indicates whether the registration was completed automatically.

do_not_fileboolean

If true, do not file for this registration (treated as False by default).

registrations_regimeRegistrationsRegimeEnum

The tax registration regime (e.g., STANDARD, SIMPLIFIED).

Available options:STANDARDSIMPLIFIED
change_regime_statusChangeRegimeStatusEnum
Available options:REQUESTEDAPPROVEDDONEACKNOWLEDGED
is_pre_collectingboolean

Set true to mark the organization as collecting tax in this jurisdiction ahead of registration details, instead of a normal import. Opens the registration in PROCESSING; filing frequency and credentials are not required.

country_codeCountryCodeEnumRequired

The country code (ISO 3166-1 alpha-2 format) where the registration applies.

Available options:AFAXALDZASADAOAIAQAGARAMAWAUATAZBSBHBDBBBYBEBZBJBMBTBOBQBABWBVBRIOBNBGBFBICVKHCMCAKYCFTDCLCNCXCCCOKMCGCDCKCRHRCUCWCYCZDKDJDMDOECEGSVGQEREESZETFKFOFJFIFRGFPFTFGAGMGEDEGHGIGRGLGDGPGUGTGGGNGWGYHTHMVAHNHKHUISINIDIRIQIEIMILITCIJMJPJEJOKZKEKIKPKRKWKGLALVLBLSLRLYLILTLUMOMGMWMYMVMLMTMHMQMRMUYTMXFMMDMCMNMEMSMAMZMMNANRNPNLNCNZNINENGNUNFMKMPNOOMPKPWPSPAPGPYPEPHPNPLPTPRQARERORURWBLSHKNLCMFPMVCWSSMSTSASNRSSCSLSGSXSKSISBSOZAGSSSESLKSDSRSJSECHSYTWTJTZTHTLTGTKTOTTTNTRTMTCTVUGUAAEGBUSUMUYUZVUVEVNVGVIWFEHYEZMZWXKZZ_EU
state_codestringRequired

The state/province code where the registration applies.

state_namestringRequired

The name of the state/province.

filing_frequencyFilingFrequencyEnum

Specifies how often tax filings should be made. Possible values: MONTHLY, QUARTERLY, ANNUALLY, UNKNOWN. Required unless isPreCollecting is set.

Available options:UNKNOWNMONTHLYQUARTERLYSEMI_ANNUALLYANNUALLYANNUAL_FISCAL_YEARSEMI_MONTHLYBI_MONTHLYFOUR_MONTHLYQUARTERLY_PREPAYMENT
period_end_monthinteger

Fiscal-year anchor month (1-12) on which each recurring period ends, for filers whose periods are offset from the calendar: Hawaii (US-HI) quarterly/semiannual, British Columbia (CA-BC) and United Kingdom (GB) quarterly, and California (US-CA) and District of Columbia (US-DC) annual. Null (default) keeps the standard calendar grid.

usernamestring

Username for accessing tax registration details.

commentstring

Additional comments related to the registration.

create_filings_fromstring

The date from which filings should be created. should start (YYYY-MM-DD).

initial_syncboolean

Indicates whether an initial synchronization should be performed.

amount_feesnumber | string

The amount of fees associated with the registration.

vdaboolean

Indicates whether a Voluntary Disclosure Agreement (VDA) applies.

importedboolean

Whether the registration was imported from another system.

sales_tax_idstring

The sales tax ID associated with the registration.

ior_numberstring

The Importer of Record (IOR) number associated with the registration.

sst_importboolean

Indicates whether the registration is an SST Import.

tax_idstring

Organization-level tax ID (e.g., VAT number, Canada Business Number).

password_plain_textstring

The plaintext password for accessing the tax registration account.

password_metadata_plain_textstring

Metadata related to the password.

jurisdiction_specific_fieldsAlabamaFieldsRequired

Alabama-specific registration fields.

request_idstring

Optional client-minted id for this confirm attempt.

tax_typeTaxTypeEnum

Tax obligation this registration covers.

Available options:SALES_TAXUSE_TAXSALES_AND_USE_TAXRETAIL_DELIVERY_FEESMALL_PARCEL_VAT

Response

registration_datestring

The date when the registration was created. Format: YYYY-MM-DD.

registration_emailstring

Email address associated with the registration.

registration_requestedstring

Timestamp when the registration was requested.

registration_completedstring

Timestamp when the registration was completed.

deregistration_requestedstring

Timestamp when deregistration was requested.

deregistration_completedstring

Timestamp when the deregistration was completed.

auto_registeredboolean

Indicates whether the registration was completed automatically.

registrations_regimeRegistrationsRegimeEnum

The tax registration regime (e.g., STANDARD, SIMPLIFIED).

Available options:STANDARDSIMPLIFIED
change_regime_statusChangeRegimeStatusEnum
Available options:REQUESTEDAPPROVEDDONEACKNOWLEDGED
third_party_enabledboolean

Indicates whether third-party access is enabled for this registration.

do_not_fileboolean

If true, do not file for this registration (treated as False by default).

two_factor_enabledboolean

Indicates whether two-factor authentication (2FA) is enabled for this registration.

marked_collectingboolean

Indicates whether the registration is marked as collecting in shopify

is_pre_collectingboolean

True when this PROCESSING registration marks the organization as collecting tax in the jurisdiction ahead of registration details. It skips the Tax Ops registration task until the flag is cleared.

statusRegistrationStatusEnumRequired

The current status of the registration. Possible values: REGISTERED, PROCESSING, UNREGISTERED, DEREGISTERING, DEREGISTERED, CANCELLED, VALIDATING, AWAITING_CLARIFICATION, SELF_MANAGED.

Available options:REGISTEREDPROCESSINGUNREGISTEREDDEREGISTERINGDEREGISTEREDCANCELLEDVALIDATINGAWAITING_CLARIFICATIONSELF_MANAGED
country_codeCountryCodeEnumRequired

The country code (ISO 3166-1 alpha-2 format) where the registration applies.

Available options:AFAXALDZASADAOAIAQAGARAMAWAUATAZBSBHBDBBBYBEBZBJBMBTBOBQBABWBVBRIOBNBGBFBICVKHCMCAKYCFTDCLCNCXCCCOKMCGCDCKCRHRCUCWCYCZDKDJDMDOECEGSVGQEREESZETFKFOFJFIFRGFPFTFGAGMGEDEGHGIGRGLGDGPGUGTGGGNGWGYHTHMVAHNHKHUISINIDIRIQIEIMILITCIJMJPJEJOKZKEKIKPKRKWKGLALVLBLSLRLYLILTLUMOMGMWMYMVMLMTMHMQMRMUYTMXFMMDMCMNMEMSMAMZMMNANRNPNLNCNZNINENGNUNFMKMPNOOMPKPWPSPAPGPYPEPHPNPLPTPRQARERORURWBLSHKNLCMFPMVCWSSMSTSASNRSSCSLSGSXSKSISBSOZAGSSSESLKSDSRSJSECHSYTWTJTZTHTLTGTKTOTTTNTRTMTCTVUGUAAEGBUSUMUYUZVUVEVNVGVIWFEHYEZMZWXKZZ_EU
state_codestringRequired

The state/province code where the registration applies.

state_namestringRequired

The name of the state/province.

filing_frequencyFilingFrequencyEnumRequired

Specifies how often tax filings should be made. Possible values: MONTHLY, QUARTERLY, ANNUALLY, UNKNOWN.

Available options:UNKNOWNMONTHLYQUARTERLYSEMI_ANNUALLYANNUALLYANNUAL_FISCAL_YEARSEMI_MONTHLYBI_MONTHLYFOUR_MONTHLYQUARTERLY_PREPAYMENT
initial_filing_frequencyFilingFrequencyEnum

The first non-UNKNOWN filing frequency this registration was ever assigned.

Available options:UNKNOWNMONTHLYQUARTERLYSEMI_ANNUALLYANNUALLYANNUAL_FISCAL_YEARSEMI_MONTHLYBI_MONTHLYFOUR_MONTHLYQUARTERLY_PREPAYMENT
scheduled_filing_frequencyFilingFrequencyEnum

The filing frequency that will automatically replace filing_frequency on filing_frequency_effective_date. Null when no frequency change is pending.

Available options:UNKNOWNMONTHLYQUARTERLYSEMI_ANNUALLYANNUALLYANNUAL_FISCAL_YEARSEMI_MONTHLYBI_MONTHLYFOUR_MONTHLYQUARTERLY_PREPAYMENT
filing_frequency_effective_datestring

The date on which scheduled_filing_frequency should automatically become the registration's filing_frequency. Null when no frequency change is pending.

period_end_monthinteger

Month (1-12) on which this registration's filing period ends, for fiscal-year filers whose quarterly/semiannual periods are offset from the calendar. Null means calendar-aligned periods.

usernamestring

Username for accessing tax registration details.

commentstring

Additional comments related to the registration.

create_filings_fromstring

The date from which filings should be created. should start (YYYY-MM-DD).

create_back_filingboolean

Whether to also file the single period preceding the first filing period.

initial_syncboolean

Indicates whether an initial synchronization should be performed.

amount_feesstring

The amount of fees associated with the registration.

vdaboolean

Indicates whether a Voluntary Disclosure Agreement (VDA) applies.

importedboolean

Whether the registration was imported from another system.

sales_tax_idstring

Account number for this registration. Holds the sales tax ID on a sales or combined permit, and the consumer use tax account number on a use tax registration.

ior_numberstring

The Importer of Record (IOR) number associated with the registration.

ior_datestring

The date the Importer of Record (IOR) became effective (YYYY-MM-DD). For jurisdictions where tax collection starts after the IOR date rather than the registration date, this is the date on/after which tax is collected.

sst_importboolean

Indicates whether the registration is an SST Import.

oss_typeOssTypeEnum

The type of OSS registration. Should be filled for ZZ_EU OSS registrations.

Available options:UNIONNON_UNIONIOSS
oss_member_state_of_identification_codeCountryCodeEnum

The Member State of Identification code for OSS registrations.

Available options:AFAXALDZASADAOAIAQAGARAMAWAUATAZBSBHBDBBBYBEBZBJBMBTBOBQBABWBVBRIOBNBGBFBICVKHCMCAKYCFTDCLCNCXCCCOKMCGCDCKCRHRCUCWCYCZDKDJDMDOECEGSVGQEREESZETFKFOFJFIFRGFPFTFGAGMGEDEGHGIGRGLGDGPGUGTGGGNGWGYHTHMVAHNHKHUISINIDIRIQIEIMILITCIJMJPJEJOKZKEKIKPKRKWKGLALVLBLSLRLYLILTLUMOMGMWMYMVMLMTMHMQMRMUYTMXFMMDMCMNMEMSMAMZMMNANRNPNLNCNZNINENGNUNFMKMPNOOMPKPWPSPAPGPYPEPHPNPLPTPRQARERORURWBLSHKNLCMFPMVCWSSMSTSASNRSSCSLSGSXSKSISBSOZAGSSSESLKSDSRSJSECHSYTWTJTZTHTLTGTKTOTTTNTRTMTCTVUGUAAEGBUSUMUYUZVUVEVNVGVIWFEHYEZMZWXKZZ_EU
tax_typeTaxTypeEnum

Which taxes this registration account covers. SALES_AND_USE_TAX is one real permit covering both; it does not imply sales activity or that sales tax should be calculated.

Available options:SALES_TAXUSE_TAXSALES_AND_USE_TAXRETAIL_DELIVERY_FEESMALL_PARCEL_VAT
marked_collecting_datestring

The date when the registration was marked as collecting.

needs_mark_as_collectingboolean

Indicates whether the registration needs to be marked as collecting.

idstringRequired

The unique identifier for the registration.

created_atstring

Timestamp when this registration was created in Kintsugi.

credits_total_availablestring
registration_categoryRegistrationCategoryEnum

The category of the registration. Possible values: REGULAR, IMPORTED, DEREGISTRATION.

Available options:REGULARIMPORTEDDEREGISTRATION
jurisdiction_specific_fieldsobject

Jurisdiction-specific registration fields.

deregistration_closure_datestring

Effective date the registration closes with the jurisdiction.

deregistration_reasonDeregistrationReasonEnum

Reason the registration is being closed.

Available options:FULL_BUSINESS_CLOSURECLOSING_NEXUS_IN_STATE
deregistration_acknowledged_atstring

When final-return acknowledgement was recorded.

kintsugi_mail_on_fileboolean

True when the Kintsugi Mail address is on file with the state for this registration.

kintsugi_mail_confirmed_atstring

Date Tax Ops marked Kintsugi Mail as on file with the state. Null when not on file.

filing_daysintegerRequired
registration_typeRegistrationTypeEnumRequired
Available options:EU_OSSOTHER
filing_website_urlstringRequired

State tax portal URL for this registration's jurisdiction.

200

Successfully created registration

401

Unauthenticated request.

409

Registration already exists

422

Validation error

500

Internal server error

cURL
POST /v1/registrations
-H "x-api-key: ***"
{
"registration_date": "2025-02-01",
"registration_email": "example@domain.com",
"country_code": "US",
"state_code": "TX",
"state_name": "Texas",
"filing_frequency": "MONTHLY",
"auto_registered": true,
"amount_fees": 100,
"comment": "Registering for monthly sales tax filings",
"initial_sync": false
}
Response
{
"registration_date": "2025-02-01",
"registration_email": "example@domain.com",
"status": "REGISTERED",
"registration_requested": "2025-02-18T19:43:32.684802",
"auto_registered": true,
"country_code": "US",
"state_code": "AR",
"state_name": "Arizona",
"filing_frequency": "MONTHLY",
"comment": "Registering for monthly sales tax filings",
"initial_sync": false,
"amount_fees": "100.00",
"vda": false,
"id": "regs_shaGJSHHr4YXg"
}
Create registration | Kintsugi API Reference