Fixture & Bot Customer Queries API

This document describes how to call the fixture and bot endpoints used for customer queries. All endpoints require authentication.

For access provisioning (M2M client creation), see API Authentication and Access.

Response samples below were captured from production on 2026-10-19 for bot 61906, Genius venue 13658 (Sportzcast venue 4320), and Genius fixture 14566239.

1. Authentication

Requests must use JWT (Bearer) authentication. Obtain a token from Auth0 using the Client Credentials grant (Machine-to-Machine), then send it in the Authorization header.

Do not use password grant or authorization-code grant for programmatic access — those are for interactive login and will fail with access_denied / Unauthorized when used from scripts.

Get an access token

Field	Production value
Token URL	`https://sportzcast.eu.auth0.com/oauth/token`
Audience	`https://servicehub.sportzcast.net/` (trailing slash required)
Grant type	`client_credentials`

Token request

POST https://sportzcast.eu.auth0.com/oauth/token
Content-Type: application/json

{
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>",
  "audience": "https://servicehub.sportzcast.net/",
  "grant_type": "client_credentials"
}

Use the client ID and client secret from your M2M Auth0 application. The app must be authorized for the Auth0 API whose Identifier is https://servicehub.sportzcast.net/.

Token response

{
  "access_token": "eyJ...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Sending authenticated requests

For every API request, include:

Header	Required	Description
`Authorization`	Yes	`Bearer <access_token>` from Auth0
`X-Username`	Yes	Sportzcast user email (same account used to log in)
`X-Token`	Yes	Sportzcast user access token from Account / UserInfo

Authenticated request example

GET https://servicehub.sportzcast.net/external/fixture/by-bot/61906
Authorization: Bearer <access_token>
X-Username: <sportzcast_user_email>
X-Token: <sportzcast_user_token>

curl (quick test)

TOKEN=$(curl -s -X POST 'https://sportzcast.eu.auth0.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>",
    "audience": "https://servicehub.sportzcast.net/",
    "grant_type": "client_credentials"
  }' | jq -r .access_token)

curl -s "https://servicehub.sportzcast.net/external/fixture/by-genius-venue/<geniusVenueId>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Username: <sportzcast_user_email>" \
  -H "X-Token: <sportzcast_user_token>"

2. Base URL

Production API host:

https://servicehub.sportzcast.net

All path examples below use this host.

3. Endpoints

3.1 Get fixtures by bot ID

Returns fixtures for a given bot. Only fixtures with start time on or after the given date (or today if omitted) are returned, ordered by start time.

GET https://servicehub.sportzcast.net/external/fixture/by-bot/{botId}

Path parameters (by bot)

Parameter	Type	Description
`botId`	integer	Bot ID

Query parameters (by bot)

Parameter	Type	Required	Description
`fixtureStartDate`	date (ISO 8601)	No	Only fixtures with `FixtureStartTime >=` this date. Default: current UTC date. Example: `2025-01-01`

Example (by bot)

GET https://servicehub.sportzcast.net/external/fixture/by-bot/61906
Authorization: Bearer <access_token>
X-Username: <sportzcast_user_email>
X-Token: <sportzcast_user_token>

Response: 200 OK — JSON array of fixture objects.

Each fixture includes id, geniusFixtureId, name, sport, competition, eventStatusType, start/end times, and a nested venue (id, geniusId, name). updatedDate and fixtureStatus may be null. Bot 62247 returned the same four fixtures as bot 61906.

[
  {
    "id": 86310,
    "geniusFixtureId": 14566239,
    "name": "BC Sabah v NTD Baku",
    "sportId": 4,
    "sportName": "Basketball",
    "competitionId": 12982,
    "competitionName": "Azerbaijan Superleague",
    "eventStatusType": "Finished",
    "createdDate": "2026-10-11T08:19:23.6169114",
    "updatedDate": "2026-10-19T19:00:24.9923678",
    "fixtureStartTime": "2026-10-19T15:00:00",
    "fixtureEndTime": "2026-10-19T19:00:24.9880971",
    "fixtureStatus": null,
    "venue": {
      "id": 4320,
      "geniusId": 13658,
      "name": "Baku Sports Palace"
    },
    "isContentGraph": false
  },
  {
    "id": 87041,
    "geniusFixtureId": 14596096,
    "name": "BC Sabah v Nakhchivan BK",
    "sportId": 4,
    "sportName": "Basketball",
    "competitionId": 12982,
    "competitionName": "Azerbaijan Superleague",
    "eventStatusType": "Notstarted",
    "createdDate": "2026-10-19T15:18:53.3513002",
    "updatedDate": null,
    "fixtureStartTime": "2026-10-23T15:00:00",
    "fixtureEndTime": "2026-10-23T19:00:00",
    "fixtureStatus": null,
    "venue": {
      "id": 4320,
      "geniusId": 13658,
      "name": "Baku Sports Palace"
    },
    "isContentGraph": false
  }
]

The live response also included two later fixtures (BC Sabah v Nanterre 92, BC Sabah v Trabzonspor BK) with the same object shape.

3.2 Get fixtures by venue ID

Returns fixtures for a given venue. Only fixtures with start time on or after the given date (or today if omitted) are returned, ordered by start time.

GET https://servicehub.sportzcast.net/external/fixture/by-venue/{venueId}

Path parameters (by venue)

Parameter	Type	Description
`venueId`	integer	Internal Sportzcast venue ID (`venue.id` in the fixture payload, not the Genius venue id)

Query parameters (by venue)

Parameter	Type	Required	Description
`fixtureStartDate`	date (ISO 8601)	No	Only fixtures with `FixtureStartTime >=` this date. Default: current UTC date. Example: `2025-01-01`

Example (by venue)

GET https://servicehub.sportzcast.net/external/fixture/by-venue/4320
Authorization: Bearer <access_token>
X-Username: <sportzcast_user_email>
X-Token: <sportzcast_user_token>

Response: 200 OK — same fixture object shape as §3.1. For Baku Sports Palace (venue.id 4320) the array matches the bot example above.

3.3 Get fixtures by Genius Sports venue ID

Same behaviour as §3.2, but the venue is identified by Genius venue ID (Venue.GeniusId) instead of the internal Sportzcast venue ID. Use this when your integration only knows the Genius Sports venue identifier.

GET https://servicehub.sportzcast.net/external/fixture/by-genius-venue/{geniusVenueId}

Path parameters (by genius venue)

Parameter	Type	Description
`geniusVenueId`	integer	Genius Sports venue ID (stored as `GeniusId` on the venue)

Query parameters (by genius venue)

Same as §3.2 (fixtureStartDate, optional; default: current UTC date).

Example (by genius venue)

GET https://servicehub.sportzcast.net/external/fixture/by-genius-venue/13658
Authorization: Bearer <access_token>
X-Username: <sportzcast_user_email>
X-Token: <sportzcast_user_token>

Response: 200 OK — same fixture array as §3.1. A production call for Genius venue 13658 returned the same four BC Sabah fixtures (first object shown below).

[
  {
    "id": 86310,
    "geniusFixtureId": 14566239,
    "name": "BC Sabah v NTD Baku",
    "sportId": 4,
    "sportName": "Basketball",
    "competitionId": 12982,
    "competitionName": "Azerbaijan Superleague",
    "eventStatusType": "Finished",
    "createdDate": "2026-10-11T08:19:23.6169114",
    "updatedDate": "2026-10-19T19:00:24.9923678",
    "fixtureStartTime": "2026-10-19T15:00:00",
    "fixtureEndTime": "2026-10-19T19:00:24.9880971",
    "fixtureStatus": null,
    "venue": {
      "id": 4320,
      "geniusId": 13658,
      "name": "Baku Sports Palace"
    },
    "isContentGraph": false
  }
]

If no venue exists for the given Genius venue ID, the response is 200 OK with an empty JSON array ([]).

3.4 Get bots by Genius fixture ID

Returns the list of bots associated with a fixture identified by its Genius fixture ID. Each bot includes venue, configurations, and current status when available.

GET https://servicehub.sportzcast.net/external/bot/by-genius-fixture/{geniusFixtureId}

Path parameters (by genius fixture)

Parameter	Type	Description
`geniusFixtureId`	integer	Genius fixture ID

Example (by genius fixture)

GET https://servicehub.sportzcast.net/external/bot/by-genius-fixture/14566239
Authorization: Bearer <access_token>
X-Username: <sportzcast_user_email>
X-Token: <sportzcast_user_token>

Response: 200 OK — JSON array of bot objects. botStatuses may be null. Nested configuration fields (homeTeam, awayTeam, vendorSportId) may also be null.

Production response for Genius fixture 14566239 (BC Sabah v NTD Baku):

[
  {
    "id": 61906,
    "venue": {
      "id": 4320,
      "name": "Baku Sports Palace",
      "geniusId": 13658
    },
    "botConfigurations": [
      {
        "id": null,
        "homeTeam": null,
        "awayTeam": null,
        "vendorSportId": null,
        "vendorSport": {
          "id": 15,
          "name": "Bicen",
          "vendorPacketCode": null,
          "eventType": {
            "id": 3,
            "name": "Basketball"
          }
        },
        "recordingConfigurationTypeId": 2
      }
    ],
    "botStatuses": null
  },
  {
    "id": 62247,
    "venue": {
      "id": 4320,
      "name": "Baku Sports Palace",
      "geniusId": 13658
    },
    "botConfigurations": [
      {
        "id": null,
        "homeTeam": null,
        "awayTeam": null,
        "vendorSportId": null,
        "vendorSport": {
          "id": 15,
          "name": "Bicen",
          "vendorPacketCode": null,
          "eventType": {
            "id": 3,
            "name": "Basketball"
          }
        },
        "recordingConfigurationTypeId": 2
      }
    ],
    "botStatuses": [
      {
        "botId": 62247,
        "botStatusType": {
          "id": 3,
          "statusType": "Disconnected"
        },
        "lastSeenDate": "2026-10-10T09:06:57.7611899Z",
        "updatedDate": "2026-10-10T16:07:06.3418608Z"
      }
    ]
  }
]

4. Error handling

Status	Meaning
401 Unauthorized	Missing or invalid `Authorization` header (expired/invalid JWT), or Auth0 token request failed
403 Forbidden	Authenticated, but the Sportzcast user (`X-Username` / `X-Token`) is not allowed to access the resource
500 Internal Server Error	Server error; response body may contain problem details

Token request failures (Auth0):

Symptom	Likely cause
`access_denied` / Unauthorized	M2M app not authorized for audience `https://servicehub.sportzcast.net/`, or wrong audience string
`unauthorized_client`	Application is not Machine-to-Machine
`invalid_client`	Wrong client id/secret, or wrong Auth0 tenant

On API error, ensure the JWT is valid and not expired, and that X-Username and X-Token match a valid Sportzcast user.