Endpoint reference

Discover effective API limits, environments, default scopes, active tax codes, and webhook event names.

Persistence

Read-only and safe to call during application startup.

Auth

Any authenticated API key

Request

No body

Response

Effective rate limit, environments, default scopes, active tax-code registry, and webhook events

Discover the calculation mode currently serving every state and DC.

Persistence

Read-only and derived from the live serving registry.

Auth

API key · scope tax:calculate

Request

No body

Response

51 jurisdictions with dynamic, legacy, or no-statewide-tax mode and sandbox estimate availability

Create a customer exemption certificate in the shared Sales Exemption Certificate Manager.

Persistence

Creates a governed pending-review certificate. Creation never assigns it or replaces existing active customer coverage.

Auth

API key · scope transactions:write

Request

customerCode, effectiveFrom, optional jurisdiction/reason/dates/signature fields

Response

Certificate code, customer, jurisdiction, lifecycle status, assignment state, and effective dates

List exemption certificates visible in the current taxpayer scope.

Persistence

Read-only.

Auth

API key · scope transactions:read

Request

Optional customerCode and status filters; limit and offset

Response

Certificate lifecycle and assignment records plus count, limit, and offset

Get one scoped exemption certificate.

Persistence

Read-only.

Auth

API key · scope transactions:read

Request

Path param: certificate_code

Response

Certificate lifecycle, coverage jurisdiction, assignment, and effective dates

Record an authorized human review of durable exemption evidence and activate the certificate.

Persistence

Atomically stores the evidence reference, document hash, reviewer, authority, and active lifecycle state. A location key cannot mutate an inherited org-wide certificate; invalid dates or incomplete metadata fail closed.

Auth

API key · scope transactions:write

Request

attestedValid=true, evidenceReference, evidenceSha256, reviewedBy, reviewAuthority

Response

Updated certificate lifecycle record

List deterministic mappings from caller taxability-code namespaces, including Avalara codes, to active ITMS tax codes.

Persistence

Read-only.

Auth

API key · scope tax:calculate

Request

Optional source_system filter; the authenticated key determines organization/location scope

Response

Organization and location mappings with target ITMS code and audit timestamps

Create or replace a line-level caller tax-code mapping.

Persistence

Persists a tenant-owned mapping. A location mapping overrides the organization default.

Auth

API key · scope transactions:write · organization/location authorization enforced

Request

Target itms_tax_code, optional location_id, and optional description

Response

The active deterministic mapping used by calculate and transaction routes

Remove a caller tax-code mapping so later use of that source code fails closed.

Persistence

Deletes only the authorized organization/location mapping.

Auth

API key · scope transactions:write

Request

Optional location_id query parameter

Response

204 No Content

Calculate tax and apply the reviewed result to a supported provider draft before provider confirmation.

Persistence

Creates an auditable provider binding. The provider mutation requires a distinct Idempotency-Key and never follows from calculation authority alone.

Auth

API key · scopes tax:calculate and transactions:write · provider profile authorization enforced

Request

Provider draft reference, calculation request, connection binding, and Idempotency-Key header

Response

Calculated result, provider application result, binding identity, lifecycle status, and idempotent replay state

Discover governed capabilities available to the service account in its exact tenant, location, and provider context.

Persistence

Read-only discovery; it grants no additional authority.

Auth

API key · scope capabilities:read

Request

Optional location_id for an organization-scoped key; provider keys may supply an authorized client context

Response

Organization, resolved location, and capability definitions including authority and approval policy

Execute an authorized governed capability with durable idempotency and action evidence.

Persistence

Persists the governed action and exact result. Capabilities requiring human-exact approval are rejected for service-account execution.

Auth

API key · scope capabilities:invoke · capability-specific policy enforced

Request

location_id when required, capability input object, and caller idempotency_key

Response

Action ID, status, capability ID, result, and idempotent-replay indicator

Apply an authorized compensating action to a prior governed capability action.

Persistence

Creates a new auditable compensating action; it does not erase the original action or evidence.

Auth

API key · scope capabilities:invoke · original action scope and undo policy enforced

Request

location_id when required and a caller idempotency_key

Response

