Avalara > Blog > Developer > The AuditAccount endpoint

The AuditAccount endpoint

  • Oct 11, 2019 | Chris Walker

The AuditAccount endpoint provides a history that contains records of all API calls made against the AvaTax REST API. You can use this endpoint to troubleshoot issues or to simply provide a detailed record of all the API calls made against your account within a certain time period. 

Why and how to use the AuditAccount endpoint

Let’s say we made a transaction in AvaTax a few days ago using CreateTransaction then noticed today it does not show up in the Transactions tab. We can use AuditAccount to figure out what happened.

The first thing we need to do when using the endpoint is determine the start and end time we want to look into formatted in UTC; note that the maximum time range is one hour. If you don’t include start or end time parameters, the default is the past 15 minutes.

If we determine we created the transaction sometime between 2:00 and 3:00 p.m. on September 9, 2019, when converted to UTC, the start time will be 2019-09-09T21:00:00Z and the end time will be 2019-09-09T22:00:00Z

The API call will look like this: https://sandbox-rest.avatax.com/api/v2/accounts/{AccountNumber}/audit?start=2019-09-09T21:00:00Z&end=2019-09-09T22:00:00Z

And the response:

    "@recordsetCount": 1,
    "value": [
            "transactionId": 8616354833,
            "accountId": {AccountNumber},
            "userId": 296785,
            "ipAddress": "",
            "serverName": "IP-0A80803D",
            "serverVersion": "",
            "severityLevelId": 2,
            "serverTimestamp": "2019-09-09T21:25:37.5859247Z",
            "serverDuration": 48,
            "serviceName": "AccountSvcJson",
            "operation": "CreateTransaction",
            "referenceCode": "/api/v2/transactions/create",
            "errorMessage": "ValueRequiredError",
            "databaseCallCount": 1,
            "databaseCallDuration": "00:00:00.0460000",
            "events": [
                    "auditEventLevelId": 0,
                    "eventTimestamp": "2019-09-09T21:25:37.5859247Z",
                    "source": "Avalara.AvaTax.AccountServices",
                    "summary": "Exception of type 'Avalara.AvaTax.AccountServices.Common.Exceptions.ValidationFinishedException' was thrown.",
                    "details": "Avalara.AvaTax.AccountServices.Common.Exceptions.ValidationFinishedException: Exception of type 'Avalara.AvaTax.AccountServices.Common.Exceptions.ValidationFinishedException' was thrown.\r\n   at Avalara.AvaTax.AccountServices.Common.Security.SecurityCheck.Execute()\r\n   at Avalara.AvaTax.AccountServices.Controllers.v2.TransactionsController.UniversalCreate(CreateTransactionModel model, String include) in C:\\GitRepo\\master\\AvataxAccountServices\\src\\Avalara.AvaTax.AccountServices\\Controllers\\v2\\TransactionsController.cs:line 1309"
            "requestUrl": "/api/v2/transactions/create",
            "requestBody": "{\"lines\":[{\"number\":\"1\",\"quantity\":1,\"amount\":100,\"taxCode\":\"PS081282\",\"itemCode\":\"Y0001\",\"description\":\"Yarn\"}],\"type\":\"SalesInvoice\",\"companyCode\":\"DEFAULT\",\"date\":\"2019-08-12\",\"purchaseOrderNo\":\"2019-08-12-001\",\"addresses\":{\"singleLocation\":{\"line1\":\"2000 Main Street\",\"city\":\"Irvine\",\"region\":\"CA\",\"country\":\"US\",\"postalCode\":\"92614\"}},\"commit\":true,\"currencyCode\":\"USD\",\"description\":\"Yarn\"}",
            "responseStatus": 400,
            "responseBody": "{\r\n  \"error\": {\r\n    \"code\": \"ValueRequiredError\",\r\n    \"message\": \"Field customerCode is required.\",\r\n    \"target\": \"IncorrectData\",\r\n    \"details\": [\r\n      {\r\n        \"code\": \"ValueRequiredError\",\r\n        \"number\": 5,\r\n        \"message\": \"Field customerCode is required.\",\r\n        \"description\": \"Please provide a value for field customerCode.\",\r\n        \"faultCode\": \"Client\",\r\n        \"helpLink\": \"http://developer.avalara.com/avatax/errors/ValueRequiredError\",\r\n        \"refersTo\": null,\r\n        \"severity\": \"Error\"\r\n      }\r\n    ]\r\n  }\r\n}"

There are several helpful bits of information in the response. The first is the recordsetCount is equal to 1, which means only a single API call was made to AvaTax during the requested timeframe. Keep in mind only 1,000 results will be returned. Use the top and skip parameters to paginate your results if more than 1,000 requests have been made. The operation field will show what this API call was trying to do, in this case it’s set to CreateTransaction. The next field to check is errorMessage. For our transaction, it looks like a ValueRequiredError was returned because we forgot to add a required piece of information when trying to create the transaction.

To get more detail on the error, we can look at the responseBody field. 

                "responseBody": "{\r\n  \"error\": {\r\n    \"code\": \"ValueRequiredError\",\r\n    \"message\": \"Field customerCode is required.\",\r\n    \"target\": \"IncorrectData\",\r\n    \"details\": [\r\n      {\r\n        \"code\": \"ValueRequiredError\",\r\n        \"number\": 5,\r\n        \"message\": \"Field customerCode is required.\",\r\n        \"description\": \"Please provide a value for field customerCode.\",\r\n        \"faultCode\": \"Client\",\r\n        \"helpLink\": \"http://developer.avalara.com/avatax/errors/ValueRequiredError\",\r\n        \"refersTo\": null,\r\n        \"severity\": \"Error\"\r\n      }\r\n    ]\r\n  }\r\n}"

When reading through the response body, we can see that we forgot to add the customerCode.

To fix this issue, recreate the transaction and include the customerCode. The AuditAccount endpoint makes it easy to recreate the original API as it provides the requestBody. 

    "requestBody": "{\"lines\":[{\"number\":\"1\",\"quantity\":1,\"amount\":100,\"taxCode\":\"PS081282\",\"itemCode\":\"Y0001\",\"description\":\"Yarn\"}],\"type\":\"SalesInvoice\",\"companyCode\":\"DEFAULT\",\"date\":\"2019-08-12\",\"purchaseOrderNo\":\"2019-08-12-001\",\"addresses\":{\"singleLocation\":{\"line1\":\"2000 Main Street\",\"city\":\"Irvine\",\"region\":\"CA\",\"country\":\"US\",\"postalCode\":\"92614\"}},\"commit\":true,\"currencyCode\":\"USD\",\"description\":\"Yarn\"}"

AuditTransaction vs. AuditAccount?

AuditTransaction and AuditAccount have some overlap but there are some differences. AuditTransaction is very targeted and will give you specific information about a transaction provided you have all the required information to identify that transaction (document code). If you want to learn more about AuditTransaction, check out our previous blog post.

In conclusion

You can use this API to list the calls you’ve made to AvaTax to see the information you sent into AvaTax and what AvaTax sent back in a particular window of time. This can be helpful when trying to figure out why your transaction was missing, why tax calculated a certain way on a purchase order, or just to have a detailed record of your API call history. We still recommend having your own local logging mechanism to record the calls made to AvaTax to capture time, context, request, and response. 

Sales tax rates, rules, and regulations change frequently. Although we hope you'll find this information helpful, this blog is for informational purposes only and does not provide legal or tax advice.
Avalara Author
Chris Walker
Avalara Author Chris Walker
Chris Walker is a Software Engineer on Avalara's Developer Relations team. When not building cool things, he can be found jumping off of mountaintops or cruising on an electric longboard.