automated-provisioning.md

layout	title	product	doctype	nav
page	Overview	avaTax	use_cases	apis

Account Provisioning and Company Management

The Onboarding API allows Avalara partners to create customer accounts, company profiles, and user credentials.

What You Can Do

This API allows partners to automatically provision individual customer accounts and assist with company profile setup on those accounts, allowing for a quick, automated account setup for these customers.

Get API Key

To get access to this API, contact your Customer Account Manager or email [email protected].

Documentation

Here is the Onboarding API Documentation for the RESTful Onboarding API. This API is designed so that a single operation represents a group of provisioning steps; an account can be provisioned with a company and single location (with associated nexus) and a single admin user with a single POST /accounts.

Develop Your Integration

Once you have access to the Onboarding API, there are a number of options and simplifications you can present to your users.

Provisioning Workflow

Registered in more than one jurisdiction?

Account creation also creates a default company, with a single-location nexus set up. This tax registration (nexus) reflects all triggered jurisdictions for the provided merchant address. If the merchant needs to collect sales tax in additional locations (e.g. other states), nexus needs to be set up in those jurisdictions as well. You can call POST /nexus with additional addresses to set nexus associated with those merchant addresses. If a merchant prefers to choose nexus jurisdictions by name (rather than triggering them by address), they should set up their nexus in the Avalara Admin Console.

Why Set Locations?

When a company is created, a single location is also created. If a merchant needs to report out sales by physical location within a single jurisdiction (note: this is uncommon), additional locations should be created. Locations do not need to represent every merchant origin address, or every end-customer address (in fact, they should never represent an end-customer address).

Credential Management

Provisioning an account creates the account number and license key required to call that account. This credential information is returned in the response to POST /accounts. You should store this information in a secure, merchant-specific location. The merchant will also be emailed this credential information, but since it is specifically used for calling the AvaTax API (separate credentials are issued to the merchant to log in to the Avalara Admin Console), it is most useful when entered in your connector.

Processing Payment

Currently only free trial accounts can be created through the Onboarding API. Payment information does not need to be collected or provided to provision free trial accounts.

Product Attachment

If a merchant wants to upgrade from a free trial account to a full account, or to add additional services (tax return filing, certificate management) to their existing paid account, they should reach out to Avalara directly. Product attachment is not currently supported through the Onboarding API.

Provisioning Workflow

When provisioning customer accounts with the onboarding API, you must perform various provisioning steps in a specific order.

Request 1: /accounts

The first request in the workflow creates a single account with:

• one Account Admin-level user
• one default company profile
• one defined location
• tax registration (nexus) designated for the single location

The account will be a free or paid account depending on the ProductRatePlan information provided in the request. The credentials for this account will be returned in the response, an should be stored for use in future calls to set up company profile elements, and to calculate tax.

Request 2: /companies

Once the account is provisioned, additional companies can be created.

Request 3: /locations

If a company requires more than one reportable location, additional locations can be defined.

Request 4: /nexus

If a company requires more than one nexus location, additional nexus can be set.