6. Actuals API

⚡

The Actuals raw transactions API lets your systems POST individual records in near real time (for example from a website or backend when an order becomes definitive).

Validate completeness carefully — this path sends one resource per request (no bulk POST).

Authentication

Use an administration API key in the token request header.

Test keys are prefixed test_

Production keys are prefixed prod_

bash
POST 'https://api.actuals.io/v1/raw_transactions' \
  --header 'token: ••••••' \
  --header 'Content-Type: application/json'

HTTPS is required. Contact Actuals for keys for your administration.

POST body (V1)

Property	Required	Description
`type`	yes	Dataset kind (for example `order`, `invoice`, `payment`)
`external_id`	yes	Unique id; processed once
`timestamp`	yes	ISO 8601, e.g. `2025-01-01T00:00:00Z`
`object`	yes	Custom JSON payload

Example:

json
{
  "type": "order",
  "external_id": "123456",
  "timestamp": "2025-01-01T00:00:00Z",
  "object": {
    "my_custom_object_key1": "my_custom_object_value1"
  }
}

Idempotency

Calls are categorized as NEW, IGNORED (same external_id + identical content), or ERROR (same id, different content). Processing usually keeps NEW only; others remain for debugging.

GET for completeness checks

GET https://api.actuals.io/v1/raw_transactions with required timestamp_gte and timestamp_lt (business event time, max ~1 month / 32-day window per docs).

Optional: type, expand=raw_transactions, limit (max 500), cursor.

No concurrency: keep concurrent GETs to 1

Records can take up to 4 hours after POST to appear on GET

Best practice: daily CRON comparing counts to your backend; if mismatched, expand and reconcile missing external_ids, then resend.

In the new app

API-ingested rows show up like other imports under Import › Files / Raw Data Explorer, then flow through Transformation.

Security & Privacy — HTTPS and API-key auth

Data integration hub — when to prefer connectors vs API