# API workflows

Source: https://developer.avalara.com/transaction-reconciliation/nud4641063434676/

# 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.

1.  Get filing period dates:

    ```
    GET /api/v2/companies/{companyId}/filingcalendars
    ```

    → Determine current period boundaries

2.  Query AvaTax transaction totals:

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

3.  Compare with ERP totals (partner-provided).

4.  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.

1.  **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`.

2.  Poll for completion:

    ```
    GET /api/v2/reports/{reportId}
    ```

    → Check `status` until "Completed"

3.  Download CSV:

    ```
    GET /api/v2/reports/{reportId}/attachment
    ```

    → Rate limit: 5 calls per minute

4.  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:

1.  Fetch all AvaTax transactions for the period with pagination (`$top=1000`).

2.  Get ERP transactions (partner-provided).

3.  Match by document code and identify matched, missing from AvaTax, and missing from ERP.

4.  For mismatches, compare: `totalAmount`, `totalTax`, `status`, `customerCode`, and `addresses`.

5.  For missing from AvaTax, check the audit trail:

    ```
    GET /api/v2/accounts/{accountId}/audit
    ```

6.  Categorize discrepancies by root cause.

7.  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

1.  When a user approves a creation:

2.  Log approval (user, timestamp, reason, transaction details).

3.  Create a transaction:

    ```
    POST /api/v2/transactions/create
    ```

    Include `description`: "Created via AI Reconciliation - \[reason\]"

4.  Handle response (success or error).

5.  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.