KintsugiKintsugi
API Lab

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 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 LabSimulated
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.
1Create physical nexus
POST/v1/nexus/physical_nexus
2Create registration
POST/v1/registrations
3Get nexus for org
GET/v1/nexus

Read back the nexus footprint for your organization.

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

Related Resources