Tax Registration API Overview

Introduction

The Tax Registration API is a REST integration provided by CorpNet for registering employers for state and federal tax accounts (unemployment insurance, withholding, and equivalents) across all 50 U.S. states. Partner systems — accounting platforms, payroll providers, business-formation services — use it to create, submit, and track tax registration orders programmatically.

Use this API to:

• Submit business and state-by-state tax registration data in a single payload.
• Track order progression and retrieve issued account numbers and tax rates.
• Register employers in any state, including California, through a unified endpoint.

API at a glance

Authentication

The API uses Bearer token authentication. CorpNet issues your token directly during partner onboarding — there is no token exchange and no OAuth flow. The same token authenticates both the Tax Registration API and the Business Formation API; entitlement to each product follows your partner agreement.

Authorization: Bearer <your_api_key>

See Authorization for the full auth model and error semantics.

Endpoints

📘

GET returns a status summary, not the full submitted order. Submitted business details, state info, and responsible parties are NOT retrievable via GET — partners should retain a local copy of the submission. See the Retrieve reference for the exact summary shape.

Request workflow

1. Obtain a Bearer token from CorpNet (see API Key).
2. Construct your order payload — partnerOrder envelope with orderFilingType, apiUserPid, pcid, accountInfo, businessDetails, stateInfo, responsibleParties. See the Create reference for the full request schema.
3. POST the payload to /api/api-partners-v10/tax-reg-50states/. On success the API returns HTTP 201 with the full submitted order echoed back, plus the assigned orderGuid.
4. Store the orderGuid for status polling.
5. GET /{orderGuid} as needed to track orderPhase, orderStatus, and any populated accountNumbers / taxRates / agencyAccounts.

Common gotchas

• Validation cascades. Some fields are conditionally required (e.g., responsibleParty.dateOfBirth is required when type === "INDIVIDUAL"; nonProfitInfo is required when entityType === "Non-Profit Corporation"). See the Create reference for the per-field conditions.
• Per-entity-type title enums. responsibleParty.title is enum-validated against an undocumented per-entity-type list — LLCs accept Member/Manager; C-Corp/S-Corp accept Director/President/Secretary/Treasurer/Vice President/CEO (but reject the generic Officer). See the schema description on ResponsibleParty for the full table.
• Format-only EIN validation. The API checks NN-NNNNNNN format only — the EIN is not verified against the IRS database. Do client-side sanity checks before submitting.
• firstPayrollAmount — accepts strings, decimals, zero, and (incorrectly) negative values. Validate >= 0 client-side.
• Not-found returns 400, not 404. GET on a non-existent orderGuid returns HTTP 400 with body {"statusCode": 200, "message": "success", "data": {"partnerOrder": null}}. Detect not-found by checking data.partnerOrder === null rather than trusting the status fields.

Best practices

• Use HTTPS and keep tokens server-side; never embed in client-side code.
• Validate request bodies before submission to avoid round-trip 400s.
• Use the staging environment to dry-run integrations before production.
• Log orderGuid and submission payloads on your side — the GET endpoint won't return submitted business details on its own.

Support

For credentials, onboarding, or technical assistance, contact your CorpNet account manager or [email protected].