Skip to main content
POST
/
v1
/
nexus
/
physical_nexus
Create Physical Nexus
curl --request POST \
  --url https://api.trykintsugi.com/v1/nexus/physical_nexus \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'x-organization-id: <api-key>' \
  --data '
{
  "country_code": "US",
  "state_code": "CA",
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "category": "PHYSICAL_BUSINESS_LOCATION",
  "external_id": "ext_ABC123",
  "source": "USER"
}
'
{
  "country_code": "US",
  "state_code": "CA",
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "category": "PHYSICAL_BUSINESS_LOCATION",
  "external_id": "ext_ABC123"
}

​
Managing Nexus

​
Overview

Nexus determines where your business has a tax obligation. Physical nexus represents business locations (offices, warehouses, employees), while registrations represent jurisdictions where you’re registered to collect and remit sales tax. This API Lab covers managing both physical nexus and registrations.

​
Understanding Nexus Types

  • Physical Nexus: Business locations that create tax obligations (offices, warehouses, employees)
  • Registrations: Jurisdictions where you’re registered to collect and remit tax

​
Workflow

  1. Create Physical Nexus - Record a physical business location
  2. Create Registration - Register in a jurisdiction
  3. Retrieve Nexus - View all physical nexus records
  4. Retrieve Registrations - View all registrations

​
Step 1: Create Physical Nexus

Create a physical nexus record using the interactive playground below with POST /v1/nexus/physical_nexus.

​
Required Fields

  • country_code: Country code (ISO 3166-1 alpha-2, e.g., “US”)
  • state_code: State or province code (e.g., “CA”, “NY”)
  • start_date: Date when nexus began
  • category: Nexus category (e.g., “PHYSICAL_BUSINESS_LOCATION”)

​
Example Request

{
  "country_code": "US",
  "state_code": "CA",
  "start_date": "2024-01-01",
  "category": "PHYSICAL_BUSINESS_LOCATION"
}

​
Step 2: Create Registration

Create a registration using POST /v1/registrations. This represents a jurisdiction where you’re registered to collect tax.

​
Required Fields

  • country_code: Country code
  • state_code: State or province code
  • registration_date: Date of registration

​
Example Request

{
  "country_code": "US",
  "state_code": "CA",
  "state_name": "California",
  "registration_date": "2024-01-01",
  "filing_frequency": "MONTHLY"
}

​
Step 3: Retrieve Physical Nexus

Retrieve physical nexus records using GET /v1/nexus/physical_nexus. You can filter by:
  • country_code: Filter by country
  • state_code: Filter by state
  • Pagination: Use page and size parameters

​
Step 4: Retrieve Registrations

Retrieve registrations using GET /v1/registrations. You can filter by:
  • country_code__in: Filter by countries
  • state_code: Filter by state
  • status__in: Filter by registration status
  • Pagination: Use page and size parameters

​
Authentication

These endpoints require two headers:
  • x-api-key: Your API key
  • x-organization-id: Your organization ID
Both headers are required for authentication. You can find your API key and organization ID in your Kintsugi dashboard.

​
Try It Out

Use the interactive playground below to create physical nexus. The playground will automatically include the required authentication headers.
The playground prefills example values from the API schema. Modify the request body to test different nexus configurations.

​
Common Use Cases

​
Physical Business Location

Create nexus for a physical office or warehouse: 
{
  "country_code": "US",
  "state_code": "CA",
  "start_date": "2024-01-01",
  "category": "PHYSICAL_BUSINESS_LOCATION",
  "external_id": "LOCATION-001"
}

​
Employee Location

Create nexus based on employee location: 
{
  "country_code": "US",
  "state_code": "NY",
  "start_date": "2024-01-15",
  "category": "EMPLOYEE_LOCATION",
  "external_id": "EMPLOYEE-NY-001"
}

​
Registration

Create a registration for a jurisdiction: 
{
  "country_code": "US",
  "state_code": "CA",
  "state_name": "California",
  "registration_date": "2024-01-01",
  "filing_frequency": "MONTHLY",
  "sales_tax_id": "123456789"
}

​
Response Fields

​
Physical Nexus Response

  • id: Unique nexus identifier
  • country_code: Country code
  • state_code: State code
  • start_date: Nexus start date
  • end_date: Nexus end date (if applicable)
  • category: Nexus category

​
Registration Response

  • id: Unique registration identifier
  • country_code: Country code
  • state_code: State code
  • status: Registration status
  • filing_frequency: How often you file returns
  • sales_tax_id: Sales tax registration number

​
Next Steps

Authorizations

​
X-API-KEY
string
header
required
​
x-organization-id
string
header
required

Body

application/json
​
country_code
enum<string>
required

The country code in ISO 3166-1 alpha-2 format (e.g., US).

Available options:
AF,
AX,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
CV,
KH,
CM,
CA,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CG,
CD,
CK,
CR,
HR,
CU,
CW,
CY,
CZ,
DK,
DJ,
DM,
DO,
EC,
EG,
SV,
GQ,
ER,
EE,
SZ,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
CI,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KP,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MK,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RE,
RO,
RU,
RW,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
US,
UM,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW,
XK,
ZZ_EU
​
state_code
string
required

