Create Liveblog from external source

This endpoint is only available for customers who have booked this feature. Please ensure your organization has access before using this API.

Overview

This endpoint allows you to create a liveblog for a sports event using data fetched from an external provider. The API pre-fills the liveblog with match data such as teams, players, and scoreboard information. Additionally, automatic posting of events like goals, cards, or substitutions can be configured.

Endpoint

POST /apigw/sports/v2/{organizationId}/liveblog/createFromExternal

Path Parameters

  • organizationId (string, required): The ID of your organization.

Request Body

The request body should contain the following fields:

  • provider (string, required): The name of the external data provider. Supported values are gn-gsd (Gracenote) and heim (Heimspiel); see the provider sections below for the sport types and events each supports.
  • matchId (string, optional): The ID of the match to fetch from the provider. Either matchId, phaseId or overallId must be provided.
  • phaseId (string, optional): The ID of the phase to fetch from the provider. Either matchId, phaseId or overallId must be provided.
  • overallId (string, optional): The ID of the overall to fetch from the provider. Either matchId, phaseId or overallId must be provided. If phaseId and overallId are supplied at the same time, phaseId is preferred.
  • title (string, optional): Custom title for the liveblog. If not provided, a default title will be generated based on the match data.
  • locale (string, optional): The locale for the liveblog content. Defaults to “en”.
  • includeTextContent (boolean, optional): Whether to include editorial text content from the provider (e.g. Heimspiel liveticker commentary) in the created content stream — standalone commentary posts as well as narrative attached to match events. When autoPostEnabled is set, the text content is posted automatically too. Defaults to false. Only available for provider heim with sport types soccer, icehockey, tennis, american_football and motorsports, and only when your organization’s Heimspiel endpoint delivers liveticker content — requesting it otherwise is rejected with 400 Bad Request. Contact Tickaroo support if you are unsure whether your setup includes it.
  • autoPostEnabled (boolean, optional): Whether automatic posting of match events is enabled.
  • autoPostConfiguration (AutoPostConfiguration, optional): Configuration for automatic posting if autoPostEnabled is set to true. The configuration can include options to exclude specific events or scoreboards. Everything will be synced if object is missing.

AutoPostConfiguration

  • excludeScoreboard (boolean, optional): Whether to exclude the scoreboard from automatic posting.
  • excludeEvents (string[], optional): An array of event types to exclude from automatic posting.

Auto Post Configuration Example

If you enable automatic posting, the autoPostConfiguration field can be structured like this:

{
  "excludeScoreboard": true,
  "excludeEvents": ["soccer.goal"]
}

Provider

Provider: Heimspiel

  • ID: heim
  • Supported Sport Types:
    • soccer
      • Supported Events:
        • soccer.goal
        • soccer.own-goal
        • soccer.yellow-card
        • soccer.red-card
        • soccer.yellow-red-card
        • soccer.penalty-kick-missed
        • soccer.substitution
        • soccer.start
        • soccer.pause-halves
        • soccer.resume-halves
        • soccer.end-of-regular-play
        • soccer.start-overtime
        • soccer.pause-overtime
        • soccer.resume-overtime
        • soccer.end-of-overtime
        • soccer.start-shootout
        • soccer.end
      • Scoreboard: true
    • tennis
      • Supported Events:
        • tennis.game-win
        • tennis.start
        • tennis.end
      • Scoreboard: true
    • american_football
      • Supported Events: (No events supported yet)
      • Scoreboard: true
    • motorsports
      • Supported Events:
        • motorsports.crash
        • motorsports.overtake
        • motorsports.pit-stop
        • motorsports.fastest-lap
        • motorsports.penalty
        • motorsports.team-radio
        • motorsports.weather-info
        • motorsports.safety-car
        • motorsports.virtual-safety-car
        • motorsports.red-flag
        • motorsports.yellow-flag
        • motorsports.start
        • motorsports.end
        • motorsports.podium
      • Scoreboard: false

Provider: Gracenote

  • ID: gn-gsd
  • Supported Sport Types:
    • soccer
      • Supported Events:
        • soccer.goal
        • soccer.yellow-card
        • soccer.red-card
        • soccer.substitution
        • soccer.penalty-kick-missed
      • Scoreboard: true
    • cycling
      • Supported Events: (No events supported yet)
      • Scoreboard: false

Responses

Success

Errors

Error responses carry a JSON body:

{
  "code": "not_found",
  "message": "Match not found",
  "field": "configuration.matchId",
  "retryable": false
}
  • code (string): Stable machine-readable error code: invalid_request, not_found, forbidden, downstream_rejected, upstream_unavailable or internal.
  • message (string): Human-readable description.
  • field (string, optional): The request field that caused the error, if attributable.
  • retryable (boolean): Whether retrying the same request later can succeed. false means the request itself must be changed — do not retry unchanged.

Status codes:

  • 400 Bad Request: The request is malformed, required data is missing, or the referenced sport/operation is not supported.
  • 403 Forbidden: Your organization is not authorized for the requested data source.
  • 404 Not Found: The specified route, data source provider, or match is not found.
  • 422 Unprocessable Entity: Validation of the request data fails (e.g., matchId, phaseId and overallId are missing).
  • 503 Service Unavailable: The external sport data provider is temporarily unavailable. Retry later (retryable: true).
  • 500 Internal Server Error: Unexpected error on our side.

Example Request

POST /apigw/sports/v2/YOUR_ORGANIZATION_ID/liveblog/createFromExternal

{
  "provider": "gn-gsd",
  "matchId": "12345",
  "locale": "en",
  "autoPostEnabled": true
}