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
The Actuals (REST) API allows for real-time transaction sending by extending a company’s IT infrastructure with a small script. This script should send transactions to the Actuals platform once they are definitive. It is recommended to do this asynchronously to avoid impacting the primary workflow. The Actuals API follows a Representational State Transfer (REST) architecture.
Raw transactions endpoint (preview)
ℹ️This API is in preview state. Documentation and behaviour can be changed without notification. You can request a raw transactions API key via your implementation consultant.
You can interact with the Actuals API in
test and production mode, which allows safe experimentation without affecting production data or triggering real-world operations. The mode of your request. Test or production, is determined by the API key used for authentication.
Each request must target a single resource. The Actuals API does not support bulk operations.
Authentication
Authentication is handled via API keys. You can request keys via your Actuals implementation consultant. Keys are prefixed to indicate their mode:
prod_ for production mode
The api key is needs to be added to the request header in the ‘token’ parameter.
Raw transactions
Endpoint
This is an object representing a raw transaction coming from another application into Actuals.
🌐ENDPOINT
POST https://api.actuals.io/v1/raw_transactions
The raw transaction object
The body has a partly mandatory structure. A couple of standardized fields and an object field that can contain a custom json structure determined by the user of the API Endpoint.
the type of data that get’s shared. For example orders, invoices, payments. Each type can get their own processing logic.
a unique reference to this transaction. This id will be only processed once to the Actuals platform.
the timestamp of this object in format ‘YYYY-MM-DDTHH24:MI:SSZ’ according to iso 8601 standard.
A json representation of the raw content you want to share.
{
"type":"order",
"external_id": "123456",
"timestamp": "2025-01-01T00:00:00Z",
"object":{}
}
Example CURL
curl --location 'https://api.actuals.io/v1/raw_transactions' \
--header 'Content-Type: application/json' \
--header 'token: ••••••' \
--data '{
"type": "order",
"external_id": "123456",
"timestamp": "2025-01-01T00:00:00",
"object": {
{
"id":"order_123456",
"customer": "customer_1",
"amount": 50,
"vatamount": 10
}
}'
Idempotency/deduplication
ℹ️When processing API calls we categorize the API calls into three different statuses:
- NEW
- IGNORED
- ERROR
Usually the platform is configured to only process NEW transactions. Others are not processed but kept for debugging purposes.
flowchart TD
subgraph database
ingest_record_new
ingest_record_ignored
ingest_record_error
end
received_api_call --> |upon succesful response| compare_external_id{compare external id}
compare_external_id --> |new| ingest_record_new
compare_external_id --> |existing| comparison_content{compare contents}
comparison_content --> |identical| ingest_record_ignored
comparison_content --> |different| ingest_record_error
API details
The API is accessible over the internet and requires a specific URL, which can be obtained from your Actuals implementation consultant. It operates using HTTPS.
Request Structure
All requests to the Actuals API should be constructed with the following settings:
Method | POST
|
URL | https://{{CUSTOMER_NAME}}.{{CUSTOMER_ID}}.api.auditservicebus.com/{{VERSION}}/{{RESOURCE}}
|
Headers | Authorization: Bearer {{TOKEN}}
Content-Type: application/json
|
Body | {{OBJECT}}
|
Replace the placeholders:
- {{TOKEN}}: The access token provided by your implementation consultant
- {{CUSTOMER_NAME}}: Your environment name (provided by your implementation consultant)
- {{CUSTOMER_ID}}: A unique ID for your company (provided by your implementation consultant)
- {{VERSION}}: The version of the API to be used (provided by your implementation consultant)
- {{RESOURCE}}: The type of data being sent (a list provided by your implementation consultant)
- {{OBJECT}}: your data in JSON format
The full URL for your environment can be found when generating your source connection. An example curl command to send data is
method POST
curl --location 'https://MY_CUSTOMER_NAME.CUSTOMER_ID123.api.auditservicebus.com/1.0/RESOURCETYPETRANSACITON' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MYBEARER' \
--data '{
"transactionid": "1923423",
"timestamp": 2018-01-05T11: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.
API Rate limits
The Actuals V1 API does not enforce hard rate limits, allowing for flexible integration and usage. However, to ensure optimal performance and system stability, it is recommended to follow best practices for request management. Specifically:
- keep the number of concurrent requests to a maximum of 10.
- Additionally, limit the request rate to 1 request per second per concurrent connection, which translates to a maximum of 600 requests per minute.
Adhering to these guidelines helps prevent throttling and ensures consistent API responsiveness for all users.
ℹ️It is recommend to only use the POST method instead of the GET method for this API.
In the V1 API the GET method cannot be used to retrieve data but is used to send in data. If the GET method is used, the details of the request (e.g. transactionid, amount, etc.) are provided as query string parameters.
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.
