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 Physical Nexus - View all physical nexus records
4. 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

Try It Out

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

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