openapi: 3.0.0
info:
title: Avalara AvaTax Registrar API
description: "Welcome to the AvaTax API Postman Collection! \n \nThis collection provides a REST interface to Avalara's enterprise tax service, AvaTax. You can use this collection to interact with the AvaTax APIs while building your integration. \n\nWhile using this collection, we recommend following along with our Developer Implementation Guide: https://developer.avalara.com/avatax/dev-guide/ \n\nAPI requests are grouped into folders to help you navigate through the collection easily. Each request includes a description of the operation and its associated URL, method, headers, and example request body (if applicable). \n\nThe collection uses Postman environment variables for the API base URL and credentials, making it easy to switch between the sandbox and production environments.\n\nTo get started, ensure you have the necessary credentials. Then, update the 'username' and 'password' variables in the 'Authorization' or 'Variables' section with your credentials if you prefer username and password authentication. Alternatively, you can use the 'account_id' and 'license_key' variables for authentication using an account ID and license key.\n\nWe recommend starting with the Ping API, located within the Utilities folder, to test your connectivity and ensure your authentication credentials are valid. The Ping API is a simple way to check if you can successfully communicate with AvaTax.\n\nCollection Variables:\n- Base URL: The base URL for the API. By default, it is set to the sandbox URL - https://sandbox-rest.avatax.com. \n - Change this variable to switch between sandbox and production environments:\n - Sandbox URL: https://sandbox-rest.avatax.com\n\t\t- Production URL: https://rest.avatax.com\n- Username: If you are using username and password authentication, enter your username for AvaTax.\n- Password: If you are using username and password authentication, enter your password for AvaTax.\n- Account ID: If you are using account ID and license key authentication, enter your AvaTax account ID. \n - Be sure to also replace the username variable in the authorization tab with account_id.\n- License Key: If you are using account ID and license key authentication, enter your AvaTax license key.\n - Be sure to also replace the password variable in the authorization tab with license_key.\n\nHappy testing with AvaTax APIs!"
version: 1.0.0
servers:
- url: http://{{baseurl}}
security:
- basicAuth: []
tags:
- name: Registrar
paths:
/api/v2/accounts/{id}:
delete:
tags:
- Registrar
summary: Avalara DeleteAccount
description: "# For Registrar Use Only\nThis API is for use by Avalara Registrar administrative users only.\n \nDelete an account.\nDeleting an account will delete all companies, all account level users and license keys attached to this account.\n\n### Security Policies\n\n* This API requires the user role SystemAdmin.\n"
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: {}
put:
tags:
- Registrar
summary: Avalara UpdateAccount
description: "# For Registrar Use Only\nThis API is for use by Avalara Registrar administrative users only.\n \nReplace an existing account object with an updated account object.\n\n### Security Policies\n\n* This API requires one of the following user roles: BatchServiceAdmin, FirmAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.\n"
requestBody:
content:
application/json:
schema:
type: object
example:
id: 12345
name: Test Account
effectiveDate: '2023-08-13T00:00:00+00:00'
accountStatusId: Test
accountTypeId: Regular
isSamlEnabled: false
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: {}
/api/v2/accounts:
post:
tags:
- Registrar
summary: Avalara CreateAccount
description: "# For Registrar Use Only\nThis API is for use by Avalara Registrar administrative users only.\n \nCreate a single new account object.\nWhen creating an account object you may attach subscriptions and users as part of the 'Create' call.\n\n### Security Policies\n\n* This API requires one of the following user roles: BatchServiceAdmin, FirmAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.\n"
requestBody:
content:
application/json:
schema:
type: object
example:
id: 12345
name: Test Account
effectiveDate: '2023-08-13T00:00:00+00:00'
accountStatusId: Test
accountTypeId: Regular
isSamlEnabled: false
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
responses:
'200':
description: Successful response
content:
application/json: {}
/api/v2/notifications/{id}:
delete:
tags:
- Registrar
summary: Avalara DeleteNotification
description: "This API is available by invitation only.\n \nDelete the existing notification identified by this URL.\n \nA notification is a message from Avalara that may have relevance to your business. You may want\nto regularly review notifications and then dismiss them when you are certain that you have addressed\nany relevant concerns raised by this notification.\n \nAn example of a notification would be a message about new software, or a change to AvaTax that may\naffect you, or a potential issue with your company's tax profile.\n\n### Security Policies\n\n* This API requires one of the following user roles: BatchServiceAdmin, FirmAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.\n* This API is available by invitation only. To request access to this feature, please speak to a business development manager and request access to [NotificationsAPI:Create].\n"
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: {}
put:
tags:
- Registrar
summary: Avalara UpdateNotification
description: "This API is available by invitation only.\n \nReplaces the notification identified by this URL with a new notification.\n \nA notification is a message from Avalara that may have relevance to your business. You may want\nto regularly review notifications and then dismiss them when you are certain that you have addressed\nany relevant concerns raised by this notification.\n \nAn example of a notification would be a message about new software, or a change to AvaTax that may\naffect you, or a potential issue with your company's tax profile.\n\n### Security Policies\n\n* This API requires one of the following user roles: BatchServiceAdmin, FirmAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.\n* This API is available by invitation only. To request access to this feature, please speak to a business development manager and request access to [NotificationsAPI:Create].\n"
requestBody:
content:
application/json:
schema:
type: object
example:
id: 123
accountId: 202011901
companyId: 34345
referenceObject: Company Return
referenceId: 692
severityLevelId: Neutral
category: Certificate Expiration
message: The certificate of your company is nearing its expiration, please consider renewing it.
needsAction: true
actionName: Certificate Renewal
actionLink: www.xyz.com
dismissed: false
expireDate: '2023-08-13T00:00:00+00:00'
createdUserId: 442323
createdDate: '2018-05-05T00:00:00'
modifiedUserId: 442323
modifiedDate: '2018-05-07T00:00:00'
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: {}
/api/v2/notifications:
post:
tags:
- Registrar
summary: Avalara CreateNotifications
description: "This API is available by invitation only.\n \nCreate a single notification.\n \nA notification is a message from Avalara that may have relevance to your business. You may want\nto regularly review notifications and then dismiss them when you are certain that you have addressed\nany relevant concerns raised by this notification.\n \nA Global notification is a message which is directed to all the accounts and is set to expire within\na certain time and cannot be dismissed by the user. Make accountId and companyId null to create a global notification.\n \nAn example of a notification would be a message about new software, or a change to AvaTax that may\naffect you, or a potential issue with your company's tax profile.\n\n### Security Policies\n\n* This API requires one of the following user roles: BatchServiceAdmin, FirmAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.\n* This API is available by invitation only. To request access to this feature, please speak to a business development manager and request access to [NotificationsAPI:Create].\n"
requestBody:
content:
application/json:
schema:
type: object
example:
id: 123
accountId: 202011901
companyId: 34345
referenceObject: Company Return
referenceId: 692
severityLevelId: Neutral
category: Certificate Expiration
message: The certificate of your company is nearing its expiration, please consider renewing it.
needsAction: true
actionName: Certificate Renewal
actionLink: www.xyz.com
dismissed: false
expireDate: '2023-08-13T00:00:00+00:00'
createdUserId: 442323
createdDate: '2018-05-05T00:00:00'
modifiedUserId: 442323
modifiedDate: '2018-05-07T00:00:00'
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
responses:
'200':
description: Successful response
content:
application/json: {}
/api/v2/accounts/{accountId}/subscriptions:
post:
tags:
- Registrar
summary: Avalara CreateSubscriptions
description: "This API is for use by Avalara Registrar administrative users only.\n \nCreate one or more new subscription objects attached to this account.\nA 'subscription' indicates a licensed subscription to a named Avalara service.\nTo request or remove subscriptions, please contact Avalara sales or your customer account manager.\n\n### Security Policies\n\n* This API requires one of the following user roles: BatchServiceAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.\n"
requestBody:
content:
application/json:
schema:
type: object
example:
id: 12345
accountId: 123456789
subscriptionTypeId: 2
subscriptionDescription: AvaTaxPro
effectiveDate: '2015-01-01'
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: accountId
in: path
schema:
type: string
required: true
responses:
'200':
description: Successful response
content:
application/json: {}
/api/v2/accounts/{accountId}/subscriptions/{id}:
delete:
tags:
- Registrar
summary: Avalara DeleteSubscription
description: "# For Registrar Use Only\nThis API is for use by Avalara Registrar administrative users only.\n \nMark the existing account identified by this URL as deleted.\n\n### Security Policies\n\n* This API requires one of the following user roles: BatchServiceAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.\n"
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: accountId
in: path
schema:
type: string
required: true
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
description: Successful response
content:
application/json: {}
put:
tags:
- Registrar
summary: Avalara UpdateSubscription
description: "# For Registrar Use Only\nThis API is for use by Avalara Registrar administrative users only.\n \nReplace the existing subscription object at this URL with an updated object.\nA 'subscription' indicates a licensed subscription to a named Avalara service.\nTo request or remove subscriptions, please contact Avalara sales or your customer account manager.\nAll data from the existing object will be replaced with data in the object you PUT.\nTo set a field's value to null, you may either set its value to null or omit that field from the object you post.\n\n### Security Policies\n\n* This API requires one of the following user roles: BatchServiceAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.\n"
requestBody:
content:
application/json:
schema:
type: object
example:
id: 12345
accountId: 123456789
subscriptionTypeId: 2
subscriptionDescription: AvaTaxPro
effectiveDate: '2015-01-01'
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: accountId
in: path
schema:
type: string
required: true
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
description: Successful response
content:
application/json: {}
/api/v2/servicetypes/servicetypes:
get:
tags:
- Registrar
summary: Avalara ListServiceTypes
description: "For Registrar Use Only\nThis API is for use by Avalara Registrar administrative users only.\n \nReturns the full list of Avalara-supported subscription types.\nThis API is intended to be useful for identifying which features you have added to your account.\nYou may always contact Avalara's sales department for information on available products or services.\nYou cannot change your subscriptions/service directly through the API.\n\n### Security Policies\n\n* This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, Compliance Root User, ComplianceAdmin, ComplianceUser, CSPAdmin, CSPTester, FirmAdmin, FirmUser, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.\n"
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
responses:
'200':
description: Successful response
content:
application/json: {}
/api/v2/passwords/{userId}/reset:
post:
tags:
- Registrar
summary: Avalara ResetPassword
description: "# For Registrar Use Only\nThis API is for use by Avalara Registrar administrative users only.\n \nAllows a system admin to reset the password for a specific user via the API.\nThis API is only available for Avalara Registrar Admins, and can be used to reset the password of any\nuser based on internal Avalara business processes.\n\n### Security Policies\n\n* This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, Compliance Root User, ComplianceAdmin, ComplianceUser, CSPTester, FirmAdmin, FirmUser, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.\n* This API is available to Avalara system-level (registrar-level) users only.\n"
requestBody:
content:
application/json:
schema:
type: object
example:
newPassword: NewPassword789~~!
suppressResetPasswordEmail: false
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: userId
in: path
schema:
type: string
required: true
responses:
'200':
description: Successful response
content:
application/json: {}
components:
securitySchemes:
basicAuth:
type: http
scheme: basic