# Managing Nexus

> Interactive walkthrough for creating physical nexus, registrations, and retrieving nexus information

Source: https://docs.trykintsugi.com/docs/recipes/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

Create Physical Nexus - Record a physical business location

Create Registration - Register in a jurisdiction

Retrieve Nexus - View all physical nexus records

Retrieve Registrations - View all registrations

## Step 1: Create Physical Nexus

Create a physical nexus record using the API Lab below with POST /v1/nexus/physical_nexus.

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.

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

API Lab Simulated

Run all Reset Share Copy cURL Postman

Runs in a simulated sandbox. Responses are generated from the API schema so you can explore each call safely; they never reach the live API, so the values are illustrative.

1 Create physical nexus

POST /v1/nexus/physical_nexus

{

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

}

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

Run

2 Create registration

POST /v1/registrations

{

"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

}

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

Run

3 Get nexus for org

GET /v1/nexus

Read back the nexus footprint for your organization.

Run

## Required Fields

Physical Nexus

country_code: Country code (for example, US)

state_code: State code (for example, CA)

start_date: Date the nexus obligation began

category: Nexus category

Registration

country_code: Country code (for example, US)

state_code: State code (for example, TX)

registration_date: Date the registration became effective

filing_frequency: How often you file returns (for example, MONTHLY)

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

Create physical nexus

external_id: Your 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

Create registration

id: Unique registration identifier

country_code: Country code

state_code: State code

status: Registration status

filing_frequency: How often you file returns

registration_date: Date the registration was recorded

## Next Steps

Get Physical Nexus - List physical nexus

Get Registrations - List registrations

Update Physical Nexus - Modify nexus details

Update Registration - Modify registration details

## Related Resources

Nexus API Reference

Registrations API Reference

Getting Started

Support

---

Index of every page: https://docs.trykintsugi.com/llms.txt