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.

x-organization-idstringRequired

Identifies the organization this request acts on.

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_keystring

A unique key assigned to the registration.

deregistration_keystring

A unique key assigned for deregistration.

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

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.

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.

Response

registration_datestring

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

registration_emailstring

Email address associated with the registration.

registration_keystring

A unique key assigned to the registration.

deregistration_keystring

A unique key assigned for deregistration.

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, VALIDATING, AWAITING_CLARIFICATION.

Available options:REGISTEREDPROCESSINGUNREGISTEREDDEREGISTERINGDEREGISTEREDVALIDATINGAWAITING_CLARIFICATION
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
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_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

The sales tax ID associated with the registration.

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_UNION
oss_member_state_of_identification_codeCountryCodeEnum

The Member State of Identification code for OSS registrations.

Available options:AFAXALDZASADAOAIAQAGARAMAWAUATAZBSBHBDBBBYBEBZBJBMBTBOBQBABWBVBRIOBNBGBFBICVKHCMCAKYCFTDCLCNCXCCCOKMCGCDCKCRHRCUCWCYCZDKDJDMDOECEGSVGQEREESZETFKFOFJFIFRGFPFTFGAGMGEDEGHGIGRGLGDGPGUGTGGGNGWGYHTHMVAHNHKHUISINIDIRIQIEIMILITCIJMJPJEJOKZKEKIKPKRKWKGLALVLBLSLRLYLILTLUMOMGMWMYMVMLMTMHMQMRMUYTMXFMMDMCMNMEMSMAMZMMNANRNPNLNCNZNINENGNUNFMKMPNOOMPKPWPSPAPGPYPEPHPNPLPTPRQARERORURWBLSHKNLCMFPMVCWSSMSTSASNRSSCSLSGSXSKSISBSOZAGSSSESLKSDSRSJSECHSYTWTJTZTHTLTGTKTOTTTNTRTMTCTVUGUAAEGBUSUMUYUZVUVEVNVGVIWFEHYEZMZWXKZZ_EU
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.

credits_total_availablestring
registration_categoryRegistrationCategoryEnum

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

Available options:REGULARIMPORTEDDEREGISTRATION
filing_daysintegerRequired
registration_typeRegistrationTypeEnumRequired
Available options:EU_OSSOTHER
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: ***"
-H "x-organization-id: ***"
{
"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"
}