# Query received two-factor security codes

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

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

# Query received two-factor security codes

Retrieve 2-factor authentication, 2FA, emails, and security verification codes for a company by using the companies GraphQL query.

The companies query returns 2FA or MFA, emails and verification codes that tax authorities sent to a company's alias through the `codeDetails` field.

This company-level field returns received codes for the entire company, not for a single tax authority.

Key considerations:

-   **Required company ID**: Pass the company ID as an integer argument. If you don’t provide it, `codeDetails` returns null, and an error is added to the errors array.

-   **Field distinction**: Selecting `codeDetails` doesn't read or create the alias. To read or create the alias, select `twoFactorSettings`.

## View request

```
query Companies($id: Int) {
  companies(id: $id) {
    value {
      id
      codeDetails {
        externalId
        from
        subject
        createdAt
        emailType
        code
        emailContents
      }
    }
    errors {
      message
    }
  }
}
```

**Input variables**:

```
{
  "id": 1234567
}
```

Table 1. Input variable details

Argument

Type

Description

`id`

`Int`

The company whose 2FA emails to return. This is a number, not a string. Required for `codeDetails`.

## View response

```
{
  "data": {
    "companies": {
      "value": [
        {
          "id": 1234567,
          "codeDetails": [
            {
              "externalId": "1234567",
              "from": "Example Sender ",
              "subject": "AL security code",
              "createdAt": "2026-01-15T10:00:00",
              "emailType": "2fa",
              "code": "123456",
              "emailContents": "Your security code is 123456"
            }
          ]
        }
      ],
      "errors": []
    }
  }
}
```

**Response field descriptions**:

Response field

Description

`codeDetails`

The 2FA emails received for the company. Returns an empty array when none have arrived.

`codeDetails[].externalId`

The external identifier for the email.

`codeDetails[].from`

The sender of the email.

`codeDetails[].subject`

The subject line of the email.

`codeDetails[].createdAt`

The date and time when the email was received, in ISO 8601 format.

`codeDetails[].emailType`

The email type, for example `2fa`.

`codeDetails[].code`

The 2FA code.

`codeDetails[].emailContents`

The full contents of the email.

Note

If the codes can’t be returned, `codeDetails` is `null`, and the reason appears in the response `companies.errors` array.

## Next step

To submit portal credentials for a tax authority, 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.").