Atria API

Atria API

Atria API

Purpose

The Atria API is a new Rest-based integration point that over time will replace the functionality of the old API, (known as the CortexAPI).  If you have developed against The CortexAPI, don’t worry, it’s still working and supported. 

Requirements:
  1. Atria 12.11 or higher
  2. A valid Atria external API Token

Benefits

The new API will be easier for developers to understand and consume and will be built using standard conventions.
Our initial release is focused on Billing, the API can be used to extract your billing information directly into spreadsheets, PowerBI, or third-party systems.

Using the API

Authentication

Authentication to the API uses a JWT token, the application communicating with Atria, presents the token, this is then validated against a user in Atria, if valid access is permitted and the API call is executed.
Tokens are created within Atria and are attached to a user account.
If the user account in Atria is disabled, then API access via the token attached to that user will also be disabled.   Note that the user account must be disabled via Atria in order to disable API access, disabling the associated AD user account will not immediately block access.
At the time of writing, AD Account expiry will not disable API access.

Authorization

In order for a user to have an API token, they must be granted the “ Service Provider Developer ” permission.  Once they have this permission, the change password page allows the tokens to be created and deleted.
In order to grant "Service Provider Developer" permission to a user follow the below steps:

  1. Click on Users -> select a user -> Edit User -> Account Settings -> Advanced Options -> Enable "Service Provider Developer" check-box

Creating a Token

Login or impersonate a user that has access, click on the “ Password ” link on the left-hand menu.  Half way down the page you should see a “ Generate API Access Token ” – click on the “ Generate ” link to create a new token.

Here is a scribe on how to generate this token - https://scribehow.com/shared/Atria_Configuration__Generate_new_API_Token__3oVFo-hSQRalNVIREA4gmw

Once you leave this page, you will not be able to view the token again, it is encrypted and stored in the database, if you forget the token you will need to create another one and reconfigure your applications.
 Store the token securely and protect it in the same way as credentials.

Using the Token

The token should be provided as an Authorization header for every call made to the API.  If the token is not present the API call will fail.

Header name
Value
Authorization
Bearer {token} 

Billing API Calls

Billing Parameters

/api/Billing/parameters
This GET command will return 
- All of the billing periods that are available within your Atria system
- All of the Customers contained within the system and their customerIDs

Curl Syntax

  1. curl -X GET "https://{API HOSTNAME}/api/Billing/parameters" -H "accept: text/plain" -H "Authorization: bearer a8cab2d1ae00df4a7edd514af7828d7df672054c89feb753305f17c403127769"

