Skip to content

API Overview

Use the AutoROICalc API when you want another system to send business data into AutoROICalc automatically. The API is most often used for records, service-token integrations, web event collection, backend jobs, custom imports, and reporting pipelines.

This page is a practical orientation for choosing the right API path. It does not replace the generated endpoint reference.

Complete API reference

For endpoint schemas, request parameters, response models, and interactive testing, use the live API documentation.

Open API Reference

Which API Should You Use?

Use case Best fit Why
Create detailed business records from a backend Records API Gives you control over dates, sources, tags, values, raw data, and custom data.
Send records from trusted automation or scheduled jobs Service Token API Uses a service token for server-side integrations without a browser session.
Capture website actions as records Collect Web Event API Simple event collection with a tracking ID, ideal for leads, signups, purchases, and funnel events.
Import occasional batches from files File import Better for manual CSV, XML, or ARC uploads that do not need live API calls.

Common API Workflows

Typical API integrations do one or more of these tasks:

  • Create one record when an order, lead, cost, conversion, or milestone happens.
  • Create many records in a scheduled sync from another system.
  • Query records for validation, auditing, or integration checks.
  • Update a record when source-system data changes.
  • Send web events from a website, backend, tag manager, CRM, or ecommerce flow.

Authentication and Tokens

Service-token endpoints use a service token from the AutoROICalc Integrations page. Pass it only from trusted server-side code, scripts, private jobs, or backend services.

Keep tokens out of public code

Do not place service tokens in frontend JavaScript, mobile app bundles, public repositories, screenshots, browser-visible requests, or client-side configuration. Treat a service token like a password.

Web event collection uses a tracking ID instead of a service token. The tracking ID is designed for event collection, but it can still create records in your account, so use it only in places you control and validate important events on the server when possible.

Service Token API Web Event Tracking

Core Record Concepts

Most API integrations eventually create AutoROICalc records. A record normally contains:

  • date and time for when the business event happened
  • type for the kind of record, such as sale, lead, cost, or conversion
  • activity for the record state, such as open or closed
  • desc for a readable description
  • source for channels, systems, campaigns, pages, or providers
  • tags for grouping and filtering
  • value for the numeric amount used in reports
  • custom_data for stable structured details used by reports or filters
  • raw_data for original source payloads and traceability

Keep names consistent across integrations. Stable sources, tags, custom-data keys, and record types make reports easier to compare over time.

Create a Record

A service-token request can create a record from a trusted backend or job:

curl -X POST "https://api.autoroicalc.com/service_token/record?service_token=$AUTOROICALC_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-09-15",
    "time": "14:30:00",
    "type": "sale",
    "activity": "closed",
    "desc": "Order paid",
    "source": ["woocommerce"],
    "tags": ["ecommerce", "paid-order"],
    "value": 129.9,
    "custom_data": {
      "order_id": "100045",
      "campaign_id": "fall-2026"
    },
    "raw_data": {
      "provider": "woocommerce",
      "event": "order.paid"
    }
  }'

Send a Web Event

Use the Collect Web Event API when the event can use the current date and time and only needs a simple tracking payload:

https://api.autoroicalc.com/record/collect_web_event?trackingId=YOUR_TRACKING_ID&type=demo_request&desc=Demo%20request%20form%20submitted&sources=website%7Cpricing-page&value=1&tags=lead%7Cdemo

Use the full Records API instead when you need custom dates, richer JSON data, updates, or more control over the record shape.

Errors and Reliability

Handle API failures explicitly in your integration:

  • Treat 401 and 403 responses as authentication or permission problems.
  • Treat 400 and 422 responses as validation problems that need payload fixes.
  • Retry temporary 429 or 5xx responses with backoff when the operation is safe to retry.
  • Log response bodies on failed server-side jobs so invalid fields can be corrected.
  • Avoid retrying record creation blindly if duplicate records would be harmful.

Reference and Guides

API Reference Records API Guide Service Token API