About

The nexus and registration service includes four key endpoints that manage tax nexus and registration obligations. These endpoints work together to help you determine where your organization needs to register for tax collection and maintain accurate registration information.

Available endpoints

Create new tax obligation

POST /api/rest/organization/taxObligation/create

Set tax obligation

POST /api/rest/organization/obligation/set

List organization registrations

POST /api/rest/organizationRegistration/list

List tax jurisdictions

POST /api/rest/taxjurisdictions/list

These endpoints typically work together in this sequence:

1. Retrieve available tax jurisdictions in a hierarchical structure with the list tax jurisdictions endpoint. Use it to discover jurisdiction IDs and codes needed for creating tax obligations.

2. Create initial registrations using the create tax obligation endpoint for new jurisdictions, for example, when setting up initial tax registrations for a new organization.

3. Update registrations using the set tax obligation endpoint when you need to update registration numbers or statuses, for example, when registration requirements change.

4. Query registration status using the list organization registrations endpoint to view your organization's registration statuses across multiple jurisdictions.

Best practices

Use jurisdiction identifiers consistently

Choose either geographic codes (country, state, city) or Sovos tax jurisdiction IDs (TJCIDs). Do not use both identifiers in a single request.

Set appropriate registration status

Use regStatusId values that accurately reflect your registration status. Setting incorrect registration statuses can result in incorrect tax calculations. To learn what the different statuses mean, read Registration statuses.

Maintain active status

When updating registrations, ensure the isActive flag reflects whether the registration is currently valid. Inactive registrations are not used for tax calculations.

Handle hierarchical jurisdictions

When working with multi-level jurisdictions (country → state → county → city), create tax obligations at each relevant level. The tax calculation engine uses the most specific applicable jurisdiction.

Update rather than recreate

Use the set tax obligation endpoint to modify existing registrations rather than creating duplicates. The Sovos software identifies existing registrations by jurisdiction and organization/business party combination.