Compensating action ID, status, capability ID, result, and idempotent-replay indicator

Inspect tenant-scoped request, batch, and webhook queue health.

Persistence

Read-only.

Auth

Any authenticated API key

Request

No body

Response

API version/environment and tenant-only backlog or stale-work signals

Validate, normalize, and geolocate a US address before calculation.

Persistence

Caches provider resolution for efficient reuse; creates no tax transaction.

Auth

API key · scope transactions:read

Request

Address fields plus optional latitude / longitude caller context

Response

Normalized address, state, ZIP/ZIP+4, county, precision, geocode, provider, and messages

Read the provider filing portfolio with the same calculation facts, stages, and filing holds as Provider Console.

Persistence

Read-only. Production portfolio only; sandbox preparation uses return-jobs. Active client relationships and provider-key governance determine visibility.

Auth

Production provider API key · scope provider:return-jobs:read

Request

Optional client_org_id and state query filters; filters can only narrow the authorized client portfolio

Response

service_provider_id, items, total, and environment; each item carries its exact client and filing context

Prepare or explicitly refresh a governed batch of filing packages through the same workflow as Provider Console.

Persistence

Creates an auditable batch and preparation work. It does not grant filing, remittance, or approval authority. Production only.

Auth

Production provider API key · scope provider:return-jobs:write · governed provider authority enforced

Request

Optional client_org_ids and states filters, refresh_existing, and up to 10,000 exact work_items; explicit refresh requires work_items. Idempotency-Key is supported.

Response

HTTP 202 with batch_id, service_provider_id, status, progress_pct, created, child_count, children, requested_states, and created_at

Read a provider preparation batch and the status of its child work.

Persistence

Read-only. Requires access to the batch and its authorized client relationships; inaccessible batches return 404.

Auth

Production provider API key · scope provider:return-jobs:read

Request

Path param: batch_id

Response

Batch identity, status, progress_pct, created, child_count, children, requested_states, and created_at

List taxpayer engagements owned by the authenticated service provider.

Persistence

Read-only. Prefer client_context_ref in X-ITMS-Client-Ref; client_context_id remains available for X-ITMS-Client-Id.

Auth

Provider API key · scope provider:clients:read

Request

Query params: optional status; limit (1–500); offset

Response

Explicit external and numeric client-context values, canonical organization identity, status, and total

Idempotently onboard a taxpayer using the canonical Organization and Location tenancy model.

Persistence

Creates an ordinary taxpayer organization, active provider engagement, and optional primary location. external_client_id is idempotent within the provider.

Auth

Provider API key · scope provider:clients:write

Request

external_client_id, taxpayer name and identity fields, optional primary_location

Response

client_context_ref, client_context_id, canonical organization ID, status, identity, and locations

Read one provider-authorized taxpayer and its canonical locations.

Persistence

Read-only.

Auth

Provider API key · scope provider:clients:read

Request

Path param: provider client engagement id

Response

Engagement, canonical organization, and location details

Update taxpayer identity or pause/offboard the provider engagement.

Persistence

Updates normal organization fields. Engagement status changes never deactivate or delete the taxpayer organization or locations.

Auth

Provider API key · scope provider:clients:write

Request

Any mutable taxpayer identity fields and/or status active | paused | offboarded

Response

Updated client and canonical tenant details

List canonical locations for one authorized taxpayer.

Persistence

Read-only.

Auth

Provider API key · scope provider:clients:read

Request

Path param: provider client engagement id

Response

Canonical organization locations

Create an ordinary application location for an active taxpayer engagement.

Persistence

Creates a canonical Location row that is also visible in the normal Prophit UI.

Auth

Provider API key · scope provider:clients:write

Request

Location name, identity, address, and contact fields

Response

Canonical location

Update or deactivate a location owned by the selected taxpayer.

Persistence

Updates the canonical location.

Auth

Provider API key · scope provider:clients:write

Request

Mutable location identity, address, contact, and is_active fields

Response

Updated canonical location

Explain whether client setup supports calculations and return preparation.

Persistence

Read-only and advisory; it does not claim tax accuracy where setup is incomplete.

Auth

Provider API key · scope provider:clients:read

Request

