API - Track History

1. Presentation

Our API is intended for purely professional use. It enables server-to-server (S2S) communication between your server and the Track History server.

The main advantage of the API is the automation of your events. If you have a website or platform that conducts real-time transactions, you obviously won't want to manually report each transaction to your Track History account.

Additionally, the API also allows you to:

List your events
Manage your groups
Manage your categories
Manage your value types

2. Prerequisites

Have a server capable of sending HTTP requests
Purchase API requests on Track History
Have some technical knowledge or hire a developer *

* If you do not have a developer, we can handle the installation if your infrastructure allows it. This is however a paid service.

3. Steps to obtain a private key

Create an account on Track History
Purchase API requests
Go to My API Accounts
Make sure you have at least one Active account
Copy the private key

The private key is only partially displayed on the interface! Clicking on it will allow you to copy it in full.

Warning! A private key should only be used on the backend. Do not use it on the frontend (HTML, JavaScript, or any code that can be directly read in the browser).

Only use the API if you know exactly what you're doing, as it poses a potential security risk to your Track History account.

4. How to use the key in your requests?

Send your private key in the Authorization header, as a Bearer token. The X-Api-Key header is accepted too. Never put it in the URL: it would end up in server logs.

In the examples below, replace your_private_key with the private key you copied.

1. Authorization header (recommended)

curl https://api.track-history.com/event \
  -H "Authorization: Bearer your_private_key"

2. X-Api-Key header

curl https://api.track-history.com/event \
  -H "X-Api-Key: your_private_key"

Each request made with a key uses one request from your stock. Once it is used up, the API answers 401 with the error api_request_limit_reached.

5. Requests

API access URL: https://api.track-history.com

The parameters sent and the responses are always in JSON : Content-Type: application/json

Dates are written YYYY-MM-DD HH:MM:SS, in local time, without a time zone.
A creation answers 201 with the created object, id included.
An update (PATCH) only changes the fields sent and answers with the updated object.
A deletion answers {"success": true}.
Lists (defaultValues, values) replace the existing list when sent: keep the id of the items to keep.

Errors

An error answers with an HTTP status and an error object giving the reason:

{
    "error": "event_not_found"
}

400 invalid data, for instance a fulfilled event without an end date (ending_date_required)
401 missing or invalid key, or request stock used up (api_request_limit_reached)
402 a limit of your plan reached, for instance the number of groups
404 resource not found on your account

> Group

Name	Route	Parameters / Response
List of groups	`GET /event-group`	Response `[ { "id": 1, "name": "Expenses", "description": "Analyze the amounts used each month", "photoId": null, "defaultValues": [ { "id": 7, "eventValueTypeId": 3, "value": "10" } ] } ]`
Count groups	`GET /event-group/count`	Response `1`
Retrieve a group	`GET /event-group/{id}`	Response : a group object, as in the list
Create a group	`POST /event-group`	Parameters `{ "name": "Expenses", "description": "Analyze the amounts used each month", "defaultValues": [ { "eventValueTypeId": 3, "value": "10" } ] }` Response (201) : the created group, in the same format as GET /event-group/{id}
Update a group	`PATCH /event-group/{id}`	Same parameters as the creation, all optional. Response: the updated object.
Delete a group	`DELETE /event-group/{id}`	Response `{"success": true}`

> Category

Name	Route	Parameters / Response
List of categories	`GET /event-type`	Response `[ { "id": 32, "name": "Rent", "description": "850 €/month", "eventGroupId": 1, "photoId": null, "defaultValues": [] } ]`
Retrieve a category	`GET /event-type/{id}`	Response : a category object, as in the list
Create a category	`POST /event-type`	Parameters `{ "name": "Rent", "description": "850 €/month", "eventGroupId": 1, "defaultValues": [] }` Response (201) : the created category, in the same format as GET /event-type/{id}
Update a category	`PATCH /event-type/{id}`	Same parameters as the creation, all optional. Response: the updated object.
Delete a category	`DELETE /event-type/{id}`	Response `{"success": true}`

> Value Type

Name	Route	Parameters / Response
List of value types	`GET /event-value-type`	Response `[ { "id": 3, "name": "Amount", "symbol": "€", "totalFormula": "sum", "criticalMin": null, "criticalMax": "1000" } ]` `totalFormula`: how values add up, one of `sum`, `avg`, `median`, `min`, `max`, `count`, `first`, `last`.
Retrieve a value type	`GET /event-value-type/{id}`	Response : a value type object, as in the list
Create a value type	`POST /event-value-type`	Parameters `{ "name": "Amount", "symbol": "€", "totalFormula": "sum", "criticalMin": null, "criticalMax": "1000" }` Response (201) : the created value type, in the same format as GET /event-value-type/{id}
Update a value type	`PATCH /event-value-type/{id}`	Same parameters as the creation, all optional. Response: the updated object.
Delete a value type	`DELETE /event-value-type/{id}`	Response `{"success": true}`

> Event

Name	Route	Parameters / Response
List of events	`GET /event`	Query parameters, all optional: `limit`, `offset` : pagination (without limit, every event) `sort` : `DESC` (default) or `ASC`, by start date `trackingStartingDate`, `trackingEndingDate` : bounds of the period `eventGroupIds`, `eventTypeIds`, `eventValueTypeIds`, `status` : comma-separated lists `identifier` : the events of exactly this identifier `keyword` : searches the name, description, identifier, group, category and value types Response [ { "id": 2356, "name": "July Rent", "description": "The landlord has raised the prices again", "identifier": "flat-12", "status": "normal", "selfFulfilled": false, "trackingStartingDate": "2026-07-01 00:00:00", "trackingEndingDate": "2026-07-31 23:59:59", "notificationDate": null, "eventGroupId": 1, "eventGroupName": "Expenses", "eventTypeId": 32, "eventTypeName": "Rent", "apiAccountId": 4, "photoId": null, "fileCount": 0, "values": [ { "id": 911, "eventValueTypeId": 3, "eventValueTypeName": "Amount", "eventValueTypeSymbol": "€", "value": "850" } ], "creationDate": "2026-07-01 08:12:40", "updateDate": "2026-07-01 08:12:40" } ]
Count events	`GET /event/count`	Takes the same filters as the list. `496`
Retrieve an event	`GET /event/{id}`	Response : an event object, as in the list
Create an event	`POST /event`	Parameters `{ "name": "July Rent", "description": "The landlord has raised the prices again", "identifier": "flat-12", "status": "normal", "selfFulfilled": false, "trackingStartingDate": "2026-07-01 00:00:00", "trackingEndingDate": "2026-07-31 23:59:59", "eventGroupId": 1, "eventTypeId": 32, "values": [ { "eventValueTypeId": 3, "value": "850" } ] }` `status`: `normal`, `awaiting`, `fulfilled` or `missed`. Without `trackingStartingDate` and `trackingEndingDate`, the event starts and ends now; `"trackingEndingDate": null` leaves it ongoing. A `fulfilled` event needs an end date. "identifier" is optional and free-form: what the event is about (a player, a machine, an order…). Two events with the same identifier are about the same thing, which lets you count distinct identifiers and filter with GET /event?identifier=… Response (201) : the created event, in the same format as GET /event/{id}
Update an event	`PATCH /event/{id}`	Same parameters as the creation, all optional. Sending `"identifier": null` removes the identifier. A key can only update or delete the events it created and those entered in the application. Response: the updated object.
Delete an event	`DELETE /event/{id}`	Response `{"success": true}`

API Documentation