# Select regions and forms to file returns

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

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

# Select regions and forms to file returns

## Determine where to file returns

In this step, partners guide the merchant in identifying the regions (states or jurisdictions) where tax returns need to be filed. This can be done either by using Avalara's automated recommendations based on historical transaction data or by manually selecting from a list of supported forms per jurisdiction.

Partners have 2 supported options for enabling merchants to choose return forms:

## Recommended approach

**Option 1: Use suggested Avalara Managed Returns based on transaction history**

If historical transaction data has been imported for the client (via the onboarding transaction import process), Avalara analyzes this data and provides automated return form suggestions.

These suggestions are available via the `suggestedTaxForms` field of the `companies` GraphQL query. Each suggestion includes:

-   The region and country

-   A list of return forms applicable to that region

-   The tax authority name and form description

**View respect**:

```
query Companies {
    companies(id: 123456) {
        value {
            suggestedTaxForms {
                country
                region
                suggestedReturns {
                    description
                    taxAuthorityId
                    taxAuthorityName
                    taxFormCode
                    taxFormName
                    taxTypes
                }
                answeredQuestions {
                    accountId
                    answerId
                    companyId
                    country
                    onboardingQuestionAnswerId
                    questionId
                    region
                }
                onboardingQuestions {
                    allowMultiSelect
                    country
                    dataType
                    helpText
                    question
                    questionId
                    region
                    sequence
                    standard
                    answers {
                        answer
                        answerHelpText
                        leadingQuestionAnswerId
                        nextQuestionId
                        taxFormCode
                    }
                }
            }
        }
    }
}
```

**View response**:

```
{
  "data": {
    "companies": {
      "value": [
        {
          "suggestedTaxForms": [
            {
              "country": "US",
              "region": "NC",
              "suggestedReturns": [
                {
                  "description": "Sales and Use Tax Return",
                  "taxAuthorityId": 123,
                  "taxAuthorityName": "NORTH CAROLINA",
                  "taxFormCode": "ABCDE",
                  "taxFormName": "ABCDE",
                  "taxTypes": [
                    "Sales Tax",
                    "Sellers Use",
                    "Consumer Use"
                  ]
                }
              ],
              "answeredQuestions": [],
              "onboardingQuestions": [
                {
                  "allowMultiSelect": false,
                  "country": "US",
                  "dataType": "",
                  "helpText": "",
                  "question": "",
                  "questionId": 12,
                  "region": "NC",
                  "sequence": 1,
                  "standard": false,
                  "answers": [
                    {
                      "answer": "",
                      "answerHelpText": "",
                      "leadingQuestionAnswerId": 123,
                      "nextQuestionId": null,
                      "taxFormCode": "[\"ABCDE\"]"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}
```

Note

Avalara’s suggested forms rely on recent transaction data. For the best experience, partners upload at least 12 months of historical data before initiating this step.

**Option 2: Manual form selection**

If the merchant wants to add more regions not covered by past sales or business address, partners can use the `taxForms` query to retrieve a list of all supported returns forms by region.

This allows the partner to present an interface where the merchant can select a region (state or jurisdiction) and view the forms that Avalara Support for that region.

Note

This approach is ideal when no transaction history is available, or when the merchant wants to register proactively in new jurisdictions.

**View request**:

```
query TaxForms {
  definitions(input: { country: "US", region: "AR" }) {
    value {
      taxForms {
        authorityName
        country
        displayName
        taxFormCode
        taxFormName
        taxAuthority
        shortCode
        revision
        region
        purpose
        minor
      }
    }
  }
}
```

**View response**:

```
{
  "data": {
    "definitions": {
      "value": {
        "taxForms": [
          {
            "authorityName": "MIDWEST TAX AGENCY",
            "country": "US",
            "displayName": "US-AR Sales Tax Form A",
            "taxFormCode": "FORM-US-AR-001",
            "taxFormName": "Arkansas Sales and Use Form A",
            "taxAuthority": "ARKANSAS DOR",
            "shortCode": "AR001",
            "revision": 19,
            "region": "AR",
            "purpose": null,
            "minor": 0
          },
          {
            "authorityName": "MIDWEST TAX AGENCY",
            "country": "US",
            "displayName": "US-AR Sales Tax Form B",
            "taxFormCode": "FORM-US-AR-002",
            "taxFormName": "Arkansas Sales and Use Form B",
            "taxAuthority": "ARKANSAS DOR",
            "shortCode": "AR002",
            "revision": 5,
            "region": "AR",
            "purpose": null,
            "minor": 0,
          }
        ]
      }
    }
  }
}
```

Return form setup isn’t a one-time activity. Merchants may expand into new jurisdictions over time, requiring more filing calendars and forms. Partners design their onboarding and settings UI to allow merchants to:

-   Review configured return forms

-   Add new regions and forms at any time

-   Update jurisdictional details (for example, filing frequency, registration numbers)

## Next step

Once the merchant has selected their returns forms, either from Avalara’s suggestions or by browsing supported forms, the partner proceeds to configure filing calendars and gather any additional jurisdiction-specific information.