Successful Response Format

  1. {
  2.   "data": {
  3.     "endDates": [
  4.       {
  5.         "label": "2019-10-31"
  6.       },
  7.       {
  8.         "label": "2019-11-30"
  9.       },
  10.       {
  11.         "label": "2019-12-31"
  12.       },
  13.       {
  14.         "label": "2020-01-31"
  15.       },
  16.       {
  17.         "label": "2020-02-29"
  18.       },
  19.     ],
  20.     "customers": [
  21.       {
  22.         "id": 30,
  23.         "name": "Aanimals Inc"
  24.       },
  25.       {
  26.         "id": 102,
  27.         "name": "Abacus Computing Group"
  28.       },
  29.       {
  30.         "id": 57,
  31.         "name": "Able Metals Limited"
  32.       },
  33.       {
  34.         "id": 5,
  35.         "name": "Abracard Limited"
  36.       }
  37.       ]

Curl Syntax (Powershell)

  1. curl -Uri "https://{API HOSTNAME}/api/Billing/parameters" -Method Get -Headers @{
  2.     accept = "text/plain"
  3.     authorization = "bearer a8cab2d1ae00df4a7edd514af7828d7df672054c89feb753305f17c403127769"
  4. }


Billing Summary


URL - /api/billing/{enddate}

  • This extracts a summarized view of the data for a billing period (as specified by the billing period end date), this refers to a customer, but does not provide detailed information for the customer (e.g. address details etc)
  • You can specify whether you want to retrieve only billable items (set billable flag).
  • Group output by customer with the AggregateByCustomer parameter.
  • This will also compare the data from the current period with the prior period, so handy for showing trends in data.
Header Name Description
endDate * (string, path) The end date of the billing period
customerId (integer, query) The customer to generate a billing summary for
billable (integer, query) Whether to only include billable items
aggregateByCustomer (boolean, query) Whether to aggregate the results by customers

Example JSON Response

  1. {
  2.   "data": {
  3.     "items": [
  4.       {
  5.         "customerCode": "string",
  6.         "customerName": "string",
  7.         "customerAccountCode": "string",
  8.         "sku": "string",
  9.         "isBillable": true,
  10.         "lineDescription": "string",
  11.         "previousPeriod": 0,
  12.         "change": 0,
  13.         "currentPeriod": 0
  14.       }
  15.     ],
  16.     "billPeriodId": 0,
  17.     "periodName": "string",
  18.     "startDate": "2023-10-23T12:47:24.683Z",
  19.     "endDate": "2023-10-23T12:47:24.683Z"
  20.   },
  21.   "errorMessage": "string",
  22.   "success": true,
  23.   "responseCode": 0
  24. }

Get a detailed report of all customer data

Using the EndDate from previous, or input the current month in your code, you can pull a detailed report



URL - /api/billing/{enddate}/detail

This extracts user level details for the specified billing period.  For example, data will show the customer, the user, the service and the duration of the month that they have had the service (via start and end date)
Filter the data to a specific customer, show billable or all data, or use additional parameters for service and user search.


Header Name Description
endDate * (string, path) The end date of the billing period
customerId (integer, query) The customer to generate a billing summary for
serviceSearch (string, query) Search for a specific service
userSearch (string, query) Search for a specific user
billable (integer, query) Whether to only include billable items

Example JSON Response

  1. {
  2.   "data": {
  3.     "items": [
  4.       {
  5.         "billPeriodID": 0,
  6.         "periodName": "string",
  7.         "billPeriodStartDate": "2023-10-23T12:51:24.148Z",
  8.         "billPeriodEndDate": "2023-10-23T12:51:24.148Z",
  9.         "customerId": 0,
  10.         "customerCode": "string",
  11.         "customerName": "string",
  12.         "customerAccountCode": "string",
  13.         "address1": "string",
  14.         "address2": "string",
  15.         "country": "string",
  16.         "postCode": "string",
  17.         "email": "string",
  18.         "billCustomerID": 0,
  19.         "billCustomerCode": "string",
  20.         "billCustomerName": "string",
  21.         "billCustomerAccountCode": "string",
  22.         "billAddress1": "string",
  23.         "billAddress2": "string",
  24.         "billCountry": "string",
  25.         "billPostCode": "string",
  26.         "billEmail": "string",
  27.         "billItemID": 0,
  28.         "serviceChangeID": 0,
  29.         "userId": 0,
  30.         "upn": "string",
  31.         "userName": "string",
  32.         "serviceId": 0,
  33.         "serviceCode": "string",
  34.         "serviceName": "string",
  35.         "instanceName": "string",
  36.         "sku": "string",
  37.         "skuType": "string",
  38.         "planCode": "string",
  39.         "servicePlanName": "string",
  40.         "lineDescription": "string",
  41.         "summaryGrouping": "string",
  42.         "percentDuration": 0,
  43.         "isBillable": true,
  44.         "overrideReason": "string",
  45.         "billConfigRuleID": 0,
  46.         "changeStartDate": "2023-10-23T12:51:24.148Z",
  47.         "changeEndDate": "2023-10-23T12:51:24.148Z",
  48.         "quantity": 0,
  49.         "action": "string",
  50.         "addedByUserID": 0,
  51.         "addedByUserName": "string",
  52.         "removedByUserID": 0,
  53.         "removedByUserName": "string",
  54.         "department": "string",
  55.         "location": "string",
  56.         "actionedDate": "2023-10-23T12:51:24.148Z",
  57.         "actionedBy": "string",
  58.         "resultCount": 0
  59.       }
  60.     ],
  61.     "billPeriodId": 0,
  62.     "periodName": "string",
  63.     "startDate": "2023-10-23T12:51:24.148Z",
  64.     "endDate": "2023-10-23T12:51:24.148Z"
  65.   },
  66.   "errorMessage": "string",
  67.   "success": true,
  68.   "responseCode": 0
  69. }


    • Related Articles

    • Atria API Policy

      Purpose To provide direction and guidance to Atria customers and third parties integrating with Atria API’s. Atria API's API Name Type Purpose Cortex API XML based over HTTPS https://{hostname}/cortexapi Used by AD Sync, Customer, User, Service ...

    • How to connect Power BI to Atria API

      Overview In this article, we are going to show you how to connect to Atria API via Power BI.  Power BI will be able to retrieve data to create visuals and reports based on your requirements. The following article will illustrate a step by step guide ...

    • Atria API User Guide (CortexAPI)

      Overview The application programming interface (API) is a powerful interface that allows you to interact directly with Atria without using the ATRIA Web User Interface (UI).  The API grants a user, with some development knowledge, the ability to ...

    • How to connect to Atria External Billing API via Excel

      Atria External API via Excel This document illustrates how to use Atria's external API platform to retrieve billing invoice data via an Excel document. Applies to: Atria 12.11 or later Create Token Use the following KB as a step by step to receive ...

    • Billing with Atria

      Atria Billing Index Atria has a systematic approach to tracking services that it manages, this data can be exported or directly integrated via API into external PSA or billing systems. Background Information Quick video on billing and auditing How ...