API workflows

This section describes the recommended API strategy and reconciliation workflows used during AI-assisted transaction reconciliation.

Recommended API strategy

Choose the appropriate API approach based on your reconciliation use case.


Use Case	Recommended API	Why
Daily quick check	`GET /api/v2/companies/{code}/transactions?$include=Summary`	Real-time data, lightweight response, fast aggregate totals
Monthly bulk reconciliation	`POST /api/v2/companies/{id}/reports/exportdocumentline/initiate`	Async bulk export, no pagination limits, CSV download
Individual investigation	`GET /api/v2/companies/{code}/transactions/{transactionCode}`	Full transaction detail with $include=TaxDetailsByTaxType
Cross-Border variance	`GET /api/v2/companies/{code}/AllVariance`	Customs-specific: calculated vs. actual duty/tax paid
Resolution actions	`Create/Adjust/Void/Refund APIs`	Modify transactions after user approval

Important

AvaTax UI reports update every 30 minutes. For real-time data, use the Transactions API directly. For bulk reconciliation where a 30-minute delay is acceptable, the ExportDocumentLine Report API is more efficient.

Daily aggregate check

Use this approach for quick daily monitoring of ERP-to-AvaTax alignment.

Get filing period dates:
```
GET /api/v2/companies/{companyId}/filingcalendars
```
→ Determine current period boundaries

Query AvaTax transaction totals:

GET /api/v2/companies/{companyCode}/transactions
$filter=date ge '2025-11-01' and date le '2025-11-30'
$include=Summary

Compare with ERP totals (partner-provided).
If the variance exceeds the threshold, generate an alert with a summary.

Bulk reconciliation via ExportDocumentLine report

For monthly or period-end deep reconciliation, use the async Report API to avoid pagination limits.

Initiate report:

POST /api/v2/companies/{companyId}/reports/exportdocumentline/initiate

{
  "format": "CSV",
  "startDate": "2025-11-01",
  "endDate": "2025-11-30",
  "country": "US",
  "state": "ALL",
  "dateFilter": "DocumentDate",
  "docType": "Sales",
  "documentStatus": "Committed"
}

Returns reportId.

Poll for completion:
```
GET /api/v2/reports/{reportId}
```
→ Check status until "Completed"
Download CSV:
```
GET /api/v2/reports/{reportId}/attachment
```
→ Rate limit: 5 calls per minute
Parse and compare with ERP export.

Large datasets:

For reports with 100K or more transactions, use numberOfPartitions (2–250) to split the report. Generate each partition separately and merge client-side.

ExportDocumentLine filter options:

dateFilter: DocumentDate, ModifiedDate, PaymentDate, ReportingDate, TaxDate
documentStatus: Saved, Posted, Committed, Canceled, Uncommitted
docType: Sales, ConsumerUse
isLocked: true or false
country: "U.S.," "ALL," "ALL Non-US," or ISO country code
state: "ALL" or 2-character state code

Detailed transaction investigation

When investigating a specific discrepancy:

Fetch all AvaTax transactions for the period with pagination ($top=1000).
Get ERP transactions (partner-provided).
Match by document code and identify matched, missing from AvaTax, and missing from ERP.
For mismatches, compare: totalAmount, totalTax, status, customerCode, and addresses.
For missing from AvaTax, check the audit trail:
```
GET /api/v2/accounts/{accountId}/audit
```
Categorize discrepancies by root cause.
Generate recommendations and present to the user.

Cross-border variance API

The Variance API is designed specifically for cross-border and customs transactions where actual duties and taxes paid at customs clearance may differ from initial calculations.

Get all variance data for a company:
```
GET /api/v2/companies/{companyCode}/AllVariance
```
→ Returns variance data for all cross-border transactions
Get variance for a specific transaction:
```
GET /api/v2/companies/{companyCode}/transactions/{transactionId}/variance
```
→ Returns calculated duty and tax versus actual paid amounts
Generate variance report:
```
POST /api/v2/companies/{companyCode}/variance
```
→ Input actual duty and tax paid; receive variance analysis

Attention

The Variance API isn’t for general ERP-to-AvaTax reconciliation. It specifically tracks customs clearance variances for international shipments. For domestic ERP reconciliation, use the Transactions API or ExportDocumentLine Report API.

Resolve missing transaction

When a user approves a creation:
Log approval (user, timestamp, reason, transaction details).
Create a transaction:
```
POST /api/v2/transactions/create
```
Include description: "Created via AI Reconciliation - [reason]"
Handle response (success or error).

Verify creation:

GET /api/v2/companies/{code}/transactions/{code}

Tip

Use POST /api/v2/transactions/createoradjust for idempotent transaction creation that won’t fail on duplicates.