# Discover tax authorities

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

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

# Discover tax authorities

View the authorities query, input variables, response fields, and access status values for discovering available tax authority portals for a company.

The authorities query returns the Department of Revenue (DOR) tax authorities that are available to a company in a specified country and region. For each tax authority, the response includes supported tax form codes, whether 2-factor authentication (2FA) is required, the current onboarding access status, and any active background extraction tasks.

There is 1 entry for each tax authority portal. The `id` and `portalUrl` fields represent the authority website address. To grant access in later steps, pass the value of the `name` field to the `grantAuthorityAccess` mutation.

## View request

```
query Authorities($companyId: ID!, $country: String!, $region: String, $includeDetails: Boolean) {
  authorities(companyId: $companyId, country: $country, region: $region, includeDetails: $includeDetails) {
    id
    name
    portalUrl
    country
    region
    authMechanism
    accessStatus
    isTwoFactorAuthRequired
    supportedFormCodes
    activeTasks {
      taskId
      formCode
      status
      message
      dateCreated
      dateCompleted
      filingRequestIds
      generatedTaxFormCodes
    }
  }
}
```

**Input variables**:

```
{
  "companyId": "1234567",
  "country": "US",
  "region": "AL",
  "includeDetails": true
}
```

Table 1. Input variable details

Argument

Type

Description

`companyId`

`ID!`

The company to look up.

`country`

`String!`

The 2-character ISO 3166 country code.

`region`

`String`

The 2-character or 3-character ISO 3166 region or state code.

`includeDetails`

`Boolean`

Specifies whether to include extraction tasks in `activeTasks`. The default is `true`.

## View response

```
{
  "data": {
    "authorities": [
      {
        "id": "https://myalabamataxes.alabama.gov/_/",
        "name": "Alabama Department of Revenue",
        "portalUrl": "https://myalabamataxes.alabama.gov/_/",
        "country": "US",
        "region": "AL",
        "authMechanism": "CREDENTIAL_SCRAPE",
        "accessStatus": "ACCESS_GRANTED",
        "isTwoFactorAuthRequired": true,
        "supportedFormCodes": [
          "USAL2100",
          "USAL2410",
          "USAL2620",
          "USAL2630",
          "USAL9501",
          "USALSU2610"
        ],
        "activeTasks": [
          {
            "taskId": "aaaaaaaa-0000-4000-8000-000000000002",
            "formCode": "USALSU2610",
            "status": "Success",
            "message": null,
            "dateCreated": "2026-01-15T09:23:57.394736",
            "dateCompleted": "2026-01-15T10:00:10.036327",
            "filingRequestIds": ["200001"]
            “generatedTaxFormCodes”: [“USALSU2610“]
          }
        ]
      }
    ]
  }
}
```

**Response field descriptions**:

Response field

Description

`id`

The tax authority portal URL.

`name`

The tax authority display name. Use this value as `name` when granting access.

`portalUrl`

The tax authority portal URL.

`authMechanism`

Indicates how access is granted. `CREDENTIAL_SCRAPE` means that the authority uses a username and password.

`accessStatus`

The company's onboarding status for this tax authority.

`isTwoFactorAuthRequired`

Indicates whether the authority sends 2FA codes. If it does, 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.").

`supportedFormCodes`

The form codes that the company can file with this authority.

`activeTasks`

The extraction tasks for this authority. This value is `null` when the authority has no active tasks.

**Access status values**:

Value

Meaning

`NOT_STARTED`

No filing requests exist for this authority.

`ACCESS_GRANTED`

At least 1 extraction is running or has finished, so the credentials were accepted.

`ACTION_REQUIRED`

Filing requests exist, but all of them failed.

## Next step

If `isTwoFactorAuthRequired` is true, configure the company forwarding email. For more 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.").

If 2FA isn't required, proceed directly to Grant authority access and trigger extraction. For more 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.").