KintsugiKintsugi
API reference / Create registration

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
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
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) quarterly, and California (US-CA) 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.

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

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.

retail_delivery_fee_obligatedboolean

Whether this registration is declared obligated to file a Retail Delivery Fee return (e.g. Colorado DR 1786).

retail_delivery_fee_effective_fromstring

First date from which retail delivery fee filings may be generated. Periods that closed before this date must not get those filings.

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_TAX
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.

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"
}