Create and link an account

The first step in onboarding a client is to provision a new Avalara Client Account through your Firm (Partner) account, or to link an existing Avalara account the client already owns.

When provisioning a new Client account, the following actions occur automatically:

A new Client Account (representing the merchant) is created.
The Client Account is linked to your Firm (Partner) Account via a firm-client relationship.
A default Company profile is created using the same name as the Client Account.
A license key is generated, allowing future authentication into the Client Account.

Note
While clients can have multiple company records, the Channel Ready Returns model assumes a simple structure. Most clients will use the default company created at provisioning.

This process enables all downstream setup tasks such as importing transactions, selecting forms, configuring filing calendars, and submitting filings.

Requirements for provisioning a new Client account:

The account name and address must be valid and unique; invalid addresses will trigger an error at the time of provisioning.
A Firm (Partner) token must be used for this operation. Client credentials aren’t accepted for account creation or provisioning.

Note
After provisioning is complete, the partner must securely store the returned Client license key and account ID, which is used for all future authenticated operations on behalf of the client (for example, filing calendar creation, returns submission, and so on).

To create and link an account, use the following mutation:

View request:

mutation CreateAndLinkAccount {
  createAndLinkAccount(
    firmClientAccountInput: {
      accountName: "CRR Onboarding Test 33"
      companyAddress: {
        city: "Green Bay"
        country: "US"
        line: "3033 Main Street"
        postalCode: "54313"
        region: "WI"
      }
      companyCode: "testCompanyCode"
      taxPayerIdNumber: "123456783"
      email: "test@test.com"
      firstName: "ABC"
      lastName: "XYZ"
      phoneNumber: "3604900294"
      title: "MR"
    }
  ) {
    clientAccountId
    clientAccountName
    firmAccountId
    firmAccountName
    firmContactEmail
    firmContactName
    id
    isDeleted
    status
    company {
      companyId # this will be the unique id of the company which will be used in subsequent queries
      companyCode
    }
    licenseKey { #these are your credentials which can use to generate token
      privateLicenseKey
      accountId
    }
  }
}

View response:

{
  "data": {
    "createAndLinkAccount": {
      "clientAccountId": 1234567890,
      "clientAccountName": "CRR Onboarding Test",
      "firmAccountId": 1234567890,
      "firmAccountName": "CRR_Firm_Account",
      "firmContactEmail": "",
      "firmContactName": "anonymous ",
      "id": 123456,
      "isDeleted": false,
      "status": "APPROVED",
      "company": {
        "companyId": 1234567,
        "companyCode": "CRROnboardingTest33"
      },
      "licenseKey": {
        "privateLicenseKey": "1235ABCD456EDC",
        "accountId": 1234567890
      }
    }
  }
}