# Set up returns with generic DOR access overview

Source: https://developer.avalara.com/products/returns/integration-guides/managed-returns/rxt2028644176415/

Guide: Avalara Managed Returns API (U.S. and Canada)

# Set up returns with generic DOR access overview

Learn how Generic DOR Access automates returns onboarding, from validating tax authority credentials to approving filing requests.

Generic DOR Access automates the returns setup onboarding process. Instead of manually entering registration details and selecting forms for each jurisdiction, a company provides the credentials it uses on a tax authority portal. Avalara validates the sign-in and 2-factor authentication (2FA). Then, a background task extracts the company registrations into pending filing requests. After you review and approve the filing requests, they become active filing calendars.

Key capabilities include:

-   **Discover authorities**: Check which tax authorities a company can onboard with, whether 2FA is required, and the current access status.
-   **Grant access**: Submit portal credentials once. Avalara validates the sign-in and 2FA, and starts the background returns extraction.
-   **Track extraction**: Poll the background task until it finishes and returns the filing requests created from the extracted data.
-   **Resume an onboarding session**: Recover saved accounts and retry an in-flight job without requiring the user to reenter credentials.
-   **Approve filing requests**: Convert extracted pending filing requests into active filing calendars.

## Generic DOR Access workflow

The automated onboarding process includes these steps:

1.  **Discover tax authorities**: Call the authorities query for the company, country, and region. The response returns available DOR authorities, their access status, the 2FA requirement flag, and supported tax form codes. For details, see [Discover tax authorities](/managed-returns/kow8302325542211/ "View the authorities query, input variables, response fields, and access status values for discovering available tax authority portals for a company.").

2.  **Set up company 2-factor authentication** (if required): If a tax authority requires 2FA, configure the company forwarding email by using the company 2FA operations. Avalara assigns an alias email address for the company to receive security verification codes sent by the tax authority. For details, see [Company-level two-factor authentication](/managed-returns/rty9684532390671/ "Learn how company-level two-factor authentication (2FA) works and how Avalara routes security codes during tax authority onboarding.").

3.  **Grant authority access**: Call the `grantAuthorityAccess` mutation with the portal credentials. Avalara validates the sign-in and 2FA with the tax authority portal, and starts a background extraction task. If validation fails, review the failure reason and ask the user to provide updated credentials. For details, see [Grant authority access and trigger extraction](/managed-returns/skf6239163889825/ "Submit portal credentials for a tax authority, validate credentials and 2-factor authentication, and start background return extraction by using the grantAuthorityAccess GraphQL mutation.").

4.  **Monitor extraction task status**: Periodically poll the `taskStatus` query, for example, every 30 seconds, by using the task IDs returned from the grant step. Continue polling until all tasks reach a terminal status of **SUCCESS** or **FAILED**. Tasks that finish with a **SUCCESS** status return the IDs of the created filing requests. For details, see [Monitor extraction task status](/managed-returns/fcy1877890471345/ "Check the status of 1 or more background return extraction tasks with the taskStatus GraphQL query.").

5.  **Query saved authority accounts** (optional): If a user leaves the onboarding workflow before completion, call the `savedAuthorityAccounts` query to retrieve the saved username and portal URL for any in-flight jobs. For details, see [Query saved authority accounts](/managed-returns/apn4585095333300/ "Retrieve saved authority usernames and portal URLs for in-flight onboarding jobs with the savedAuthorityAccounts GraphQL query.").

6.  **Resume an in-flight session** (optional): If a user leaves the onboarding workflow before completion, call `savedAuthorityAccounts` to retrieve the saved username. Then call `resumeAuthorityAccess` to retry the job by using the stored credentials. For details, see [Resume authority onboarding session](/managed-returns/gfx1144966310754/ "Resume in-flight onboarding jobs with saved credentials by using the resumeAuthorityAccess GraphQL mutation.").

7.  **Review and approve filing requests**: Call `filingCalendarRequests` to review the extracted filing requests in Pending status. If needed, call `updateFilingCalendarRequest` to modify answers before approval. After you verify the requests, call `approveFilingRequests` with the filing request IDs to convert them into active filing calendars. For details, see [Approve extracted filing requests](/managed-returns/why7129607850668/ "Approve extracted pending filing requests and convert them into active filing calendars by using the approveFilingRequests GraphQL mutation.").

**Key considerations**

Keep these points in mind when you implement Generic DOR Access:

-   **Validation duration**: The `grantAuthorityAccess` mutation waits for a live sign-in and 2FA validation on the authority portal, which can take up to 4 minutes. Set your client timeout accordingly.
-   **Extraction duration**: Background extraction runs asynchronously and can take several minutes to complete. Poll the `taskStatus` query instead of holding a single connection open.
-   **Credential security**: Passwords are write only. They’re transmitted to the tax authority for validation and are never returned in queries or responses.
-   **Duplicate extraction prevention**: If an authority already has access granted, `grantAuthorityAccess` validates credentials but does not trigger a duplicate extraction.
-   **Supported tax types**: These operations currently apply to U.S. Sales and Use tax workflows.