> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trykintsugi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Managing Nexus
> Interactive playground for creating physical nexus, registrations, and retrieving nexus information
# 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
```json theme={null}
{
"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
```json theme={null}
{
"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](https://app.trykintsugi.com).
## 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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
* [Get Physical Nexus](/reference/api/nexus/get-physical-nexus) - List physical nexus
* [Get Registrations](/reference/api/registrations/get-registrations) - List registrations
* [Update Physical Nexus](/reference/api/nexus/update-physical-nexus) - Modify nexus details
* [Update Registration](/reference/api/registrations/update-registration) - Modify registration details
## Related Resources
* [Nexus API Reference](/reference/api/nexus/create-physical-nexus)
* [Registrations API Reference](/reference/api/registrations/create-registration)
* [Getting Started](/docs/getting-started)
* [Support](https://trykintsugi.com/support)
## OpenAPI
````yaml post /v1/nexus/physical_nexus
openapi: 3.0.0
info:
title: Tax Platform
version: 1.0.0
servers:
- url: https://api.trykintsugi.com
description: Production API server URL
security: []
paths:
/v1/nexus/physical_nexus:
post:
tags:
- Nexus
summary: Create Physical Nexus
description: |-
The Create Physical Nexus API allows you to create a new physical
nexus by specifying its attributes, including the location,
start date, end date, etc.
operationId: create_physical_nexus_v1_nexus_physical_nexus_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PhysicalNexusCreate'
example:
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
street_1: 123 Main Street
street_2: Suite 100
city: San Francisco
postal_code: '94102'
responses:
'200':
description: Successfully created physical nexus
content:
application/json:
schema:
$ref: '#/components/schemas/PhysicalNexusRead'
example:
country_code: US
state_code: CA
start_date: '2024-01-01'
end_date: '2025-01-01'
category: PHYSICAL_BUSINESS_LOCATION
external_id: ext_ABC123
'401':
description: Unauthenticated request.
content:
application/json:
example:
detail: The request is missing a valid x-api-key.
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation error
content:
application/json:
example:
detail:
- type: date_from_datetime_parsing
loc:
- body
- start_date
msg: >-
Input should be a valid date or datetime, input is too
short
input: 23rd Jan
ctx:
error: input is too short
schema:
$ref: >-
#/components/schemas/backend__src__nexus__responses__ValidationErrorResponse
'500':
description: Internal server error
content:
application/json:
example:
detail: An unexpected error occurred
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- APIKeyHeader: []
CustomHeader: []
components:
schemas:
PhysicalNexusCreate:
properties:
country_code:
$ref: '#/components/schemas/CountryCodeEnum'
description: |-
The country code in ISO
3166-1 alpha-2 format (e.g., US).
state_code:
type: string
title: State Code
description: |-
The state or province code in
ISO 3166-2 format (e.g., CA).
start_date:
type: string
format: date
title: Start Date
description: |-
The date when the nexus became
effective (YYYY-MM-DD).
end_date:
description: |-
The date when the
nexus ended, if applicable.
type: string
category:
$ref: '#/components/schemas/PhysicalNexusCategory'
description: |-
The reason for the
nexus (e.g.,
'TELECOMMUTING_OR_REMOTE_EMPLOYEE').
external_id:
description: |-
Optional
external identifier for the nexus.
type: string
source:
$ref: '#/components/schemas/PhysicalNexusSource'
description: |-
The source of the physical nexus presence.
Possible values: USER, DEEL.
default: USER
street_1:
description: Primary street address for the physical presence location.
type: string
street_2:
description: Additional street address details, such as suite or unit number.
type: string
city:
description: City of the physical presence location.
type: string
postal_code:
description: ZIP or postal code of the physical presence location.
type: string
type: object
required:
- country_code
- state_code
- start_date
- category
title: PhysicalNexusCreate
PhysicalNexusRead:
properties:
country_code:
$ref: '#/components/schemas/CountryCodeEnum'
description: |-
The country code in ISO
3166-1 alpha-2 format (e.g., US).
state_code:
type: string
title: State Code
description: |-
The state or province code in
ISO 3166-2 format (e.g., CA).
start_date:
type: string
format: date
title: Start Date
description: |-
The date when the nexus became
effective (YYYY-MM-DD).
end_date:
description: |-
The date when the
nexus ended, if applicable.
type: string
category:
$ref: '#/components/schemas/PhysicalNexusCategory'
description: |-
The reason for the
nexus (e.g.,
'TELECOMMUTING_OR_REMOTE_EMPLOYEE').
external_id:
description: |-
Optional
external identifier for the nexus.
type: string
source:
$ref: '#/components/schemas/PhysicalNexusSource'
description: |-
The source of the physical nexus presence.
Possible values: USER, DEEL.
default: USER
street_1:
description: Primary street address for the physical presence location.
type: string
street_2:
description: Additional street address details, such as suite or unit number.
type: string
city:
description: City of the physical presence location.
type: string
postal_code:
description: ZIP or postal code of the physical presence location.
type: string
id:
type: string
title: Id
description: The unique identifier for the physical nexus.
type: object
required:
- country_code
- state_code
- start_date
- category
- id
title: PhysicalNexusRead
ErrorResponse:
properties:
detail:
type: string
title: Detail
description: Error message
type: object
required:
- detail
title: ErrorResponse
backend__src__nexus__responses__ValidationErrorResponse:
properties:
detail:
items:
$ref: >-
#/components/schemas/backend__src__nexus__responses__ValidationErrorItem
type: array
title: Detail
type: object
required:
- detail
title: ValidationErrorResponse
CountryCodeEnum:
type: string
enum:
- 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
title: CountryCodeEnum
PhysicalNexusCategory:
type: string
enum:
- 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
title: PhysicalNexusCategory
PhysicalNexusSource:
type: string
enum:
- USER
- DEEL
title: PhysicalNexusSource
backend__src__nexus__responses__ValidationErrorItem:
properties:
type:
type: string
title: Type
description: |-
Validation issues, such as missing required
fields or invalid field values.
loc:
items:
type: string
type: array
title: Loc
description: Location of error
msg:
type: string
title: Msg
description: Error message
input:
title: Input
description: Invalid input value
ctx:
additionalProperties: true
type: object
title: Ctx
description: Additional context
type: object
required:
- type
- loc
- msg
- input
- ctx
title: ValidationErrorItem
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-KEY
CustomHeader:
type: apiKey
in: header
name: x-organization-id
````