The Actuals API provides a mechanism to send transactions directly to Actuals (from the source e.g. website or mobile app where the transaction is created). By doing this as real time as possible when the transaction is created, Actuals provides companies with an independent source of expectations that can be used to match transactions against from other sources.
REST API
Using the Actuals (REST) API for sending transactions real time involves extending a company’s IT infrastructure with a small script. This script should send transactions to the Actuals platform when they are definitive. It is advised to do this asynchronously as to not impact the primary workflow. The Actuals API implements a Representational state transfer (REST) architecture and only several methods to send data (namely GET and POST). This allows details of a transaction to be send as well.
API details
The API is accessbile accross the internet but requires a specific URL to be used. Additionally HTTPs is used to encrypt the data. The URL can be obtained at your Actuals implementation consultant.
All requests to Actuals should be built up with these settings
- Headers: Authorization: Bearer: TOKEN, Content-Type: application/json
- URL:
https://[CUSTOMER_NAME].[CUSTOMER_ID].api.auditservicebus.com/[VERSION]/[RESOURCE](for testing please usehttps://dev-plem.[CUSTOMER_NAME].[CUSTOMER_ID].api.auditservicebus.com/[VERSION]/[RESOURCE])
Where
- TOKEN is the access token as described in the section Security
- CUSTOMER_NAME is a string describing your company
- CUSTOMER_ID is a unique id for your company
- VERSION describes the version of the API to be used
- RESOURCE describes the type of data being send (transaction, cancellations, etc.)
If the GET method is used, the details of the request (e.g. transactionid, amount, etc.) are provided as query string parameters. If the POST method is used, the data should be provided as a data object
The full URL for your environment can be found when generating your source connection. An example curl command to send data is
curl -H "Authorization: Bearer test_XXXXX" -H "Content-Type: application/json" -X GET "https://dev-plem.customeractuals.d02ma.api.auditservicebus.com/transaction?transactionid=1923423×tamp=2018-05-10T11:34:11Z&amount=2988"The API will return 200 status code if the data is processed correctly and will return a 400 status code is the end point is not valid.
Considerations
It is highly prefered to use a unique transactionid to deduplicate data. By default the transactionid parameter is used for that.