Path param: provider client engagement id

Response

Calculation/return readiness plus identity, location, registration, obligation, and return-account checks

Queue return-preparation worksheets across up to 5,000 independent taxpayer/state periods.

Persistence

Durable asynchronous job. Each item succeeds or fails independently and generated packages remain in the taxpayer tenant.

Auth

Provider API key · scope provider:return-jobs:write

Request

idempotency_key and items[] with reference_id, client_id, state, period, frequency, and optional account_profile_id

Response

202 job manifest with durable id and counters

Poll portfolio return output and per-item results.

Persistence

Read-only; polling can recover queued or stale work.

Auth

Provider API key · scope provider:return-jobs:read

Request

Path param: provider return job id

Response

Per-client gross, exempt, and taxable sales; tax and remittance totals; setup blockers; validation; lines; and artifact download paths

Record an already-issued customer registration and activate filing for one client state.

Persistence

Writes the registration, obligation timeline, and state account profile in the taxpayer tenant. Never registers the customer with a state.

Auth

Provider API key · scopes provider:clients:write and returns:write

Request

filing_frequency, optional registration_number/date, account_key/name/fields, and forward/back return generation flags

Response

Registration id/status, filing frequency, and generated return counts

Record existing registrations and activate filing for up to 100 provider client/state accounts in one atomic control-plane request.

Persistence

Atomic across the entire batch: every item writes the canonical registration, obligation timeline, and state account profile in its taxpayer tenant, or no item changes. Never registers a customer with a state.

Auth

Provider API key · scopes provider:clients:write and returns:write

Request

idempotency_key and up to 100 items[] with provider client engagement id, state, optional location, filing cadence, registration data, obligation start, and forward/back draft-return controls. Use asynchronous return jobs for high-volume workpaper generation.

Response

Configured and generated-return totals plus ordered per-item client/state results

List the provider's per-client (and per-client-per-state) reviewer/approver role defaults for one client.

Persistence

Read-only.

Auth

Provider API key · scope provider:workflow:read

Request

Path param client id; optional module query (default sales)

Response

Role assignment rows with user, optional state scope, and whether each is a provider or taxpayer default

Upsert a provider client-wide or client-and-state reviewer/approver default.

Persistence

Provider assignments are client-wide; a null user_id clears the assignment. Location-level defaults remain the taxpayer’s own configuration.

Auth

Provider API key · scope provider:workflow:write

Request

role, user_id (or null), optional state_code and module

Response

Updated list of role assignment rows for the client

List the provider default and any per-client internal data-deadline policies.

Persistence

Read-only.

Auth

Provider API key · scope provider:workflow:read

Request

No body

Response

Policy rows with id, client scope, days_before_due, and is_active

Set the provider default or a per-client override for internal data-deadline reminders.

Persistence

Upserts one policy row; a null days_before_due removes it.

Auth

Provider API key · scope provider:workflow:write

Request

Optional client_id (omit for the provider default) and days_before_due or null

Response

Updated policy list

Record evidence that a client's period data was received, behind the provider timeliness disclaimer.

Persistence

Creates a durable receipt record; does not itself change return or workflow state.

Auth

Provider API key · scope provider:workflow:write

Request

period_start, period_end, optional received_at and note

Response

Recorded receipt id, period, received_at, and source

Read a client return package's review/approval workflow state.

Persistence

Read-only; resolves the package through the provider engagement before returning any state.

Auth

Provider API key · scope provider:workflow:read

Request

Path param: return package id

Response

Status, submitted/review-completed/decided timestamps, rejection reason, approved_via, approval_package_id, and lock state

Submit a client return package into the review workflow.

Persistence

Advances the package review state machine.

Auth

Provider API key · scope provider:workflow:write

Request

Path param: return package id

Response

Updated workflow state

Complete reviewer tick-and-tie on a client return package (gated).

Persistence

Advances the package review state machine.

Auth

Provider API key · scope provider:workflow:write

Request

Path param: return package id

Response

Updated workflow state

Send a client return package back to the preparer.

Persistence

Advances the package review state machine.

Auth

Provider API key · scope provider:workflow:write

Request

reason

Response

Updated workflow state

