# Link an existing Client Account

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

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

# Link an existing Client Account

Link an existing Avalara client account to your firm so you can manage returns, filings, and tax notices through your platform.

If a merchant already has an Avalara account, you can connect their existing account to your Firm using the firm-client linkage mutation. This establishes a formal relationship between your Firm and the Client within the Avalara system.

Once linked, your platform will be able to:

-   View and manage the client’s **returns configuration**

-   Submit and track **filings**

-   Access and monitor **tax notices**

**Requirements for linking an existing Client account**:

-   Authenticate using the client account credentials (that is, the merchant’s `accountId` and `licenseKey`).

-   The client must provide their Avalara account ID and license key so that the linkage you can authorize.

-   The Firm is responsible for storing the Client credentials securely and using them for any API requests related to the Client’s filings, calendars, or transactions.

Note

-   Once the linkage is established, all operations that affect a specific client (for example, setting up filing calendars, submitting transactions, or viewing filings) must be performed using the Client’s API credentials, not the Firm’s.

    Use the **Firm credentials** to manage linkages.

-   Use the **Client credentials** for day-to-day returns operations.

Use the following mutation to create a linkage between the client account and a firm account:

**View request**:

```
mutation CreateFirmClientLinkage {
    createFirmClientLinkage(
        input: { firmAccountId: 12345, firmAccountName: "anonymous" }
    ) {
        clientAccountId
        clientAccountName
        firmAccountId
        firmAccountName
        firmContactEmail
        firmContactName
        id
        isDeleted
        status
        company {
            companyId
            accountId
            name
            isDefault
            isActive
            hasProfile
            isReportingEntity
            companyCode
            isTest
        }
    }
}
```

**View response**:

```
{
  "data": {
    "createFirmClientLinkage": {
      "clientAccountId": 12345,
      "clientAccountName": "anonymous",
      "firmAccountId": 2091022162,
      "firmAccountName": "ABCDE",
      "firmContactEmail": "",
      "firmContactName": "anonymous ",
      "id": 340444,
      "isDeleted": false,
      "status": "APPROVED",
      "company": null,
      "licenseKey": null
    }
  }
}
```