📢 The Ask AI can now translate any part of the docs to your preferred language!
Read the guide
sportradar.comSportradar Support Portal

Match PLAY BY PLAY

A match involves a number of events. These events aggregate to form a play-by-play. The play-by-play assigned to a match are controlled by these calls.

Get a list play-by-play records for a match

get
/handball/o/{organizationId}/fixtures/{fixtureId}/playbyplay

Return a list of play-by-play records for a match

Required scopes
This endpoint requires the following scopes:
  • : Read any data from the organization down
Authorizations
OAuth2clientCredentialsRequired

You can create a JSON Web Token (JWT) using the token API call. Each token is given a set of scopes/permissions. Each endpoint has a scope/permission that it requires to run. If your token does not possess the correct scope then you will be unable to make the API call.

Token URL:
Path parameters
fixtureIdstring · uuidRequired

The unique identifier of the fixture

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
Query parameters
externalstringOptional

A comma separated list of fields that will instead be interpreted as an externalId. See External Ids for more information.

Example: entityId,personId
fieldsstringOptional

A comma separated list of fields to display. The response will only display these fields. See Partial Response section for more information.

Example: dob,firstName,organization(id),organizations[name], teams[name,details/metrics/*,tags(id)]
fromTimestampstring · date-timeOptional

Where the date/time (UTC) this play-by-play event was sent >= this value

Example: 2018-08-16T18:00:00
hideNullbooleanOptional

Don't display data fields with null values or empty structures

Example: true
includestringOptional

A comma separated list of resource types to include. See Resource Inclusion for more information.

Example: organizations,fixtures,entities
limitinteger · int32 · min: 1 · max: 2000Optional

The maximum number of records to return. See Pagination for more information.

Default: 1000Example: 10
offsetinteger · int32Optional

The offset of the records. See Pagination for more information.

Example: 10
periodIdinteger · enumOptional

The identifier for the period

  • 1 Period 1
  • 2 Period 2
  • 10 Extra time 1 period 1
  • 11 Extra time 1 period 2
  • 12 Extra time 2 period 1
  • 13 Extra time 2 period 2
  • 14 Shoot Out
Possible values:
toTimestampstring · date-timeOptional

Where the date/time (UTC) this play-by-play event was sent <= this value

Example: 2018-08-16T18:00:00
Responses
200

Successful operation

application/json
get
/handball/o/{organizationId}/fixtures/{fixtureId}/playbyplay
GET /v1/handball/o/{organizationId}/fixtures/{fixtureId}/playbyplay HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "meta": {
    "version": 1,
    "codeVersion": "d6cd1e2bd19e03a81132a23b2025920577f84e37",
    "code": 200,
    "time": "2018-06-05 23:43:41.227584+00:00",
    "fromCache": false,
    "count": 7,
    "limit": 10,
    "offset": 10,
    "generationTime": 0.011604
  },
  "links": {
    "self": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com"
  },
  "included": {
    "resources": {
      "ANY_ADDITIONAL_PROPERTY": "league"
    }
  },
  "data": [
    {
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "fixtureId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "fixture": {
        "resourceType": "fixtures",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "periodId": 1,
      "section": "text",
      "events": null,
      "class": "sport",
      "eventType": "substitution",
      "eventId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "playId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entityId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entity": {
        "resourceType": "entities",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "person": {
        "resourceType": "persons",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "subType": "out",
      "options": null,
      "received": 1,
      "status": "text",
      "success": true,
      "x": 56,
      "y": 23,
      "z": 10,
      "clock": "PT12M34.5S",
      "shotClock": "PT34.2S",
      "eventTime": "2016-09-08T02:02:00Z",
      "officialId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "zone": "text",
      "scores": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "timestamp": "2016-09-08T02:02:00Z",
      "clientType": "InGame",
      "clientId": "InGame:0.9",
      "sport": "h",
      "topic": "s/h/h1s44/3c467c99-9e5d-11ee-91d0-2b012330fcf5/w/e",
      "type": "event",
      "sequence": 10
    }
  ]
}

Delete all play-by-play records for a match

delete
/handball/o/{organizationId}/fixtures/{fixtureId}/playbyplay

Delete all play-by-play records for a match

Required scopes
This endpoint requires the following scopes:
  • : Write/Update any data from below the organization
Authorizations
OAuth2clientCredentialsRequired

You can create a JSON Web Token (JWT) using the token API call. Each token is given a set of scopes/permissions. Each endpoint has a scope/permission that it requires to run. If your token does not possess the correct scope then you will be unable to make the API call.

Token URL:
Path parameters
fixtureIdstring · uuidRequired

The unique identifier of the fixture

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
Query parameters
externalstringOptional

A comma separated list of fields that will instead be interpreted as an externalId. See External Ids for more information.

Example: entityId,personId
fieldsstringOptional

A comma separated list of fields to display. The response will only display these fields. See Partial Response section for more information.

Example: dob,firstName,organization(id),organizations[name], teams[name,details/metrics/*,tags(id)]
forceDeletebooleanOptional

Force a delete command to run and delete child records as well if there are existing records depending on the record.

Example: true
hideNullbooleanOptional

Don't display data fields with null values or empty structures

Example: true
includestringOptional

A comma separated list of resource types to include. See Resource Inclusion for more information.

Example: organizations,fixtures,entities
Responses
200

Successful operation

application/json
delete
/handball/o/{organizationId}/fixtures/{fixtureId}/playbyplay
DELETE /v1/handball/o/{organizationId}/fixtures/{fixtureId}/playbyplay HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "meta": {
    "version": 1,
    "codeVersion": "d6cd1e2bd19e03a81132a23b2025920577f84e37",
    "code": 200,
    "time": "2018-06-05 23:43:41.227584+00:00",
    "fromCache": false,
    "count": 7,
    "limit": 10,
    "offset": 10,
    "generationTime": 0.011604
  },
  "links": {
    "self": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com"
  },
  "included": {
    "resources": {
      "ANY_ADDITIONAL_PROPERTY": "league"
    }
  },
  "data": [
    {
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "fixtureId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "fixture": {
        "resourceType": "fixtures",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "periodId": 1,
      "section": "text",
      "events": {},
      "updated": "2025-11-19T05:21:22.831Z",
      "added": "2025-11-19T05:21:22.831Z"
    }
  ]
}

Get a list of live play-by-play records for a match

get
/handball/o/{organizationId}/fixtures/{fixtureId}/playbyplay/live

Return a list of live play-by-play records for a match. This call will return records of matches still in-progress if available. If the match is complete this call operates the same as the non 'live' route.

Rate limited to 2 requests every minute - returns HTTP 429 Too Many Requests if called more often.
Authorizations
OAuth2clientCredentialsRequired

You can create a JSON Web Token (JWT) using the token API call. Each token is given a set of scopes/permissions. Each endpoint has a scope/permission that it requires to run. If your token does not possess the correct scope then you will be unable to make the API call.

Token URL:
Available scopes:
  • : Authenticate based on a specific OrganizationId
  • : Read data over multiple organizations using and *orggroup* code
  • : Write/Update any data from below the organization
  • : Read any data from the organization down
  • : Perform administration API calls
  • : Ability to manage organizations
  • : Perform system configuration API calls
Path parameters
fixtureIdstring · uuidRequired

The unique identifier of the fixture

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
Query parameters
externalstringOptional

A comma separated list of fields that will instead be interpreted as an externalId. See External Ids for more information.

Example: entityId,personId
fieldsstringOptional

A comma separated list of fields to display. The response will only display these fields. See Partial Response section for more information.

Example: dob,firstName,organization(id),organizations[name], teams[name,details/metrics/*,tags(id)]
fromTimestampstring · date-timeOptional

Where the date/time (UTC) this play-by-play event was sent >= this value

Example: 2018-08-16T18:00:00
hideNullbooleanOptional

Don't display data fields with null values or empty structures

Example: true
includestringOptional

A comma separated list of resource types to include. See Resource Inclusion for more information.

Example: organizations,fixtures,entities
limitinteger · int32 · min: 1 · max: 2000Optional

The maximum number of records to return. See Pagination for more information.

Default: 1000Example: 10
offsetinteger · int32Optional

The offset of the records. See Pagination for more information.

Example: 10
periodIdinteger · enumOptional

The identifier for the period

  • 1 Period 1
  • 2 Period 2
  • 10 Extra time 1 period 1
  • 11 Extra time 1 period 2
  • 12 Extra time 2 period 1
  • 13 Extra time 2 period 2
  • 14 Shoot Out
Possible values:
toTimestampstring · date-timeOptional

Where the date/time (UTC) this play-by-play event was sent <= this value

Example: 2018-08-16T18:00:00
Responses
200

Successful operation

application/json
get
/handball/o/{organizationId}/fixtures/{fixtureId}/playbyplay/live
GET /v1/handball/o/{organizationId}/fixtures/{fixtureId}/playbyplay/live HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "meta": {
    "version": 1,
    "codeVersion": "d6cd1e2bd19e03a81132a23b2025920577f84e37",
    "code": 200,
    "time": "2018-06-05 23:43:41.227584+00:00",
    "fromCache": false,
    "count": 7,
    "limit": 10,
    "offset": 10,
    "generationTime": 0.011604
  },
  "links": {
    "self": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com"
  },
  "included": {
    "resources": {
      "ANY_ADDITIONAL_PROPERTY": "league"
    }
  },
  "data": [
    {
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "fixtureId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "fixture": {
        "resourceType": "fixtures",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "periodId": 1,
      "section": "text",
      "events": null,
      "class": "sport",
      "eventType": "substitution",
      "eventId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "playId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entityId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entity": {
        "resourceType": "entities",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "person": {
        "resourceType": "persons",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "subType": "out",
      "options": null,
      "received": 1,
      "status": "text",
      "success": true,
      "x": 56,
      "y": 23,
      "z": 10,
      "clock": "PT12M34.5S",
      "shotClock": "PT34.2S",
      "eventTime": "2016-09-08T02:02:00Z",
      "officialId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "zone": "text",
      "scores": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "timestamp": "2016-09-08T02:02:00Z",
      "clientType": "InGame",
      "clientId": "InGame:0.9",
      "sport": "h",
      "topic": "s/h/h1s44/3c467c99-9e5d-11ee-91d0-2b012330fcf5/w/e",
      "type": "event",
      "sequence": 10
    }
  ]
}

Get a full list of match events, suitable for subsequent import.

get
/handball/o/{organizationId}/fixtures/{fixtureId}/events/export

Includes play-by-play and setup events for a match

Authorizations
OAuth2clientCredentialsRequired

You can create a JSON Web Token (JWT) using the token API call. Each token is given a set of scopes/permissions. Each endpoint has a scope/permission that it requires to run. If your token does not possess the correct scope then you will be unable to make the API call.

Token URL:
Available scopes:
  • : Authenticate based on a specific OrganizationId
  • : Read data over multiple organizations using and *orggroup* code
  • : Write/Update any data from below the organization
  • : Read any data from the organization down
  • : Perform administration API calls
  • : Ability to manage organizations
  • : Perform system configuration API calls
Path parameters
fixtureIdstring · uuidRequired

The unique identifier of the fixture

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
Query parameters
externalstringOptional

A comma separated list of fields that will instead be interpreted as an externalId. See External Ids for more information.

Example: entityId,personId
fieldsstringOptional

A comma separated list of fields to display. The response will only display these fields. See Partial Response section for more information.

Example: dob,firstName,organization(id),organizations[name], teams[name,details/metrics/*,tags(id)]
hideNullbooleanOptional

Don't display data fields with null values or empty structures

Example: true
includestringOptional

A comma separated list of resource types to include. See Resource Inclusion for more information.

Example: organizations,fixtures,entities
limitinteger · int32 · min: 1 · max: 1000Optional

The maximum number of records to return. See Pagination for more information.

Default: 10Example: 10
offsetinteger · int32Optional

The offset of the records. See Pagination for more information.

Example: 10
onlySetupbooleanOptional

Include only setup events when exporting?

periodIdinteger · enumOptional

The identifier for the period

  • 1 Period 1
  • 2 Period 2
  • 10 Extra time 1 period 1
  • 11 Extra time 1 period 2
  • 12 Extra time 2 period 1
  • 13 Extra time 2 period 2
  • 14 Shoot Out
Possible values:
withScoresbooleanOptional

Include scores in exported events?

Responses
200

Successful operation

application/json
get
/handball/o/{organizationId}/fixtures/{fixtureId}/events/export
GET /v1/handball/o/{organizationId}/fixtures/{fixtureId}/events/export HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "meta": {
    "version": 1,
    "codeVersion": "d6cd1e2bd19e03a81132a23b2025920577f84e37",
    "code": 200,
    "time": "2018-06-05 23:43:41.227584+00:00",
    "fromCache": false,
    "count": 7,
    "limit": 10,
    "offset": 10,
    "generationTime": 0.011604
  },
  "links": {
    "self": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com"
  },
  "included": {
    "resources": {
      "ANY_ADDITIONAL_PROPERTY": "league"
    }
  },
  "data": [
    {
      "success": true
    }
  ]
}

Add or Update historical play-by-play records for a match

post
/handball/o/{organizationId}/fixtures/{fixtureId}/events/import

Depending on primary keys, Add a match play-by-play or update an existing record. This call operates in bulk for all events in a specific period. Note:This call should only be used to import historical data. Changes to current/live data show be peformed only via your live capture software. If this call is used data may become invalid as statistics/actions may not be recalculated.

Required scopes
This endpoint requires the following scopes:
  • : Perform administration API calls
Authorizations
OAuth2clientCredentialsRequired

You can create a JSON Web Token (JWT) using the token API call. Each token is given a set of scopes/permissions. Each endpoint has a scope/permission that it requires to run. If your token does not possess the correct scope then you will be unable to make the API call.

Token URL:
Path parameters
fixtureIdstring · uuidRequired

The unique identifier of the fixture

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
Query parameters
externalstringOptional

A comma separated list of fields that will instead be interpreted as an externalId. See External Ids for more information.

Example: entityId,personId
fieldsstringOptional

A comma separated list of fields to display. The response will only display these fields. See Partial Response section for more information.

Example: dob,firstName,organization(id),organizations[name], teams[name,details/metrics/*,tags(id)]
hideNullbooleanOptional

Don't display data fields with null values or empty structures

Example: true
includestringOptional

A comma separated list of resource types to include. See Resource Inclusion for more information.

Example: organizations,fixtures,entities
Responses
200

Successful operation

application/json
post
/handball/o/{organizationId}/fixtures/{fixtureId}/events/import
POST /v1/handball/o/{organizationId}/fixtures/{fixtureId}/events/import HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "meta": {
    "version": 1,
    "codeVersion": "d6cd1e2bd19e03a81132a23b2025920577f84e37",
    "code": 200,
    "time": "2018-06-05 23:43:41.227584+00:00",
    "fromCache": false,
    "count": 7,
    "limit": 10,
    "offset": 10,
    "generationTime": 0.011604
  },
  "links": {
    "self": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com"
  },
  "included": {
    "resources": {
      "ANY_ADDITIONAL_PROPERTY": "league"
    }
  },
  "data": [
    {
      "success": true
    }
  ]
}

Add an individual a match play-by-play event

post
/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay

Add a specific period play-by-play from a match event

Required scopes
This endpoint requires the following scopes:
  • : Perform administration API calls
Authorizations
OAuth2clientCredentialsRequired

You can create a JSON Web Token (JWT) using the token API call. Each token is given a set of scopes/permissions. Each endpoint has a scope/permission that it requires to run. If your token does not possess the correct scope then you will be unable to make the API call.

Token URL:
Path parameters
fixtureIdstring · uuidRequired

The unique identifier of the fixture

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
periodIdinteger · enumRequired

The identifier for the period

  • 1 Period 1
  • 2 Period 2
  • 10 Extra time 1 period 1
  • 11 Extra time 1 period 2
  • 12 Extra time 2 period 1
  • 13 Extra time 2 period 2
  • 14 Shoot Out
Possible values:
Query parameters
externalstringOptional

A comma separated list of fields that will instead be interpreted as an externalId. See External Ids for more information.

Example: entityId,personId
sectionstring · max: 100Optional

The section of the period (sub-period)

Body
fixtureIdstring · uuidOptional

The unique identifier of the match

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
periodIdinteger · enumOptional

The identifier for the period

  • 1 Period 1
  • 2 Period 2
  • 10 Extra time 1 period 1
  • 11 Extra time 1 period 2
  • 12 Extra time 2 period 1
  • 13 Extra time 2 period 2
  • 14 Shoot Out
Possible values:
sectionstring · max: 100Optional

The section of the period (sub-period)

eventsanyOptional
classstring · enum · max: 100Optional

The class of the event

  • clock Information about the current status of the clock match
  • sport A sporting action that relates to the running of the match
Default: sportExample: sportPossible values:
eventTypestring · max: 100Optional

See Event Types for more information

Example: substitution
eventIdstring · uuidOptional

Unique identifier of this event

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
playIdstring · uuidOptional

Unique identifier of this play (group of events)

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
entityIdstring · uuidOptional

The unique identifier of the team

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
personIdstring · uuidOptional

The unique identifier of the person

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
subTypestring · max: 100Optional

The Sub Type of event. See Streaming API documenation for more information.

Example: out
optionsanyOptional
receivedinteger · int32Optional

The UNIX timestamp when the event was received.

statusstringOptional

The status of this message. Options are added (Default); updated - meaning the content of this event has been edited; deleted - meaning this event has been deleted; enriched - meaning further information has been added to the event (not changed).

successbooleanOptional

Whether the action was successful

xnumber · floatOptional

The x co-ordinate of the event. Represented as percentage from left (0) to right (100).

Example: 56
ynumber · floatOptional

The y co-ordinate of the event. Represented as precentage from top (0) to bottom (100).

Example: 23
znumber · floatOptional

The z co-ordinate of the event. Represented as precentage from ground (0) to ceiling (100).

Example: 10
clockstringOptional

The time on the clock when the event occurred. ISO 8601 format. PTmmMss.ccS

Example: PT12M34.5S
shotClockstringOptional

The time on the shot clock when the event occurred. ISO 8601 format. PTss.ccS

Example: PT34.2S
eventTimestring · date-timeOptional

The date/time (UTC) this event occurred. For inserted actions, this should be the time the action would have occurred, not the time of insertion.

Example: 2016-09-08T02:02:00Z
officialIdstring · uuidOptional

The unique ID of the official making this decision

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
zonestring · max: 50Optional

See Event Types for more information

timestampstring · date-timeOptional

The date/time (UTC) this event was sent.

Example: 2016-09-08T02:02:00Z
clientTypestring · max: 200Optional

Type of the client that sent the event

Example: InGame
clientIdstring · max: 200Optional

ID of the client that sent the event

Example: InGame:0.9
sportstring · max: 1Optional

Sport one letter code

Example: h
topicstring · max: 200Optional

MQTT topic where the event was sent

Example: s/h/h1s44/3c467c99-9e5d-11ee-91d0-2b012330fcf5/w/e
typestring · max: 100Optional

Type of the event message

Example: event
sequenceinteger · int32 | nullableOptional

Client event sequence number

Example: 10
Responses
200

Successful operation

application/json
post
/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay
POST /v1/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 803

{
  "fixtureId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "periodId": 1,
  "section": "text",
  "events": null,
  "class": "sport",
  "eventType": "substitution",
  "eventId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "playId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "entityId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "subType": "out",
  "options": null,
  "received": 1,
  "status": "text",
  "success": true,
  "x": 56,
  "y": 23,
  "z": 10,
  "clock": "PT12M34.5S",
  "shotClock": "PT34.2S",
  "eventTime": "2016-09-08T02:02:00Z",
  "officialId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "zone": "text",
  "scores": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "timestamp": "2016-09-08T02:02:00Z",
  "clientType": "InGame",
  "clientId": "InGame:0.9",
  "sport": "h",
  "topic": "s/h/h1s44/3c467c99-9e5d-11ee-91d0-2b012330fcf5/w/e",
  "type": "event",
  "sequence": 10
}
{
  "meta": {
    "version": 1,
    "codeVersion": "d6cd1e2bd19e03a81132a23b2025920577f84e37",
    "code": 200,
    "time": "2018-06-05 23:43:41.227584+00:00",
    "fromCache": false,
    "count": 7,
    "limit": 10,
    "offset": 10,
    "generationTime": 0.011604
  },
  "links": {
    "self": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com"
  },
  "included": {
    "resources": {
      "ANY_ADDITIONAL_PROPERTY": "league"
    }
  },
  "data": [
    {
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "fixtureId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "fixture": {
        "resourceType": "fixtures",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "periodId": 1,
      "section": "text",
      "events": null,
      "class": "sport",
      "eventType": "substitution",
      "eventId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "playId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entityId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entity": {
        "resourceType": "entities",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "person": {
        "resourceType": "persons",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "subType": "out",
      "options": null,
      "received": 1,
      "status": "text",
      "success": true,
      "x": 56,
      "y": 23,
      "z": 10,
      "clock": "PT12M34.5S",
      "shotClock": "PT34.2S",
      "eventTime": "2016-09-08T02:02:00Z",
      "officialId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "zone": "text",
      "scores": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "timestamp": "2016-09-08T02:02:00Z",
      "clientType": "InGame",
      "clientId": "InGame:0.9",
      "sport": "h",
      "topic": "s/h/h1s44/3c467c99-9e5d-11ee-91d0-2b012330fcf5/w/e",
      "type": "event",
      "sequence": 10
    }
  ]
}

Delete a match play-by-play

delete
/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay

Delete a specific period play-by-play from a match

Required scopes
This endpoint requires the following scopes:
  • : Write/Update any data from below the organization
Authorizations
OAuth2clientCredentialsRequired

You can create a JSON Web Token (JWT) using the token API call. Each token is given a set of scopes/permissions. Each endpoint has a scope/permission that it requires to run. If your token does not possess the correct scope then you will be unable to make the API call.

Token URL:
Path parameters
fixtureIdstring · uuidRequired

The unique identifier of the fixture

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
periodIdinteger · enumRequired

The identifier for the period

  • 1 Period 1
  • 2 Period 2
  • 10 Extra time 1 period 1
  • 11 Extra time 1 period 2
  • 12 Extra time 2 period 1
  • 13 Extra time 2 period 2
  • 14 Shoot Out
Possible values:
Query parameters
externalstringOptional

A comma separated list of fields that will instead be interpreted as an externalId. See External Ids for more information.

Example: entityId,personId
fieldsstringOptional

A comma separated list of fields to display. The response will only display these fields. See Partial Response section for more information.

Example: dob,firstName,organization(id),organizations[name], teams[name,details/metrics/*,tags(id)]
forceDeletebooleanOptional

Force a delete command to run and delete child records as well if there are existing records depending on the record.

Example: true
hideNullbooleanOptional

Don't display data fields with null values or empty structures

Example: true
includestringOptional

A comma separated list of resource types to include. See Resource Inclusion for more information.

Example: organizations,fixtures,entities
sectionstring · max: 100Optional

The section of the period (sub-period)

Responses
200

Successful operation

application/json
delete
/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay
DELETE /v1/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "meta": {
    "version": 1,
    "codeVersion": "d6cd1e2bd19e03a81132a23b2025920577f84e37",
    "code": 200,
    "time": "2018-06-05 23:43:41.227584+00:00",
    "fromCache": false,
    "count": 7,
    "limit": 10,
    "offset": 10,
    "generationTime": 0.011604
  },
  "links": {
    "self": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com"
  },
  "included": {
    "resources": {
      "ANY_ADDITIONAL_PROPERTY": "league"
    }
  },
  "data": [
    {
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "fixtureId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "fixture": {
        "resourceType": "fixtures",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "periodId": 1,
      "section": "text",
      "events": {},
      "updated": "2025-11-19T05:21:22.831Z",
      "added": "2025-11-19T05:21:22.831Z"
    }
  ]
}

Update an individual a match play-by-play event

put
/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay/{eventId}

Update a specific period play-by-play from a match event

Required scopes
This endpoint requires the following scopes:
  • : Perform administration API calls
Authorizations
OAuth2clientCredentialsRequired

You can create a JSON Web Token (JWT) using the token API call. Each token is given a set of scopes/permissions. Each endpoint has a scope/permission that it requires to run. If your token does not possess the correct scope then you will be unable to make the API call.

Token URL:
Path parameters
eventIdstring · uuidRequired

The unique identifier of an event in a match

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
fixtureIdstring · uuidRequired

The unique identifier of the fixture

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
periodIdinteger · enumRequired

The identifier for the period

  • 1 Period 1
  • 2 Period 2
  • 10 Extra time 1 period 1
  • 11 Extra time 1 period 2
  • 12 Extra time 2 period 1
  • 13 Extra time 2 period 2
  • 14 Shoot Out
Possible values:
Query parameters
externalstringOptional

A comma separated list of fields that will instead be interpreted as an externalId. See External Ids for more information.

Example: entityId,personId
sectionstring · max: 100Optional

The section of the period (sub-period)

Body
eventsanyOptional
classstring · enum · max: 100Optional

The class of the event

  • clock Information about the current status of the clock match
  • sport A sporting action that relates to the running of the match
Default: sportExample: sportPossible values:
eventTypestring · max: 100Optional

See Event Types for more information

Example: substitution
eventIdstring · uuidOptional

Unique identifier of this event

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
playIdstring · uuidOptional

Unique identifier of this play (group of events)

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
entityIdstring · uuidOptional

The unique identifier of the team

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
personIdstring · uuidOptional

The unique identifier of the person

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
subTypestring · max: 100Optional

The Sub Type of event. See Streaming API documenation for more information.

Example: out
optionsanyOptional
receivedinteger · int32Optional

The UNIX timestamp when the event was received.

statusstringOptional

The status of this message. Options are added (Default); updated - meaning the content of this event has been edited; deleted - meaning this event has been deleted; enriched - meaning further information has been added to the event (not changed).

successbooleanOptional

Whether the action was successful

xnumber · floatOptional

The x co-ordinate of the event. Represented as percentage from left (0) to right (100).

Example: 56
ynumber · floatOptional

The y co-ordinate of the event. Represented as precentage from top (0) to bottom (100).

Example: 23
znumber · floatOptional

The z co-ordinate of the event. Represented as precentage from ground (0) to ceiling (100).

Example: 10
clockstringOptional

The time on the clock when the event occurred. ISO 8601 format. PTmmMss.ccS

Example: PT12M34.5S
shotClockstringOptional

The time on the shot clock when the event occurred. ISO 8601 format. PTss.ccS

Example: PT34.2S
eventTimestring · date-timeOptional

The date/time (UTC) this event occurred. For inserted actions, this should be the time the action would have occurred, not the time of insertion.

Example: 2016-09-08T02:02:00Z
officialIdstring · uuidOptional

The unique ID of the official making this decision

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
zonestring · max: 50Optional

See Event Types for more information

timestampstring · date-timeOptional

The date/time (UTC) this event was sent.

Example: 2016-09-08T02:02:00Z
clientTypestring · max: 200Optional

Type of the client that sent the event

Example: InGame
clientIdstring · max: 200Optional

ID of the client that sent the event

Example: InGame:0.9
sportstring · max: 1Optional

Sport one letter code

Example: h
topicstring · max: 200Optional

MQTT topic where the event was sent

Example: s/h/h1s44/3c467c99-9e5d-11ee-91d0-2b012330fcf5/w/e
typestring · max: 100Optional

Type of the event message

Example: event
sequenceinteger · int32 | nullableOptional

Client event sequence number

Example: 10
Responses
200

Successful operation

application/json
put
/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay/{eventId}
PUT /v1/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay/{eventId} HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 722

{
  "events": null,
  "class": "sport",
  "eventType": "substitution",
  "eventId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "playId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "entityId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "subType": "out",
  "options": null,
  "received": 1,
  "status": "text",
  "success": true,
  "x": 56,
  "y": 23,
  "z": 10,
  "clock": "PT12M34.5S",
  "shotClock": "PT34.2S",
  "eventTime": "2016-09-08T02:02:00Z",
  "officialId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "zone": "text",
  "scores": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "timestamp": "2016-09-08T02:02:00Z",
  "clientType": "InGame",
  "clientId": "InGame:0.9",
  "sport": "h",
  "topic": "s/h/h1s44/3c467c99-9e5d-11ee-91d0-2b012330fcf5/w/e",
  "type": "event",
  "sequence": 10
}
{
  "meta": {
    "version": 1,
    "codeVersion": "d6cd1e2bd19e03a81132a23b2025920577f84e37",
    "code": 200,
    "time": "2018-06-05 23:43:41.227584+00:00",
    "fromCache": false,
    "count": 7,
    "limit": 10,
    "offset": 10,
    "generationTime": 0.011604
  },
  "links": {
    "self": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com"
  },
  "included": {
    "resources": {
      "ANY_ADDITIONAL_PROPERTY": "league"
    }
  },
  "data": [
    {
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "fixtureId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "fixture": {
        "resourceType": "fixtures",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "periodId": 1,
      "section": "text",
      "events": null,
      "class": "sport",
      "eventType": "substitution",
      "eventId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "playId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entityId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entity": {
        "resourceType": "entities",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "person": {
        "resourceType": "persons",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "subType": "out",
      "options": null,
      "received": 1,
      "status": "text",
      "success": true,
      "x": 56,
      "y": 23,
      "z": 10,
      "clock": "PT12M34.5S",
      "shotClock": "PT34.2S",
      "eventTime": "2016-09-08T02:02:00Z",
      "officialId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "zone": "text",
      "scores": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "timestamp": "2016-09-08T02:02:00Z",
      "clientType": "InGame",
      "clientId": "InGame:0.9",
      "sport": "h",
      "topic": "s/h/h1s44/3c467c99-9e5d-11ee-91d0-2b012330fcf5/w/e",
      "type": "event",
      "sequence": 10
    }
  ]
}

Delete a match play-by-play event

delete
/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay/{eventId}

Delete a specific period play-by-play from a match event

Required scopes
This endpoint requires the following scopes:
  • : Perform administration API calls
Authorizations
OAuth2clientCredentialsRequired

You can create a JSON Web Token (JWT) using the token API call. Each token is given a set of scopes/permissions. Each endpoint has a scope/permission that it requires to run. If your token does not possess the correct scope then you will be unable to make the API call.

Token URL:
Path parameters
eventIdstring · uuidRequired

The unique identifier of an event in a match

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
fixtureIdstring · uuidRequired

The unique identifier of the fixture

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
periodIdinteger · enumRequired

The identifier for the period

  • 1 Period 1
  • 2 Period 2
  • 10 Extra time 1 period 1
  • 11 Extra time 1 period 2
  • 12 Extra time 2 period 1
  • 13 Extra time 2 period 2
  • 14 Shoot Out
Possible values:
Query parameters
externalstringOptional

A comma separated list of fields that will instead be interpreted as an externalId. See External Ids for more information.

Example: entityId,personId
fieldsstringOptional

A comma separated list of fields to display. The response will only display these fields. See Partial Response section for more information.

Example: dob,firstName,organization(id),organizations[name], teams[name,details/metrics/*,tags(id)]
hideNullbooleanOptional

Don't display data fields with null values or empty structures

Example: true
includestringOptional

A comma separated list of resource types to include. See Resource Inclusion for more information.

Example: organizations,fixtures,entities
sectionstring · max: 100Optional

The section of the period (sub-period)

Responses
200

Successful operation

application/json
delete
/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay/{eventId}
DELETE /v1/handball/o/{organizationId}/fixtures/{fixtureId}/periods/{periodId}/playbyplay/{eventId} HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "meta": {
    "version": 1,
    "codeVersion": "d6cd1e2bd19e03a81132a23b2025920577f84e37",
    "code": 200,
    "time": "2018-06-05 23:43:41.227584+00:00",
    "fromCache": false,
    "count": 7,
    "limit": 10,
    "offset": 10,
    "generationTime": 0.011604
  },
  "links": {
    "self": "https://example.com",
    "next": "https://example.com",
    "previous": "https://example.com"
  },
  "included": {
    "resources": {
      "ANY_ADDITIONAL_PROPERTY": "league"
    }
  },
  "data": [
    {
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "fixtureId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "fixture": {
        "resourceType": "fixtures",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "periodId": 1,
      "section": "text",
      "events": null,
      "class": "sport",
      "eventType": "substitution",
      "eventId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "playId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entityId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "entity": {
        "resourceType": "entities",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "person": {
        "resourceType": "persons",
        "id": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc"
      },
      "subType": "out",
      "options": null,
      "received": 1,
      "status": "text",
      "success": true,
      "x": 56,
      "y": 23,
      "z": 10,
      "clock": "PT12M34.5S",
      "shotClock": "PT34.2S",
      "eventTime": "2016-09-08T02:02:00Z",
      "officialId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "zone": "text",
      "scores": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "timestamp": "2016-09-08T02:02:00Z",
      "clientType": "InGame",
      "clientId": "InGame:0.9",
      "sport": "h",
      "topic": "s/h/h1s44/3c467c99-9e5d-11ee-91d0-2b012330fcf5/w/e",
      "type": "event",
      "sequence": 10
    }
  ]
}
PreviousAwardsNextMatch External PLAY BY PLAY

Last updated

Was this helpful?