Reopen an approved client return package for material correction.

Persistence

Unlocks the package, supersedes any active approval link, and requires re-review plus reapproval.

Auth

Provider API key · scope provider:approvals:write

Request

reason

Response

Updated workflow state

Create a client-facing approval package linking one or more reviewed return packages.

Persistence

Creates a durable, expiring, token-secured approval package in the taxpayer tenant.

Auth

Provider API key · scope provider:approvals:write

Request

client_id, return_package_ids[], recipient_name, optional recipient_email/provider_note/ttl_hours/approval_request_id

Response

Package id/status/expiry plus the portal URL and raw token exactly once (idempotent replays by approval_request_id omit the token)

Read one client approval package and its current status.

Persistence

Read-only.

Auth

Provider API key · scope provider:approvals:read

Request

Path param: approval package id

Response

Status, token prefix, expiry, recipient, view/decision timestamps, decision name/feedback, and linked return package ids

Revoke a client approval package before it is decided.

Persistence

Invalidates the outstanding token; the client-facing link stops working.

Auth

Provider API key · scope provider:approvals:write

Request

Path param: approval package id

Response

Updated id and status

Create or replace a durable item-code mapping before product tax treatment.

Persistence

Persists a catalog SKU in the API key organization/location scope; the supplied category is not authoritative state rate-class evidence by itself.

Auth

API key · scope transactions:write

Request

name; optional description and taxabilityCategory

Response

itemCode, catalog fields, productClassificationStatus, trustedProductClass when ready, location or organization scope, and timestamps

Fetch one product item mapping visible to the current API key.

Persistence

Read-only.

Auth

API key · scope transactions:read

Request

Path param: item_code

Response

The item mapping, classification status, trusted product class when ready, scope, and timestamps

List product mappings visible to the current API key.

Persistence

Read-only.

Auth

API key · scope transactions:read

Request

Query params: limit (1–500) and offset

Response

items[] plus count, limit, and offset

Create or replace the customer identity used by calculations and certificate selection.

Persistence

Persists identity and address fields in the API key scope. Exemption status and certificate assignment are read-only here.

Auth

API key · scope transactions:write

Request

name; optional line1, line2, city, state, postalCode, and country

Response

customerCode, address, exemptionCertificateStatus, active certificate code when assigned, scope, and timestamps

Fetch one customer identity mapping visible to the current API key.

Persistence

Read-only.

Auth

API key · scope transactions:read

Request

Path param: customer_code

Response

Customer identity, address, exemption certificate status, active certificate code, scope, and timestamps

List customer mappings visible to the current API key.

Persistence

Read-only.

Auth

API key · scope transactions:read

Request

Query params: limit (1–500) and offset

Response

items[] plus count, limit, and offset

Assign an active, currently effective certificate to its customer.

Persistence

Updates the ordinary customer record used by API and UI calculations.

Auth

API key · scope transactions:write

Request

certificateCode

Response

Assigned certificate record

Remove a customer certificate assignment.

Persistence

Removes the assignment without deleting the certificate or its audit history.

Auth

API key · scope transactions:write

Request

No body

Response

204 No Content

Calculate US sales tax for one or more lines.

Persistence

Stateless — persists nothing; always safe to retry.

Auth

API key · scope tax:calculate

Request

transaction_date, ship_to, lines[]; optional customer_code, ship_from, bill_to, currency, discount, validation_mode, calculation_type. Supported fact-aware treatments may accept lines[].qualifying_use_percentage (0–100) when the caller has the required documentation. Texas remote sellers may explicitly send tx_single_local_use_tax_rate_elected=true after making that election; ITMS never infers it.

Response

Sales tax returns liability_basis=gross_expected_tax. calculation_type=consumer_use|vendor_use|reverse_charge (or legacy use_tax=true for consumer use only) returns expected tax, tax paid, and net use-tax liability. A seller-imposed tax such as Hawaii GET returns liability_basis=seller_gross_receipts with tax_incidence=seller_gross_receipts, no buyer tax, and the seller amount in total_seller_liability_tax. All modes include per-line jurisdiction metadata and warnings.

Alias of /tax/calculate for quote-style integrations.

