API reference / Gamification / Match Predictions

Bulk update match predictions

Change up to 100 match predictions in one request, as a background job that applies each change like Patch match prediction.

Last updated 26 Sep 2026API v1

Method: POST
Path: https://api.returning.ai/v1/match-predictions/bulk-updates
Permission: matchPredictions
Retries: Idempotency-Key required; same key and body returns the same job

When to use this

A round of fixtures is rescheduled, and many kickoff times move.
Your sports data feed sends a batch of corrections to titles or times.
You set up many drafts and want to change their rewards before publishing.

Authentication#

Header: Authorization: Bearer <API_KEY>
Permission: matchPredictionsShown in the dashboard as “Match Prediction”

Use a Community API key with matchPredictions, shown in the dashboard as Match Prediction, and keep it on your server. The key decides the community: you only see and change match predictions in that community, and an ID from another community returns 404, the same as an unknown ID. Personal API keys are rejected with 403.

Behaviour#

api.returning.ai doesn't serve this route yet: requests return an empty 404. Ask Returning.AI before you build on it.

A 202 means the job is queued; the changes haven't been made yet. A job can wait a while before it starts. Each item is then applied in order with the same rules as Patch match prediction: the version must match, fields locked after publishing stay locked, and published times only move later. An item that fails doesn't undo the others, and the job goes on to the next item.

One difference: the job doesn't check the order of the times, that kickoffAt is in the future, or that entryCost.coins is 0 when entry cost is off. Patch match prediction rejects those; here they are saved. Check them before you send.

A bulk update only changes fields. It can't publish, settle or void a match. Job records are kept for 7 days.

Request#

Headers#

Authorization#stringREQUIRED

Community API key with matchPredictions.

RuleBearer <API_KEY>

Idempotency-Key#stringREQUIRED

A unique key you create for this job, such as a UUID. Reuse it only to retry the same body.

Rule1-255 characters

Eg"3f9c2a7e-1b4d-4e8a-9c61-2d5f7a8b9e10"

Content-Type#stringREQUIRED

Request body format. Anything else returns 415.

Ruleapplication/json

X-Request-Id#stringOPTIONAL

Your own ID for this request, returned in meta.requestId. Without it, a req_... ID is generated.

Body#

Send items, 1-100 of them, each with matchPredictionId, version and changes. A match can appear only once. changes takes the same fields as Patch match prediction, without version; an unknown field in changes rejects the whole request, while an unknown field on an item itself is ignored.

items#object[]REQUIRED

The changes, one item per match prediction. Applied in this order.

Rule1-100 items; each match once

Eg[ ... ]

matchPredictionId#stringREQUIRED

The match prediction to change. An unknown ID fails that item only.

Rulemp_ and 24 hex characters

Eg"mp_66f000000000000000000801"

version#integerREQUIRED

The version you last read for this match.

RuleWhole number, 1 or more

Eg2

changes#objectREQUIRED

The fields to change, as in Patch match prediction but without version. At least one field.

Eg{ "kickoffAt": "2026-10-10T19:30:00.000Z" }

curl --request POST \
  --url https://api.returning.ai/v1/match-predictions/bulk-updates \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: 3f9c2a7e-1b4d-4e8a-9c61-2d5f7a8b9e10' \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "matchPredictionId": "mp_66f000000000000000000801",
        "version": 2,
        "changes": {
          "lockAt": "2026-10-10T19:25:00.000Z",
          "kickoffAt": "2026-10-10T19:30:00.000Z"
        }
      },
      {
        "matchPredictionId": "mp_66f000000000000000000807",
        "version": 1,
        "changes": {
          "title": "Japan vs Fiji"
        }
      }
    ]
  }'

Response#

A 202 returns the job ID as operationId, with the URLs of its status and results.

meta#objectALWAYS

Result details.

status#stringALWAYS

Result of the request.

Rulesuccess

statusCode#integerALWAYS

The HTTP status, repeated.

code#stringALWAYS

Machine-readable result code.

RuleMATCH_PREDICTION_BULK_UPDATE_ACCEPTED

requestId#stringALWAYS

Your X-Request-Id if you sent one, otherwise a generated req_... ID. Quote it when you contact support.

message#stringALWAYS

Human-readable summary. Do not branch on it.

data#objectALWAYS

The job.

operationId#stringALWAYS

The job ID. Use it with the job status and results endpoints.

Rulempbu_ and 32 hex characters

type#stringALWAYS

Always bulk_update.

status#stringALWAYS

