# Resume authority onboarding session

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

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

# Resume authority onboarding session

Resume in-flight onboarding jobs with saved credentials by using the `resumeAuthorityAccess` GraphQL mutation.

The `resumeAuthorityAccess` mutation retries 1 or more in-flight onboarding jobs by using credentials saved on the server. The client sends only the job ID and authority name so portal passwords aren’t sent over the network again.

Each job in the request gets its own result in the response. A job that requires reverification waits for a live portal sign-in and can take up to 4 minutes. Configure client timeouts accordingly.

This operation is optional. Use `savedAuthorityAccounts` to find jobs that are eligible to resume.

## Key considerations

-   **Password protection**: Passwords are read from secure server-side storage. They’re never returned or resent by the client.

-   **Multijob processing**: You can submit multiple jobs in a single request. If 1 job fails for example because of an invalid authority name, the remaining jobs continue processing.

-   **Action on failure**: If a job returns an outcome of `NO_ACTION` or `FAILED`, prompt the user for new credentials and call `grantAuthorityAccess`.

## View request

```
mutation ResumeAuthorityAccess($input: ResumeAuthorityAccessInput!) {
  resumeAuthorityAccess(input: $input) {
    results {
      portalUrl
      locationId
      outcome
      tasks {
        taskId
        formCode
        status
        message
        dateCreated
        dateCompleted
        filingRequestIds
        generatedTaxFormCodes
      }
    }
  }
}
```

**Input variables**:

```
{
  "input": {
    "companyId": "1234567",
    "country": "US",
    "region": "AL",
    "jobs": [
      {
        "name": "Alabama Department of Revenue",
        "jobId": "100001"
      }
    ]
  }
}
```

Table 1. Input variable details

Argument

Type

Description

`companyId`

`ID!`

The company whose jobs are resumed.

`country`

`String!`

The 2-character ISO 3166 country code.

`region`

`String!`

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

`jobs[].name`

`String!`

The authority name for the job, from the `name` on `authorities`. The value is matched against the authority's DoR name, ignoring the case and surrounding spaces.

`jobs[].jobId`

`ID!`

The job to resume, from `jobId` on `grantAuthorityAccess`.

## View response

Example response when filing requests are created:

```
{
  "data": {
    "resumeAuthorityAccess": {
      "results": [
        {
          "portalUrl": "https://myalabamataxes.alabama.gov/_/",
          "locationId": null,
          "outcome": "CREATED",
          "tasks": [
            {
              "taskId": "aaaaaaaa-0000-4000-8000-000000000001",
              "formCode": "USAL2100",
              "status": "InProgress",
              "message": null,
              "dateCreated": "2026-01-15T09:13:30.9832215",
              "dateCompleted": null,
              "filingRequestIds": []
              “generatedTaxFormCodes”: []
            }
          ]
        }
      ]
    }
  }
}
```

Example response when the authority is already configured and no new extraction occurs:

```
{
  "data": {
    "resumeAuthorityAccess": {
      "results": [
        {
          "portalUrl": "https://myalabamataxes.alabama.gov/_/",
          "locationId": null,
          "outcome": "ALREADY_CREATED",
          "tasks": null
        }
      ]
    }
  }
}
```

Example response when the name doesn’t match an authority. That job gets the outcome `FAILED` and a `portalUrl` of `null`. No saved credentials are read for that job, and other jobs in the request still resume:

```
{
  "data": {
    "resumeAuthorityAccess": {
      "results": [
        {
          "portalUrl": null,
          "locationId": null,
          "outcome": "FAILED",
          "tasks": null
        }
      ]
    }
  }
}
```

**Response field descriptions**:

The response includes 1 entry in `results` for each submitted job. `portalUrl` is `null` only when the job's `name` doesn’t match an authority.

Response field

Description

`CREATED`

The saved credentials were valid, and filing requests were created. `tasks` contains the extraction tasks to poll with `taskStatus`.

`VALIDATED`

The credentials were verified again, but no filing requests were created.

`ALREADY_CREATED`

The authority already has access, so no action was taken.

`NO_ACTION`

The saved sign-in couldn’t be retried, for example because the credentials were rejected. Ask the user for new credentials and call `grantAuthorityAccess` again.

`NOT_FOUND`

No saved account exists for that job ID.

`FAILED`

Resuming the job failed, for example because its `name` didn’t match an authority. Other jobs in the request aren’t affected.

## Next step

To monitor the extraction tasks returned in the tasks array, see [Monitor extraction task status](/managed-returns/fcy1877890471345/ "Check the status of 1 or more background return extraction tasks with the taskStatus GraphQL query."). After the extraction tasks complete, proceed to approve extracted filing requests.