Avalara Accounts API

openapi: 3.2.0
info:
  title: Avalara Accounts API
  version: '1.0'
  description: 'Operations tagged Accounts across 3 of this provider''s published API definitions: avalara-avatax-rest-openapi.yml, avalara-business-openapi.yml, avatax-apis-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://rest.avatax.com
  description: AvaTax Production
- url: https://sandbox-rest.avatax.com
  description: AvaTax Sandbox
- url: https://api.avalara.com/business/v1
  description: Business API Production
- url: http://{{baseurl}}
tags:
- name: Accounts
  description: Manage AvaTax accounts and license keys
paths:
  /api/v2/accounts/{id}:
    get:
      operationId: getAccount
      summary: Avalara Retrieve a Single Account
      tags:
      - Accounts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: $include
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountModel'
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://rest.avatax.com
      description: AvaTax Production
    - url: https://sandbox-rest.avatax.com
      description: AvaTax Sandbox
  /api/v2/accounts:
    get:
      operationId: queryAccounts
      summary: Avalara List All Accounts
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      responses:
        '200':
          description: List of accounts
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://rest.avatax.com
      description: AvaTax Production
    - url: https://sandbox-rest.avatax.com
      description: AvaTax Sandbox
  /accounts:
    post:
      operationId: createAccount
      summary: Avalara Register a New Customer Account
      description: Registers a new customer account with Avalara through a partner integration.
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountRegistration'
      responses:
        '201':
          description: Account registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.avalara.com/business/v1
      description: Business API Production
  /accounts/{accountId}:
    get:
      operationId: getAccountsByAccountId
      summary: Avalara Get Account Details
      tags:
      - Accounts
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
      security:
      - bearerAuth: []
      x-operation-id-source: normalized
      x-operation-id-original: getAccount
    servers:
    - url: https://api.avalara.com/business/v1
      description: Business API Production
  /api/v2/accounts/{id}/resetlicensekey:
    post:
      tags:
      - Accounts
      summary: Avalara AccountResetLicenseKey
      description: 'Resets the existing license key for this account to a new key.


        To reset your account, you must specify the ID of the account you wish to reset and confirm the action.


        This API is only available to account administrators for the account in question, and may only be called after

        an account has been activated by reading and accepting Avalara''s terms and conditions. To activate your account

        please log onto the AvaTax website or call the `ActivateAccount` API.


        You can only reset license with ''Default'' license key name.

        Resetting a license key cannot be undone. Any previous license keys will immediately cease to work when a new key is created.


        When you call this API, all account administrators for this account will receive an email with the newly updated license key.

        The email will specify which user reset the license key and it will contain the new key to use to update your connectors.

        Note: The reset license key functionality will only be available for existing active license key i.e. when you reset license key for the account, the Default license key will be reset.The reset license key functionality is not available for newly created license keys i.e. license keys other than Default


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                accountId: 123456789
                confirmResetLicenseKey: true
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: postApiV2AccountsByIdResetlicensekey
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/accounts/{id}/activate:
    post:
      tags:
      - Accounts
      summary: Avalara ActivateAccount
      description: 'Activate the account specified by the unique accountId number.


        This activation request can only be called by account administrators. You must indicate

        that you have read and accepted Avalara''s terms and conditions to call this API.


        Once you have activated your account, use the `AccountResetLicenseKey` API to generate

        a license key for your account.


        If you have not read or accepted the terms and conditions, this API call will return the

        unchanged account model.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, FirmAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                acceptAvalaraTermsAndConditions: true
                haveReadAvalaraTermsAndConditions: true
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: postApiV2AccountsByIdActivate
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/accounts/{id}/audit:
    get:
      tags:
      - Accounts
      summary: Avalara AuditAccount
      description: 'Retrieve audit trace history for an account.


        Your audit trace history contains a record of all API calls made against the AvaTax REST API that returned an error. You can use this API to investigate

        problems and see exactly what information was sent back and forth between your code and AvaTax.


        When specifying a start and end datetime, please include a valid timezone indicator, such as the "Z" present in the examples for the start and end query parameters.

        You can learn more about valid time zone designators at https://en.wikipedia.org/wiki/ISO_8601#Time_zone_designators.


        This API enforces limits to the amount of data retrieved. These limits are subject to change.


        * You may request data from a maximum of a one-hour time period.

        * The amount of data and number of API calls returned by this API are limited and may be adjusted at any time.

        * Old records may be migrated out of immediately available storage. To request older data, please contact your account manager.

        * New records must migrate to available storage before they can be retrieved. You may need to wait a period of time before newly created records can be fetched.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, Compliance Root User, ComplianceAdmin, ComplianceUser, CSPAdmin, CSPTester, ECMAccountUser, ECMCompanyUser, FirmAdmin, FirmUser, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.'
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: getApiV2AccountsByIdAudit
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/accounts/{id}/licensekey:
    post:
      tags:
      - Accounts
      summary: Avalara CreateLicenseKey
      description: 'Creates a new license key for this account.


        To create a license key for your account, you must specify the ID of the account and license key name.


        This API is only available to account administrators for the account in question, and may only be called after

        an account has been activated by reading and accepting Avalara''s terms and conditions. To activate your account

        please log onto the AvaTax website or call the `ActivateAccount` API.


        You will reference this key using license key name. The existing license key will be using ''Default'' as license key name.

        Hence make sure that the license key name is unique per account considering the existing license key name ''Default''


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                name: ABCDEFGHIJK
                accountId: 123456789
                createdDate: '2023-08-13T00:00:00+00:00'
                createdUserId: 1
                modifiedDate: '2023-08-13T00:00:00+00:00'
                modifiedUserId: 1
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: postApiV2AccountsByIdLicensekey
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/accounts/{id}/licensekey/{licensekeyname}:
    delete:
      tags:
      - Accounts
      summary: Avalara DeleteLicenseKey
      description: 'Deletes the license key for this account using license key name.


        To delete a license key for your account, you must specify the accountID of the account and license key name.


        This API is only available to account administrators for the account in question.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.'
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: id
        in: path
        schema:
          type: string
        required: true
      - name: licensekeyname
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: deleteApiV2AccountsByIdLicensekeyByLicensekeyname
      x-operation-id-source: derived
    get:
      tags:
      - Accounts
      summary: Avalara GetLicenseKey
      description: '### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, Compliance Root User, ComplianceAdmin, ComplianceUser, CSPAdmin, CSPTester, ECMAccountUser, ECMCompanyUser, FirmAdmin, FirmUser, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.'
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: id
        in: path
        schema:
          type: string
        required: true
      - name: licensekeyname
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: getApiV2AccountsByIdLicensekeyByLicensekeyname
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/accounts/{id}/configuration:
    get:
      tags:
      - Accounts
      summary: Avalara GetAccountConfiguration
      description: 'Retrieve a list of all configuration settings tied to this account.


        Configuration settings provide you with the ability to control features of your account and of your

        tax software. The category names `TaxServiceConfig` and `AddressServiceConfig` are reserved for

        Avalara internal software configuration values; to store your own account-level settings, please

        create a new category name that begins with `X-`, for example, `X-MyCustomCategory`.


        Account settings are permanent settings that cannot be deleted. You can set the value of an

        account setting to null if desired.


        Avalara-based account settings for `TaxServiceConfig` and `AddressServiceConfig` affect your account''s

        tax calculation and address resolution, and should only be changed with care.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, ECMAccountUser, ECMCompanyUser, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser.'
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: getApiV2AccountsByIdConfiguration
      x-operation-id-source: derived
    post:
      tags:
      - Accounts
      summary: Avalara SetAccountConfiguration
      description: 'Update configuration settings tied to this account.


        Configuration settings provide you with the ability to control features of your account and of your

        tax software. The category names `TaxServiceConfig` and `AddressServiceConfig` are reserved for

        Avalara internal software configuration values; to store your own account-level settings, please

        create a new category name that begins with `X-`, for example, `X-MyCustomCategory`.


        Account settings are permanent settings that cannot be deleted. You can set the value of an

        account setting to null if desired.


        Avalara-based account settings for `TaxServiceConfig` and `AddressServiceConfig` affect your account''s

        tax calculation and address resolution, and should only be changed with care.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, CSPTester, SSTAdmin, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                accountId: 0
                category: TaxServiceConfig
                name: MaxLines
                value: '1000'
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: postApiV2AccountsByIdConfiguration
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/accounts/{id}/licensekeys:
    get:
      tags:
      - Accounts
      summary: Avalara GetLicenseKeys
      description: 'Gets list of all the license keys used by the account.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, Compliance Root User, ComplianceAdmin, ComplianceUser, CSPAdmin, CSPTester, ECMAccountUser, ECMCompanyUser, FirmAdmin, FirmUser, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.'
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: getApiV2AccountsByIdLicensekeys
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
components:
  parameters:
    skip:
      name: $skip
      in: query
      schema:
        type: integer
        default: 0
      description: Number of results to skip for pagination
    top:
      name: $top
      in: query
      schema:
        type: integer
        default: 1000
      description: Maximum number of results to return
    filter:
      name: $filter
      in: query
      schema:
        type: string
      description: OData filter expression for result filtering
  schemas:
    AccountModel:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        effectiveDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        accountStatusId:
          type: string
          enum:
          - Inactive
          - Active
          - Test
          - New
        createdDate:
          type: string
          format: date-time
        modifiedDate:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    AccountResponse:
      type: object
      properties:
        accountId:
          type: string
        accountNumber:
          type: string
        companyName:
          type: string
        status:
          type: string
          enum:
          - Active
          - Inactive
          - Pending
        createdDate:
          type: string
          format: date-time
    AccountRegistration:
      type: object
      required:
      - companyName
      - email
      properties:
        companyName:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phoneNumber:
          type: string
        address:
          type: object
          properties:
            line1:
              type: string
            city:
              type: string
            region:
              type: string
            postalCode:
              type: string
            country:
              type: string
        partnerCode:
          type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AvaTax username/password or accountId/licenseKey as basic auth credentials
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token
x-refined-from:
- avalara-avatax-rest-openapi.yml
- avalara-business-openapi.yml
- avatax-apis-openapi.yml