Gamification API

The Gamification system organizes performance data into campaigns, metrics, and scores, enabling companies to run automated competitions across their drivers. External systems can submit and finalize scores through the API, while campaign management and leaderboards are handled within the Hub.

Campaigns — Time-bound competitions, such as a Weekly Eco-Driving Challenge or Monthly Safety Ranking. Campaigns are created and managed inside the Hub and are not exposed for external modification.
Metrics — Defined performance categories (for example, fuel efficiency, retarder usage, or braking). Each campaign tracks scores for one specific metric, but a single metric can be used by multiple campaigns, simultaneously or at any time.
Scores — Numeric results submitted by external systems to represent a driver’s performance in a metric. Each driver can have one score per metric per day. Scores may be updated until the metric is finalized for a date. The driver with the highest total score within a campaign is ranked as the winner.
Companies and Drivers — Every score belongs to a company and a specific driver within that company.

POST scores

This endpoint uploads scores under a given metric for a specific date. If multiple submissions are made for the same driver, metric, and date, the latest score overwrites the previous one until the date is finalized.

Each request can include up to 50 drivers, and no duplicate userxtid values are allowed within a single batch. If the specified metric does not exist yet, it is created automatically. Submitted scores for a given combination of date, metric, and userxtid remain editable until the date is finalized. Multiple submissions for the same combination will overwrite the previous score, with the latest value taking precedence.

The operation is all-or-nothing: if any item in the batch is invalid or fails validation, the entire batch is rejected and no scores are written.

Request

POST /v3/igr/gamification/{copid}/scores HTTP/1.1
Host: api.instantcmr.com
Content-Type: application/json
x-icmr-auth-1: {authentication-token}

{
  "date": "YYYY-MM-DD",
  "metric": "{metric-id}",
  "scores": [
    { 
      "userxtid": "{driver-id}", 
      "score": {integer} 
    },
    ...
  ]
}

date	Date the scores apply to. Format: YYYY-MM-DD.
metric	Metric identifier. Must match `[a-zA-Z0-9_-]+`. If the metric does not exist yet, it will be created automatically with the first submission.
scores	Array of score items for the same `date` and `metric`. The batch can contain up to 50 entries.
scores[].userxtid	Driver identifier within the company context.
scores[].score	Numeric score value (integer) for the driver on the given date and metric.
authentication-token	See Authentication.

Response

HTTP/1.1 200 OK

Response codes

200 OK	Request was successful.
401 Unauthorized	Missing or invalid authentication-token.
403 Forbidden	Authenticated user does not have sufficient permission.
400 Invalid json	Request body doesn't match the specified format
412 Duplicate userxtid values in request
412 Score is already finalized
413 Batch size exceeds the limit	No more than 50 scores can be uploaded in a single request.

POST finalize scores

This endpoint finalizes a metric up to a specified date. After finalization, scores for that metric on dates up to and including the specified date can no longer be edited.

The operation is idempotent: calling it multiple times with the same date and metric returns 200 OK and makes no additional changes. If the metric has already been finalized to a later date, finalizing it again with an earlier or equal date also returns 200 OK and performs no change, as the finalization cut-off never moves backward. Finalization is therefore monotonic and non-decreasing—it can only advance or remain the same.

When scores are finalized, a background process is triggered to update the leaderboards of all campaigns that use the given metric.

Request

POST /v3/igr/gamification/{copid}/scores/finalize HTTP/1.1
Host: api.instantcmr.com
Content-Type: application/json
x-icmr-auth-1: {authentication-token}

{
  "date": "YYYY-MM-DD",
  "metric": "{metric-id}"
}

date	Finalization cut-off. All scores for the metric on dates ≤ date become read-only.
metric	Metric identifier. Must match `[a-zA-Z0-9_-]+`.
authentication-token	See Authentication.

Response

HTTP/1.1 200 OK

Response codes

200 OK	Request was successful.
401 Unauthorized	Missing or invalid authentication-token.
403 Forbidden	Authenticated user does not have sufficient permission.
400 Invalid json	Request body doesn't match the specified format