Persistence

Stateless — identical behavior to /tax/calculate.

Auth

API key · scope tax:calculate

Request

Same as /tax/calculate

Response

Same as /tax/calculate

Calculate consumer-use or direct-pay reverse-charge liability against vendor tax paid.

Persistence

Stateless — persists nothing; always safe to retry. After shared product and jurisdiction resolution, taxable base, effective rate, rounding, tax-paid credit, tolerance, and liability use the canonical Purchasing Tax Compliance decision seam.

Auth

API key · scope tax:calculate

Request

Calculation payload with calculation_type=consumer_use|vendor_use|reverse_charge and optional lines[].tax_paid. Reverse charge requires reverse_charge_basis and direct-pay requests require the permit number. New integrations should use this dedicated route; /tax/calculate accepts the same modes for migration compatibility.

Response

liability_basis=net_use_tax_due; expected tax, vendor tax paid, use tax due, overpayment, and jurisdiction detail by line and document

Queue up to 500 independently isolated deterministic calculations.

Persistence

Durably persists batch state and per-item results; creates no tax transactions.

Auth

API key · scope tax:calculate · separate 10/minute submission bucket

Request

items[] containing a unique reference_id and a normal calculation request

Response

Batch ID, queue state, counts, timestamps, and eventual per-reference result or error

Poll a durable calculation batch and recover abandoned queued work.

Persistence

Read-only except safe re-enqueue of queued or stale processing work.

Auth

API key · exact organization, location, and environment scope

Request

Path param: batch_id returned by queueing

Response

Queued, processing, completed, or failed state with per-item results when available

Record a committed transaction with ITMS-calculated or explicitly preserved caller tax.

Persistence

Persists the transaction in the key’s environment. By default ITMS calculates tax; tax_override preserves an exact caller-calculated amount without invoking the tax engine.

Auth

API key · scope transactions:write

Request

Everything /tax/calculate accepts, plus code, document_type, commit, and optional type. For a committed sales_invoice, optional tax_override { type: "tax_amount", tax_amount, reason } preserves supplied tax. Send Idempotency-Key on retries.

Response

The committed transaction: code, type, status, environment, totals, per-line tax, tax_override when used, and created_at

Create a committed invoice or atomically revision-adjust the active document behind the same logical code.

Persistence

Creates an immutable reversal and replacement when the business payload changes; identical retries replay the matching revision.

Auth

API key · scope transactions:write

Request

Committed transaction payload plus optional adjustmentReason. Send a stable Idempotency-Key on retries.

Response

The created or active replacement transaction, including revision lineage and idempotent_replay.

List saved sales orders and purchase orders.

Persistence

Read-only; saved documents remain isolated from compliance until committed.

Auth

API key · scope transactions:read

Request

Query params: status (saved | committed | cancelled), limit, offset

Response

Saved document payloads, calculations, status, and committed transaction code when applicable

List API-created transactions for the key’s scope.

Persistence

Read-only.

Auth

API key · scope transactions:read

Request

Query params: from / to (transaction_date filters), status, limit (1–200, default 50), offset

Response

items[] of transactions plus total, limit, offset

Fetch a single transaction by the code you supplied at creation.

Persistence

Read-only.

Auth

API key · scope transactions:read

Request

Path param: code

Response

The full transaction, identical shape to the create response

Commit a saved sales or purchase order as an invoice.

Persistence

Atomically creates the compliance transaction and links the saved document.

Auth

API key · scope transactions:write

Request

Path param: saved document code

Response

The committed sales_invoice or purchase_invoice transaction

Cancel an uncommitted saved order.

Persistence

Marks only the isolated saved document cancelled; idempotent.

Auth

API key · scope transactions:write

Request

Path param: saved document code

Response

The saved document with status 'cancelled'

Cancel a committed transaction before it feeds compliance workflows.

Persistence

Marks the transaction voided (idempotent); voided transactions are excluded from filings, nexus, and reporting.

Auth

API key · scope transactions:write

Request

Optional body: reason

Response

The transaction with status 'voided' and voided_at

Create a refund linked to the original transaction (full or partial).

Persistence

