Settle match prediction

Developing

POST

/v1/match-predictions/{matchPredictionId}/settlements

Submit the final-time score and start asynchronous settlement.

Auth: Bearer API key with matchPredictions permission.
Idempotency: Idempotency-Key header REQUIRED. Same key + same body → original 202 (same operationId). Same key + different body → 409 IDEMPOTENCY_KEY_CONFLICT.
Async: returns 202 with operationId, statusUrl, resultsUrl. Poll GET /results to check progress (202 in-progress with retryAfterSeconds + Retry-After header; 200 when terminal).
Race isolation: while a settle or void is in-flight, a competing operation returns 409 OPERATION_IN_PROGRESS. Void winning the race → subsequent settle returns 409.
Kickoff gate: settlement before kickoffAt → 409 MATCH_NOT_STARTED.
Cross-community isolation: cross-community id returns 404 identical to unknown-id shape.
Rate limit + Freeze: standard.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢202Accepted

application/json

Settlement accepted. Poll resultsUrl to check terminal state.

Bodyapplication/json

🟠400Validation failed

🟠401Unauthorized

🟠403Forbidden

🟠404Not found

🟠409Conflict

🟠429Rate limited

🔴500Internal error

🔴503Frozen / Queue unavailable

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://adss-integration.returning.ai/apis/v1/match-predictions/mp_01abc/settlements' \
--header 'Idempotency-Key: 01HXYZABCDEFG1234567890' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "fullTimeScore": { "teamA": 2, "teamB": 1 }
}'

Response Example

202 - Accepted

{
  "meta": {
    "status": "success",
    "statusCode": 202,
    "code": "MATCH_PREDICTION_SETTLEMENT_ACCEPTED",
    "requestId": "req_01abc",
    "timestamp": "2026-08-07T12:00:00.000Z"
  },
  "message": "Settlement accepted.",
  "data": {
    "operationId": "mps_01xyz",
    "type": "settlement",
    "status": "settlement_in_progress",
    "submittedAt": "2026-08-07T12:00:00.000Z",
    "resultsUrl": "/v1/match-predictions/mp_01abc/results"
  }
}

Modified at 2026-09-25 08:29:20

Publish match prediction

Get settlement results