# Managing Nexus (2026-07-21)

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

Source: https://docs.trykintsugi.com/docs/2026-07-21/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 Physical 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 /physical-nexus.

Example Request

{
"countryCode": "US",
"stateCode": "CA",
"category": "PHYSICAL_BUSINESS_LOCATION",
"startDate": "2026-01-01"
}

Recording a presence can establish nexus in the jurisdiction, so its exposure is recalculated. One record exists per organization, jurisdiction and category: a second create for the same three returns 200. A category the jurisdiction does not accept returns 400; get the accepted set from GET /physical-nexus/categories.

## Step 2: Create Registration

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

Example Request

{
"countryCode": "US",
"stateCode": "CA",
"filingFrequency": "UNKNOWN",
"registrationDate": "2026-01-01"
}

Send filingFrequency UNKNOWN when the jurisdiction has not assigned one yet; Kintsugi replaces it once it does. registrationImportType defaults to REGULAR, a direct registration identified by countryCode and stateCode.

## Step 3: Retrieve Physical Nexus

Retrieve physical nexus records using GET /physical-nexus. You can filter by:

countryCode: Filter by countries (comma-separated)

stateCode: Filter by states (comma-separated)

Pagination: Use limit and the cursor from a prior response's nextCursor or previousCursor

## Step 4: Retrieve Registrations

Retrieve registrations using GET /registrations. You can filter by:

countryCode: Filter by countries (comma-separated)

stateCode: Filter by states (comma-separated)

status: Filter by registration status (comma-separated)

Pagination: Use limit and the cursor from a prior response's nextCursor or previousCursor

## Authentication

These endpoints take one credential header:

Api-Key: Your API key

Api-Version: 2026-07-21 is optional. A request without it runs against 2026-07-21. When your key can reach more than one organization, add an Organization-Id, Connection-Id or Entity-Id header to choose which one the request targets.

## 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 Record a physical presence

POST /physical-nexus

{

"countryCode": "US",

"stateCode": "CA",

"category": "PHYSICAL_BUSINESS_LOCATION",

"startDate": "2026-01-01"

}

{
"countryCode": "US",
"stateCode": "CA",
"category": "PHYSICAL_BUSINESS_LOCATION",
"startDate": "2026-01-01"
}

Run

2 Create a registration

POST /registrations

{

"countryCode": "US",

"stateCode": "CA",

"filingFrequency": "UNKNOWN",

"registrationDate": "2026-01-01"

}

{
"countryCode": "US",
"stateCode": "CA",
"filingFrequency": "UNKNOWN",
"registrationDate": "2026-01-01"
}

Run

3 List nexus determinations

GET /nexus

Read back the nexus footprint for your organization.

Run

## Required Fields

Physical Nexus

countryCode: ISO 3166-1 alpha-2 country of the jurisdiction (for example, US)

stateCode: State or province code within countryCode (for example, CA)

category: Kind of physical presence to record (for example, PHYSICAL_BUSINESS_LOCATION)

startDate: Date the physical presence began, as YYYY-MM-DD

Registration

countryCode: ISO 3166-1 alpha-2 country to register in (for example, US)

filingFrequency: How often returns should be filed (for example, MONTHLY, or UNKNOWN when none is assigned yet)

stateCode is optional: omit it for a country-level registration.

## Common Use Cases

Physical Business Location

Create nexus for a physical office or warehouse:

{
"countryCode": "US",
"stateCode": "CA",
"category": "PHYSICAL_BUSINESS_LOCATION",
"startDate": "2026-01-01",
"externalId": "hris-4471",
"street1": "123 Main St",
"street2": "Suite 400",
"city": "San Francisco",
"postalCode": "94107"
}

Add an endDate ( YYYY-MM-DD, not before startDate) when the presence has ended; omit it while the presence is open-ended.

Registration

Create a registration for a jurisdiction:

{
"registrationImportType": "REGULAR",
"countryCode": "US",
"stateCode": "CA",
"stateName": "California",
"filingFrequency": "UNKNOWN",
"registrationDate": "2026-01-01",
"salesTaxId": "123-456789"
}

salesTaxId is the account number the jurisdiction issued, on a registration you already hold.

## Response Fields

Record a physical presence

id: Opaque unique identifier for this physical nexus

externalId: Your identifier for this record in an external system

countryCode: ISO 3166-1 alpha-2 country of the jurisdiction

stateCode: State or province code within countryCode

startDate: Date the physical presence began, as YYYY-MM-DD

endDate: Date the physical presence ended, as YYYY-MM-DD; null while open-ended

category: Kind of physical presence the record holds

Create a registration

id: Kintsugi's unique identifier for the registration

countryCode: ISO 3166-1 alpha-2 country the registration is held in

stateCode: State or province code the registration is held in

status: Where the registration stands in onboarding and filing

filingFrequency: How often returns are filed against the registration

registrationDate: Date the registration takes effect in the jurisdiction, as YYYY-MM-DD

## Next Steps

List physical presences - List physical nexus

List registrations - List registrations

Update a physical presence - Modify nexus details

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