The service-provider API is firm-agnostic. A provider credential belongs to one enabled practice and can administer only that practice's client engagements. Every client is a normal Prophit organization with normal locations—not a provider-only copy.
Tenant model and portability
Provider onboarding writes to the same canonical organization and location model used by direct customers. Transactions, product mappings, customer mappings, certificates, nexus configuration, registrations, return accounts, and return packages stay with the taxpayer organization. Pausing or offboarding the provider relationship removes provider authority only. The taxpayer can later receive direct users, entitlements, billing, and ordinary API keys without copying or migrating tax data.
1. Create a provider credential
In an enabled provider workspace, open the Developer Console, create a key, and choose Service provider portfolio. Provider keys are organization-scoped to the firm and include explicit provider administration and return-job scopes. Secrets are shown once.
2. Onboard a taxpayer
Supply a stable external_client_id from your system. Repeating the same create request for that identifier returns the existing engagement, making onboarding retries safe.
curl -X POST https://prophit.ai/api/v1/provider/clients \
-H "Authorization: Bearer itms_test_YOUR_PROVIDER_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_client_id": "CLIENT-1001",
"name": "Example Taxpayer",
"address_line1": "100 Main Street",
"city": "Austin",
"state": "TX",
"zip_code": "78701",
"primary_location": {
"name": "Main",
"address_line1": "100 Main Street",
"city": "Austin",
"state": "TX",
"zip_code": "78701"
}
}'The response makes both context values explicit. Send client_context_ref in X-ITMS-Client-Ref (recommended), or send the numeric client_context_id in X-ITMS-Client-Id for backward compatibility. Organization IDs are returned for reconciliation but are never accepted as authorization.
3. Configure and check readiness
Create or update locations under /api/v1/provider/clients/{client_id}/locations. Use the normal client-scoped item, customer, jurisdiction-account, transaction, and return endpoints for tax configuration. Call the readiness endpoint to identify missing legal identity, active locations, registrations, filing obligations, and return accounts. A readiness response is advisory and does not hide incomplete exemption certificates or product mappings.
4. Select the taxpayer on every tax-data request
Provider administration endpoints do not use a client header. Global discovery through /config and /coverage/states also needs no taxpayer selection. Every calculation, batch, item mapping, customer mapping, transaction, operational-status, jurisdiction-account, and return-package request does. Send the provider-owned external client reference:
curl -X POST https://prophit.ai/api/v1/tax/calculate \
-H "Authorization: Bearer itms_test_YOUR_PROVIDER_KEY" \
-H "X-ITMS-Client-Ref: CLIENT-1001" \
-H "X-ITMS-Test-Run-Id: onboarding-2026-07-29" \
-H "X-ITMS-Test-Case-Id: first-calculation" \
-H "Content-Type: application/json" \
-d '{
"transaction_date": "2026-06-30",
"ship_to": {
"line1": "100 Congress Ave",
"city": "Austin",
"state": "TX",
"zip_code": "78701"
},
"lines": [{"number": 1, "amount": 250.00, "quantity": 1}]
}'Omitting the header returns missing_client_context. A malformed value returnsinvalid_client_context. A foreign, paused, offboarded, or unavailable engagement returnsclient_context_not_authorized without disclosing another provider's clients. An inactive service-provider account returns provider_not_active for both administration and taxpayer-data operations.
If you send both client-context headers, they must identify the same engagement. Use X-ITMS-Test-Run-Id and X-ITMS-Test-Case-Id to correlate Postman runs with support diagnostics; sanitized values are echoed on every response.
5. Prepare portfolio return output
A return job accepts up to 5,000 explicit client/state periods. Items are isolated: one setup or validation failure does not discard successful clients. The idempotency key is unique to the provider and environment.
curl -X POST https://prophit.ai/api/v1/provider/return-jobs \
-H "Authorization: Bearer itms_test_YOUR_PROVIDER_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotency_key": "2026-06-monthly-portfolio-v1",
"items": [
{
"reference_id": "CLIENT-1001-TX-2026-06",
"client_id": 42,
"state": "TX",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"filing_frequency": "monthly"
}
]
}'Poll GET /api/v1/provider/return-jobs/{job_id}. Successful items include gross sales, exempt sales, taxable sales, tax due, collected tax, seller-remittable tax, discounts, credits, net remittance due, zero-return status, jurisdiction/location lines, setup requirements, validation results, and authorized artifact download paths. The output is neutral JSON suitable for the provider's reconciliation and branded deliverables. ITMS does not file the return or move money through these endpoints.
6. Review workflow and client approval
Prepared returns move through a four-state workflow: submitted → review complete → approved (locked), with request-changes and resubmission at each review step. Configure per-client preparer/reviewer/approver defaults (and per-state overrides) with PUT /api/v1/provider/clients/{client_id}/workflow/assignments; the approver must always be a user of the client organization. Data-receipt cutoffs walk back from each jurisdiction due date: PUT /api/v1/provider/data-deadlines sets the provider default or a per-client override, and POST /api/v1/provider/clients/{client_id}/data-receipts records timeliness evidence.
Transitions are scope-separated for machine callers: provider:workflow:write submits and completes review (/api/v1/provider/returns/{package_id}/submit-for-review, …/complete-review, …/request-changes), while client approval happens either in-app by the client's own users or through a temporary approval package minted with POST /api/v1/provider/approval-packages (provider:approvals:write). The response contains the portal URL and bearer token exactly once; only a hash is stored, links expire (24h default, 1–168h), and they can be revoked or re-issued. Poll GET /api/v1/provider/approval-packages/{id} for the client's decision, attestation, and access audit. Approval locks the reviewed figures; a material change afterwards requires invalidation, re-review, and a fresh approval package. Nothing is transmitted to a tax authority by preparing, reviewing, or approving.
Sandbox and production boundaries
Sandbox provider keys create sandbox calculations, transactions, return packages, and jobs. Production keys operate only on production records. Client engagements and canonical tenant configuration are shared control plane records, while every tax-data operation remains isolated by the key environment. Standard per-key rate limits apply; submit large calculations through calculation batches and large return portfolios through return jobs.
For sandbox troubleshooting, bounded JSON request and response bodies may be retained encrypted for up to 90 days. Secret-like body fields are redacted before encryption, and authorization, API-key, and cookie headers are never retained. Production request payloads remain metadata-only.