The state or province code in ISO 3166-2 format (e.g., CA).

​
start_date
string<date>
required

The date when the nexus became effective (YYYY-MM-DD).

​
category
enum<string>
required

The reason for the nexus (e.g., 'TELECOMMUTING_OR_REMOTE_EMPLOYEE').

Available options:
PHYSICAL_BUSINESS_LOCATION,
TELECOMMUTING_OR_REMOTE_EMPLOYEE,
WARRANTY_AND_REPAIR_SERVICES,
CATALOGUE_DISTRIBUTION_OR_ADVERTISING_MATERIAL,
DELIVERY_BY_COMMON_CARRIER,
DELIVERY_BY_OWN_VEHICLES,
IN_STATE_SALES_PERSON,
INDEPENDENT_CONTRACTOR_OR_THIRD_PARTY_SALES_PERSON,
WAREHOUSE_AND_INVENTORY_PRESENCE,
EMPLOYEES_AGENTS_CONTRACTORS,
OWN_LEASE_A_PROPERTY,
INVENTORY,
DELIVERY_USING_COMPANY_VEHICLES,
OWN_BUSINESS_INFRASTRUCTURE_AND_EQUIPMENT,
ON_SITE_INSTALLATION_MAINTENANCE_SERVICES,
FREQUENT_PARTICIPATION_IN_TRADE_SHOWS_EVENTS,
MANUFACTURE_OR_PRODUCTION_IN_CANADA,
PERFORMING_SERVICES_IN_THE_JURISDICTION,
MANUFACTURING_FACILITIES,
SERVERS_DATA_CENTERS,
TRADE_SHOW_PRESENCE,
TRADE_SHOW_PRESENCE_WITHOUT_SALES,
DIGITAL_INFRASTRUCTURE_LOCALIZED,
PERMANENT_ESTABLISHMENT,
ENTER_CONTRACTS_WITH_LOCALS,
CONSIGNMENT_STOCK_ARRANGEMENTS
​
end_date
string

The date when the nexus ended, if applicable.

​
external_id
string

Optional external identifier for the nexus.

​
source
enum<string>
default:USER

The source of the physical nexus presence. Possible values: USER, DEEL.

Available options:
USER,
DEEL

Response

Successfully created physical nexus

​
country_code
enum<string>
required

The country code in ISO 3166-1 alpha-2 format (e.g., US).

Available options:
AF,
AX,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
CV,
KH,
CM,
CA,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CG,
CD,
CK,
CR,
HR,
CU,
CW,
CY,
CZ,
DK,
DJ,
DM,
DO,
EC,
EG,
SV,
GQ,
ER,
EE,
SZ,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
CI,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KP,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MK,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RE,
RO,
RU,
RW,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
US,
UM,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW,
XK,
ZZ_EU
​
state_code
string
required

The state or province code in ISO 3166-2 format (e.g., CA).

​
start_date
string<date>
required

The date when the nexus became effective (YYYY-MM-DD).

​
category
enum<string>
required

The reason for the nexus (e.g., 'TELECOMMUTING_OR_REMOTE_EMPLOYEE').

Available options:
PHYSICAL_BUSINESS_LOCATION,
TELECOMMUTING_OR_REMOTE_EMPLOYEE,
WARRANTY_AND_REPAIR_SERVICES,
CATALOGUE_DISTRIBUTION_OR_ADVERTISING_MATERIAL,
DELIVERY_BY_COMMON_CARRIER,
DELIVERY_BY_OWN_VEHICLES,
IN_STATE_SALES_PERSON,
INDEPENDENT_CONTRACTOR_OR_THIRD_PARTY_SALES_PERSON,
WAREHOUSE_AND_INVENTORY_PRESENCE,
EMPLOYEES_AGENTS_CONTRACTORS,
OWN_LEASE_A_PROPERTY,
INVENTORY,
DELIVERY_USING_COMPANY_VEHICLES,
OWN_BUSINESS_INFRASTRUCTURE_AND_EQUIPMENT,
ON_SITE_INSTALLATION_MAINTENANCE_SERVICES,
FREQUENT_PARTICIPATION_IN_TRADE_SHOWS_EVENTS,
MANUFACTURE_OR_PRODUCTION_IN_CANADA,
PERFORMING_SERVICES_IN_THE_JURISDICTION,
MANUFACTURING_FACILITIES,
SERVERS_DATA_CENTERS,
TRADE_SHOW_PRESENCE,
TRADE_SHOW_PRESENCE_WITHOUT_SALES,
DIGITAL_INFRASTRUCTURE_LOCALIZED,
PERMANENT_ESTABLISHMENT,
ENTER_CONTRACTS_WITH_LOCALS,
CONSIGNMENT_STOCK_ARRANGEMENTS
​
id
string
required

The unique identifier for the physical nexus.

​
end_date
string

The date when the nexus ended, if applicable.

​
external_id
string

Optional external identifier for the nexus.

​
source
enum<string>
default:USER

The source of the physical nexus presence. Possible values: USER, DEEL.

Available options:
USER,
DEEL