Always queued in this response, even on a replay. Check the job status for the real state.

submitted#integerALWAYS

Items in the job.

statusUrl#stringALWAYS

Where to check the job, without the host.

resultsUrl#stringALWAYS

Where to read each item's result, without the host.

{
  "meta": {
    "status": "success",
    "statusCode": 202,
    "code": "MATCH_PREDICTION_BULK_UPDATE_ACCEPTED",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Bulk update accepted.",
  "data": {
    "operationId": "mpbu_66f00000000000000000000000000802",
    "type": "bulk_update",
    "status": "queued",
    "submitted": 2,
    "statusUrl": "/v1/match-predictions/bulk-jobs/mpbu_66f00000000000000000000000000802",
    "resultsUrl": "/v1/match-predictions/bulk-jobs/mpbu_66f00000000000000000000000000802/results"
  }
}

Errors#

Every error carries its code in meta.code and the request's ID in meta.requestId. Validation errors list each problem in details, with a field, code and message. The API key checks (401, 403, 404 COMMUNITY_NOT_FOUND and 500 AUTHENTICATION_FAILED) return detail and solution instead. A 404 with an empty body means the route isn't available on api.returning.ai yet. Problems with single items don't appear here; read them with Get bulk job results.

Fix the request10

404Fix the request

The body is empty: api.returning.ai doesn't serve this route yet. Ask Returning.AI before you build on it.

400MATCH_PREDICTION_VALIDATION_FAILEDFix the request

The request as a whole is invalid. details[].code says why: EMPTY_ITEMS (no items), TOO_MANY_ITEMS (over 100), DUPLICATE_ITEM_ID (a match appears twice), EMPTY_UPDATE (an item changes nothing), or a field that breaks its rule or isn't recognised. No job was created.

400READ_ONLY_FIELDFix the request

The request has a field the server sets, such as communityId or serverId, at the top of the body. details names it. Remove it.

400INVALID_JSONFix the request

The body is not valid JSON. Fix the syntax and send it again.

400IDEMPOTENCY_KEY_REQUIREDFix the request

Send an Idempotency-Key header with a unique value.

400IDEMPOTENCY_KEY_INVALIDFix the request

The Idempotency-Key is longer than 255 characters. Use a shorter key, such as a UUID.

415UNSUPPORTED_MEDIA_TYPEFix the request

Send the body as JSON with Content-Type: application/json.

401AUTHENTICATION_REQUIREDFix the request

The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.

403API_KEY_PERMISSION_DENIEDFix the request

The key lacks matchPredictions, or it is a personal key. Use a Community API key and add Match Prediction in Settings > Integration > API Keys.

409IDEMPOTENCY_KEY_CONFLICTFix the request

This Idempotency-Key was already used with a different body. Use a new key for a new body.

Fix the data01

404COMMUNITY_NOT_FOUNDFix the data

The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff05

429RATE_LIMITEDRetry with backoff

Your community is over its rate limit. Wait for the seconds in Retry-After, then retry.

500INTERNAL_ERRORRetry with backoff

The outcome is unclear. Send the same body again with the same Idempotency-Key: if the job was created, you get it back.

500AUTHENTICATION_FAILEDRetry with backoff

The key could not be checked. Retry with backoff; nothing changed.

503MATCH_PREDICTION_BULK_UPDATE_QUEUE_UNAVAILABLERetry with backoff

The job couldn't be queued and was removed. Retry later with a new Idempotency-Key: the same key returns this 503 again.

503MATCH_PREDICTION_FROZENRetry with backoff

Returning.AI has paused match prediction requests. Nothing changed. Retry later with backoff.

{
  "meta": {
    "status": "success",
    "statusCode": 202,
    "code": "MATCH_PREDICTION_BULK_UPDATE_ACCEPTED",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Bulk update accepted.",
  "data": {
    "operationId": "mpbu_66f00000000000000000000000000802",
    "type": "bulk_update",
    "status": "queued",
    "submitted": 2,
    "statusUrl": "/v1/match-predictions/bulk-jobs/mpbu_66f00000000000000000000000000802",
    "resultsUrl": "/v1/match-predictions/bulk-jobs/mpbu_66f00000000000000000000000000802/results"
  }
}

Next step#

Get bulk job statusGET/v1/match-predictions/bulk-jobs/{jobId}Check the job with its operationId until it is completed or completed_with_errors.

Read each item's result with Get bulk job results

Bulk update match predictions

When to use this

01Authentication#

02Behaviour#

03Request#