Persists a new refund transaction linked via parent_code; the original is never mutated beyond its status.

Auth

API key · scope transactions:write

Request

code (the refund's own code), optional lines [{number, amount}] for partial refunds, optional tax_date

Response

The refund transaction; the original moves to partially_refunded or refunded

Atomically reverse a committed sale and create its replacement revision.

Persistence

Persists a full linked reversal and a separately linked replacement; a failed preflight changes nothing.

Auth

API key · scope transactions:write

Request

refund_code, reason, and replacement (a complete type=sale transaction payload with its own code)

Response

original_code plus the committed refund and replacement; replacement exposes revision_of_code and revision_number

Reverse selected committed tax without reversing gross or taxable sales.

Persistence

Persists a credit revision with zero taxable base and original-line responsibility and jurisdiction lineage.

Auth

API key · scope transactions:write

Request

code, reason, and lines [{number, tax_amount}]; credit cannot exceed remaining committed tax

Response

The committed credit with document_type tax_only_credit and revision lineage

Audit-replay a committed transaction from its persisted inputs and responsibility.

Persistence

Read-only: returns persisted and freshly recalculated views and writes no transaction or revision.

Auth

API key · scope transactions:read

Request

Path param: code

Response

persisted, recalculated, and tax_delta so later content drift is explicit

List states that currently expose a return-package profile.

Persistence

Read-only.

Auth

API key · scope returns:read

Request

No body

Response

State codes and profile availability for return-package preparation

List effective-dated multi-location filing units owned by the taxpayer organization.

Persistence

Read-only. Group members are ordinary ITMS locations and remain portable outside a provider relationship.

Auth

Organization-scoped API key · scope returns:read

Request

Optional state filter

Response

Filing groups, exact member locations, linked jurisdiction accounts, effective dates, and version

Create one effective-dated return filing unit from several authorized locations.

Persistence

Persists a versioned group; overlapping location membership is rejected.

Auth

Organization-scoped API key · scope returns:write

Request

State, name, member location_ids, optional effective_from, and optional account_profile_ids

Response

The created filing group and immutable version metadata

Change future multi-location membership without rewriting a filed period.

Persistence

Closes the old group version and creates a successor effective on the requested date.

Auth

Organization-scoped API key · scope returns:write

Request

Successor name, location_ids, required effective_from, and optional account_profile_ids

Response

The successor filing-group version with historical lineage preserved

End a filing group after its final applicable period.

Persistence

Sets the group effective end date; existing package snapshots are unchanged.

Auth

Organization-scoped API key · scope returns:write

Request

effective_from date on which the group stops being active

Response

The closed filing-group version

Cancel a scheduled filing-group dissolution before its effective boundary.

Persistence

Applies a governed compensating action and preserves the original action history.

Auth

Organization-scoped API key · scope returns:write

Request

Path param: group_id

Response

The restored active filing-group version

Update a filing group that has not yet become effective.

Persistence

Updates the governed future group only after an exact state-hash preview; effective history remains immutable.

Auth

Organization-scoped API key · scope returns:write

Request

Optional group name, authorized locations, and account-profile bindings

Response

The updated future filing group

Archive a filing group that has not yet become effective.

Persistence

Archives the future configuration through a governed compensating-action-capable workflow; filed or effective evidence is never deleted.

Auth

Organization-scoped API key · scope returns:write

Request

Path param: group_id

Response

204 No Content

Synchronize the complete verified CDTFA registered-location set used for Schedule C.

Persistence

Atomically replaces the current active set for one CA jurisdiction account while retaining audit timestamps.

Auth

Organization-scoped API key · scope returns:write

Request

CA account_profile_id, source, filing period, and site_number/tax_area_code/address rows

Response

The normalized registered-location set and synchronization provenance

Read the synchronized CDTFA sites that will populate Schedule C.

Persistence

Read-only.

Auth

Organization-scoped API key · scope returns:read

Request

account_profile_id

Response

Active registered sites, tax-area codes, addresses, effective dates, source, and verification time

Inspect the supported fields, mappings, rules, and artifacts for a state return package.

Persistence

Read-only.

Auth

API key · scope returns:read

Request

Path param: two-letter state code

Response

State profile detail describing the preparation contract

List state account profiles authorized for the API key scope.

Persistence

Read-only.

Auth

API key · scope returns:read

Request

Optional state and location filters

Response

Jurisdiction account profiles and filing-unit identity

Create a state account profile used to scope return-package preparation.

Persistence

Persists account identity and filing settings; it stores no portal password or filing credential.

Auth

API key · scope returns:write · organization/location authorization enforced

Request

State, filing unit/location, account identity, frequency, and supported profile fields

Response

The created jurisdiction account profile

Create or retrieve the active return package for a state, period, frequency, and account scope.

Persistence

Persists an idempotent preparation package and its transaction aggregation; creates no government filing.

Auth

API key · scope returns:write

Request

State, filing period, frequency, jurisdiction account, and authorized filing location

Response

Package detail, preparation status, sales-tax totals, separate use-tax/RDF/B&O/Schedule C outputs, validations, and artifact summary

List return packages visible to the current API key.

Persistence

Read-only.

Auth

API key · scope returns:read

Request

Optional state, period, status, location, limit, and offset filters

Response

Paginated return-package summaries

Fetch return-package detail, including current preparation and external-filing bookkeeping state.

Persistence

Read-only.

Auth

API key · scope returns:read · package scope enforced

Request

Path param: package_id

Response

Package detail, sales-tax totals, separate use-tax/RDF/B&O/Schedule C outputs, validations, artifacts, and lifecycle timestamps

List files generated for a return package.

Persistence

Read-only.

Auth

API key · scope returns:read · package scope enforced

Request

Path param: package_id

Response

Artifact identifiers, names, media types, sizes, and generation timestamps

Download one generated return-package artifact after package and artifact authorization checks.

Persistence

Read-only download; does not submit the artifact.

Auth

API key · scope returns:read · package and artifact scope enforced

Request

Path params: package_id and artifact_id

Response

Artifact bytes with the generated media type and filename

Re-aggregate an unfiled package over the current eligible transactions.

Persistence

Updates the preparation package and regenerates applicable artifacts; filed packages are immutable.

Auth

API key · scope returns:write

Request

Path param: package_id

Response

Refreshed package detail and validations

Create an amended successor to a filed return package.

Persistence

Persists a successor package without mutating the filed package or its evidence.

Auth

API key · scope returns:write

Request

Path param: package_id

Response

The new amendment package with lineage to the filed predecessor

Record that the customer filed a prepared return through an external process.

Persistence

Bookkeeping only: records the external event. ITMS sends nothing to the state and moves no money.

Auth

API key · scope returns:write

Request

External filing date, method, reference, and optional note

Response

Package detail with the recorded external-filing state

Record jurisdiction confirmation for a filing completed outside ITMS.

Persistence

Bookkeeping only; retains the confirmation reference and timestamp.

Auth

API key · scope returns:write

Request

Confirmation reference, confirmation date, and optional note

Response

Package detail with confirmation state

Read a return package's review/approval workflow state.

Persistence

Read-only.

Auth

API key · scope workflow:read

Request

Path param: return package id

Response

Status, submitted/review-completed/decided timestamps, rejection reason, approved_via, and lock state

Submit a return package into the review workflow.

Persistence

Advances the package review state machine.

Auth

API key · scope workflow:write

Request

Path param: return package id

Response

Updated workflow state

Complete reviewer tick-and-tie on a return package (gated).

Persistence

Advances the package review state machine.

Auth

API key · scope workflow:write

Request

Path param: return package id

Response

Updated workflow state

Send a return package back to the preparer.

Persistence

Advances the package review state machine.

Auth

API key · scope workflow:write

Request

reason

Response

Updated workflow state

Approve a reviewed return package, locking the version.

Persistence

Advances the package review state machine and locks the approved version.

Auth

API key · scope workflow:approve

Request

Path param: return package id

Response

Updated workflow state

Reopen an approved return package for material correction.

Persistence

Unlocks the package and requires re-review plus reapproval. Separate scope from submit/complete/request-changes so orgs can enforce machine separation of duties.

Auth

API key · scope workflow:approve

Request

reason

Response

Updated workflow state