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

Persons

A Person is a human being involved (playing in, organizing, officiating or in some other way) with the organization.

A person belongs to only one organization. While logically a person could be involved over the course of their career in multiple organizations, in most cases (for the purpose of this API) they are treated as a different person.

A person belongs in teams, matches, competitions etc by virtue of their season rosters, fixture rosters or roles.

Get a list of persons

get
/badminton/o/{organizationId}/persons

Return a list of available persons

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
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
Query parameters
addedstring · date-timeOptional

Record was added after this date/time. In UTC.

Example: 2018-08-16T02:10:48
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)]
genderstring · enumOptional

The gender of the person

  • FEMALE Female
  • MALE Male
  • UNKNOWN Unknown
Example: MALEPossible values:
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
nameFamilyLatinStartsWithstring · max: 50Optional

Family latin name starts with

nameFamilyLocalStartsWithstring · max: 50Optional

Family local name starts with

nameFullLatinstring · max: 50Optional

The full name of the person in latin characters

nameFullLatinContainsstring · min: 2 · max: 50Optional

Fields that allow a 'Contains' query string parameter search for words separated by a space, matching characters left to right. Example: nameFullLatin=David Johnson nameFullLatinContains=Dav will match nameFullLatinContains=John will match nameFullLatinContains=son will not match

Example: Dav and nameFullLatin='David Johnson'
nameFullLocalstring · max: 50Optional

The full name of the person

nameFullLocalContainsstring · min: 2 · max: 50Optional

Fields that allow a 'Contains' query string parameter search for words separated by a space, matching characters left to right. Example: nameFullLocal=David Johnson nameFullLocalContains=Dav will match nameFullLocalContains=John will match nameFullLocalContains=son will not match

Example: Dav and nameFullLocal='David Johnson'
nationalitystring · min: 3 · max: 3Optional

A 3 letter nationality code

Example: AUS
offsetinteger · int32Optional

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

Example: 10
personIdsstring · uuidOptional

The unique identifiers of the persons (comma-delimited).

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc,de83c6a8-3b29-11eb-bdb7-0242ac130005
representingstring · max: 100Optional

Who the person was representing

Example: AUSTRALIA
representingCountrystring · enumOptional

What country representation is used

  • ANY Any country
  • NONE No country
Possible values:
sortBystringOptional

Comma-delimited list of one or more fields to sort by. Each field can have '-' as prefix to sort in descending order and no prefix to sort in ascending order.

Example: -nameFullLocal,nameFullLatinPattern: ^(\-?nameFullLocal|\-?nameFullLatin|,)*$
statusstring · enumOptional

Status

  • ACTIVE Active
  • DECEASED Deceased
  • INACTIVE Inactive
  • PENDING Pending
  • UNREGISTERED UnRegistered
Example: ACTIVEPossible values:
updatedstring · date-timeOptional

Record was modified after this date/time. In UTC.

Example: 2018-08-16T02:11:48
Responses
200

Successful operation

application/json
get
/badminton/o/{organizationId}/persons
GET /v1/badminton/o/{organizationId}/persons 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": [
    {
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "status": "ACTIVE",
      "gender": "MALE",
      "nameFullLocal": "John Smith",
      "nameAbbreviated": "Pat",
      "languageLocal": "en",
      "nameGivenLocal": "John",
      "nameFamilyLocal": "Smith",
      "nameFullLatin": "John Smith",
      "nameGivenLatin": "John",
      "nameFamilyLatin": "Smith",
      "dob": "1978-08-24",
      "nationality": "AUS",
      "deceased": "2016-09-08",
      "additionalNames": {
        "ANY_ADDITIONAL_PROPERTY": "default"
      },
      "additionalDetails": {
        "height": 1,
        "heightImperial": "text",
        "weight": 1,
        "weightImperial": 1,
        "dominantHand": "LEFT",
        "dominantFoot": "LEFT",
        "homeTown": "text",
        "school": "text",
        "schoolClass": "text",
        "college": "text",
        "collegeClass": "text",
        "representation": "text",
        "juniorAssociationLeague": "text"
      },
      "social": {
        "website": "http://www.example.com",
        "facebook": "https://www.facebook.com/example",
        "twitter": "https://www.twitter.com/example",
        "wikipedia": "https://en.wikipedia.org/wiki/example",
        "instagram": "https://www.instagram.com/example"
      },
      "historicalNames": [
        {
          "dateStart": "2025-11-19",
          "dateEnd": "2025-11-19",
          "nameFullLocal": "text",
          "nameGivenLocal": "text",
          "nameFamilyLocal": "text",
          "nameFullLatin": "text",
          "nameGivenLatin": "text",
          "nameFamilyLatin": "text"
        }
      ],
      "representing": "AUSTRALIA",
      "externalId": "A123",
      "updated": "2025-11-19T05:48:26.384Z",
      "added": "2025-11-19T05:48:26.384Z",
      "images": [
        {
          "imageId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "organizationId": "9",
          "organization": {
            "resourceType": "organizations",
            "id": "9"
          },
          "baseType": "entity",
          "baseId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "fileType": "png",
          "imageType": "LOGO",
          "secondaryType": "entity",
          "secondaryId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "rating": "LOW",
          "url": "text",
          "maximumHeight": 200,
          "maximumWidth": 200,
          "updated": "2025-11-19T05:48:26.384Z",
          "added": "2025-11-19T05:48:26.384Z"
        }
      ]
    }
  ]
}

Create a person

post
/badminton/o/{organizationId}/persons

Insert a new person

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
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
Body
personIdstring · uuidOptional

The unique identifier of the person

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
statusstring · enum · max: 30Required

Status

  • ACTIVE Active
  • DECEASED Deceased
  • INACTIVE Inactive
  • PENDING Pending
  • UNREGISTERED UnRegistered
Default: ACTIVEExample: ACTIVEPossible values:
genderstring · enumRequired

The gender of the person

  • FEMALE Female
  • MALE Male
  • UNKNOWN Unknown
Example: MALEPossible values:
nameFullLocalstring · max: 200Required

The full name of the person in local language

Example: John Smith
nameAbbreviatedstring | nullableOptional

An abbreviated name for a person

Example: Pat
languageLocalstring | nullableOptional

The language code of the full name in local language. This code is a two letter (lower-case) ISO 639-1 language code.

Example: en
nameGivenLocalstring | nullableOptional

Given name of the person in local language

Example: John
nameFamilyLocalstring | nullableOptional

Family name of the person in local language

Example: Smith
nameFullLatinstring | nullableOptional

The full name of the person in latin characters

Example: John Smith
nameGivenLatinstring | nullableOptional

Given name of the person in latin characters

Example: John
nameFamilyLatinstring | nullableOptional

Family name of the person in latin characters

Example: Smith
dobstring · date | nullableOptional

Date of Birth

Example: 1978-08-24
nationalitystring | nullableOptional

A 3 letter nationality code. We recommend you use ISO-3166 where available.

Example: AUS
deceasedstring · date | nullableOptional

Date deceased

Example: 2016-09-08
representingstring | nullableOptional

Who the person or team was representing

Example: AUSTRALIA
externalIdstring | nullableOptional

The Id of the data as set by the provider of the data

Example: A123Pattern: ^[0-9A-Za-z/_-]+$
Responses
200

Successful operation

application/json
post
/badminton/o/{organizationId}/persons
POST /v1/badminton/o/{organizationId}/persons HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1186

{
  "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "status": "ACTIVE",
  "gender": "MALE",
  "nameFullLocal": "John Smith",
  "nameAbbreviated": "Pat",
  "languageLocal": "en",
  "nameGivenLocal": "John",
  "nameFamilyLocal": "Smith",
  "nameFullLatin": "John Smith",
  "nameGivenLatin": "John",
  "nameFamilyLatin": "Smith",
  "dob": "1978-08-24",
  "nationality": "AUS",
  "deceased": "2016-09-08",
  "additionalNames": {
    "ANY_ADDITIONAL_PROPERTY": "default"
  },
  "additionalDetails": {
    "height": 1,
    "heightImperial": "text",
    "weight": 1,
    "weightImperial": 1,
    "dominantHand": "LEFT",
    "dominantFoot": "LEFT",
    "homeTown": "text",
    "school": "text",
    "schoolClass": "text",
    "college": "text",
    "collegeClass": "text",
    "representation": "text",
    "juniorAssociationLeague": "text"
  },
  "social": {
    "website": "http://www.example.com",
    "facebook": "https://www.facebook.com/example",
    "twitter": "https://www.twitter.com/example",
    "wikipedia": "https://en.wikipedia.org/wiki/example",
    "instagram": "https://www.instagram.com/example"
  },
  "historicalNames": [
    {
      "dateStart": "2025-11-19",
      "dateEnd": "2025-11-19",
      "nameFullLocal": "text",
      "nameGivenLocal": "text",
      "nameFamilyLocal": "text",
      "nameFullLatin": "text",
      "nameGivenLatin": "text",
      "nameFamilyLatin": "text"
    }
  ],
  "representing": "AUSTRALIA",
  "externalId": "A123"
}
{
  "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": [
    {
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "status": "ACTIVE",
      "gender": "MALE",
      "nameFullLocal": "John Smith",
      "nameAbbreviated": "Pat",
      "languageLocal": "en",
      "nameGivenLocal": "John",
      "nameFamilyLocal": "Smith",
      "nameFullLatin": "John Smith",
      "nameGivenLatin": "John",
      "nameFamilyLatin": "Smith",
      "dob": "1978-08-24",
      "nationality": "AUS",
      "deceased": "2016-09-08",
      "additionalNames": {
        "ANY_ADDITIONAL_PROPERTY": "default"
      },
      "additionalDetails": {
        "height": 1,
        "heightImperial": "text",
        "weight": 1,
        "weightImperial": 1,
        "dominantHand": "LEFT",
        "dominantFoot": "LEFT",
        "homeTown": "text",
        "school": "text",
        "schoolClass": "text",
        "college": "text",
        "collegeClass": "text",
        "representation": "text",
        "juniorAssociationLeague": "text"
      },
      "social": {
        "website": "http://www.example.com",
        "facebook": "https://www.facebook.com/example",
        "twitter": "https://www.twitter.com/example",
        "wikipedia": "https://en.wikipedia.org/wiki/example",
        "instagram": "https://www.instagram.com/example"
      },
      "historicalNames": [
        {
          "dateStart": "2025-11-19",
          "dateEnd": "2025-11-19",
          "nameFullLocal": "text",
          "nameGivenLocal": "text",
          "nameFamilyLocal": "text",
          "nameFullLatin": "text",
          "nameGivenLatin": "text",
          "nameFamilyLatin": "text"
        }
      ],
      "representing": "AUSTRALIA",
      "externalId": "A123",
      "updated": "2025-11-19T05:48:26.384Z",
      "added": "2025-11-19T05:48:26.384Z",
      "images": [
        {
          "imageId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "organizationId": "9",
          "organization": {
            "resourceType": "organizations",
            "id": "9"
          },
          "baseType": "entity",
          "baseId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "fileType": "png",
          "imageType": "LOGO",
          "secondaryType": "entity",
          "secondaryId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "rating": "LOW",
          "url": "text",
          "maximumHeight": 200,
          "maximumWidth": 200,
          "updated": "2025-11-19T05:48:26.384Z",
          "added": "2025-11-19T05:48:26.384Z"
        }
      ]
    }
  ]
}

Get a person

get
/badminton/o/{organizationId}/persons/{personId}

Return detailed information about a specific person

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
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
personIdstring · uuidRequired

The unique identifier of the person

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
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
Responses
200

Successful operation

application/json
get
/badminton/o/{organizationId}/persons/{personId}
GET /v1/badminton/o/{organizationId}/persons/{personId} 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": [
    {
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "status": "ACTIVE",
      "gender": "MALE",
      "nameFullLocal": "John Smith",
      "nameAbbreviated": "Pat",
      "languageLocal": "en",
      "nameGivenLocal": "John",
      "nameFamilyLocal": "Smith",
      "nameFullLatin": "John Smith",
      "nameGivenLatin": "John",
      "nameFamilyLatin": "Smith",
      "dob": "1978-08-24",
      "nationality": "AUS",
      "deceased": "2016-09-08",
      "additionalNames": {
        "ANY_ADDITIONAL_PROPERTY": "default"
      },
      "additionalDetails": {
        "height": 1,
        "heightImperial": "text",
        "weight": 1,
        "weightImperial": 1,
        "dominantHand": "LEFT",
        "dominantFoot": "LEFT",
        "homeTown": "text",
        "school": "text",
        "schoolClass": "text",
        "college": "text",
        "collegeClass": "text",
        "representation": "text",
        "juniorAssociationLeague": "text"
      },
      "social": {
        "website": "http://www.example.com",
        "facebook": "https://www.facebook.com/example",
        "twitter": "https://www.twitter.com/example",
        "wikipedia": "https://en.wikipedia.org/wiki/example",
        "instagram": "https://www.instagram.com/example"
      },
      "historicalNames": [
        {
          "dateStart": "2025-11-19",
          "dateEnd": "2025-11-19",
          "nameFullLocal": "text",
          "nameGivenLocal": "text",
          "nameFamilyLocal": "text",
          "nameFullLatin": "text",
          "nameGivenLatin": "text",
          "nameFamilyLatin": "text"
        }
      ],
      "representing": "AUSTRALIA",
      "externalId": "A123",
      "updated": "2025-11-19T05:48:26.384Z",
      "added": "2025-11-19T05:48:26.384Z",
      "images": [
        {
          "imageId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "organizationId": "9",
          "organization": {
            "resourceType": "organizations",
            "id": "9"
          },
          "baseType": "entity",
          "baseId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "fileType": "png",
          "imageType": "LOGO",
          "secondaryType": "entity",
          "secondaryId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "rating": "LOW",
          "url": "text",
          "maximumHeight": 200,
          "maximumWidth": 200,
          "updated": "2025-11-19T05:48:26.384Z",
          "added": "2025-11-19T05:48:26.384Z"
        }
      ]
    }
  ]
}

Update a person

put
/badminton/o/{organizationId}/persons/{personId}

Change the information of a specific person

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
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
personIdstring · uuidRequired

The unique identifier of the person

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
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
Body
statusstring · enum · max: 30Optional

Status

  • ACTIVE Active
  • DECEASED Deceased
  • INACTIVE Inactive
  • PENDING Pending
  • UNREGISTERED UnRegistered
Default: ACTIVEExample: ACTIVEPossible values:
genderstring · enumOptional

The gender of the person

  • FEMALE Female
  • MALE Male
  • UNKNOWN Unknown
Example: MALEPossible values:
nameFullLocalstring · max: 200Optional

The full name of the person in local language

Example: John Smith
nameAbbreviatedstring | nullableOptional

An abbreviated name for a person

Example: Pat
languageLocalstring | nullableOptional

The language code of the full name in local language. This code is a two letter (lower-case) ISO 639-1 language code.

Example: en
nameGivenLocalstring | nullableOptional

Given name of the person in local language

Example: John
nameFamilyLocalstring | nullableOptional

Family name of the person in local language

Example: Smith
nameFullLatinstring | nullableOptional

The full name of the person in latin characters

Example: John Smith
nameGivenLatinstring | nullableOptional

Given name of the person in latin characters

Example: John
nameFamilyLatinstring | nullableOptional

Family name of the person in latin characters

Example: Smith
dobstring · date | nullableOptional

Date of Birth

Example: 1978-08-24
nationalitystring | nullableOptional

A 3 letter nationality code. We recommend you use ISO-3166 where available.

Example: AUS
deceasedstring · date | nullableOptional

Date deceased

Example: 2016-09-08
representingstring | nullableOptional

Who the person or team was representing

Example: AUSTRALIA
externalIdstring | nullableOptional

The Id of the data as set by the provider of the data

Example: A123Pattern: ^[0-9A-Za-z/_-]+$
Responses
200

Successful operation

application/json
put
/badminton/o/{organizationId}/persons/{personId}
PUT /v1/badminton/o/{organizationId}/persons/{personId} HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1136

{
  "status": "ACTIVE",
  "gender": "MALE",
  "nameFullLocal": "John Smith",
  "nameAbbreviated": "Pat",
  "languageLocal": "en",
  "nameGivenLocal": "John",
  "nameFamilyLocal": "Smith",
  "nameFullLatin": "John Smith",
  "nameGivenLatin": "John",
  "nameFamilyLatin": "Smith",
  "dob": "1978-08-24",
  "nationality": "AUS",
  "deceased": "2016-09-08",
  "additionalNames": {
    "ANY_ADDITIONAL_PROPERTY": "default"
  },
  "additionalDetails": {
    "height": 1,
    "heightImperial": "text",
    "weight": 1,
    "weightImperial": 1,
    "dominantHand": "LEFT",
    "dominantFoot": "LEFT",
    "homeTown": "text",
    "school": "text",
    "schoolClass": "text",
    "college": "text",
    "collegeClass": "text",
    "representation": "text",
    "juniorAssociationLeague": "text"
  },
  "social": {
    "website": "http://www.example.com",
    "facebook": "https://www.facebook.com/example",
    "twitter": "https://www.twitter.com/example",
    "wikipedia": "https://en.wikipedia.org/wiki/example",
    "instagram": "https://www.instagram.com/example"
  },
  "historicalNames": [
    {
      "dateStart": "2025-11-19",
      "dateEnd": "2025-11-19",
      "nameFullLocal": "text",
      "nameGivenLocal": "text",
      "nameFamilyLocal": "text",
      "nameFullLatin": "text",
      "nameGivenLatin": "text",
      "nameFamilyLatin": "text"
    }
  ],
  "representing": "AUSTRALIA",
  "externalId": "A123"
}
{
  "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": [
    {
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "status": "ACTIVE",
      "gender": "MALE",
      "nameFullLocal": "John Smith",
      "nameAbbreviated": "Pat",
      "languageLocal": "en",
      "nameGivenLocal": "John",
      "nameFamilyLocal": "Smith",
      "nameFullLatin": "John Smith",
      "nameGivenLatin": "John",
      "nameFamilyLatin": "Smith",
      "dob": "1978-08-24",
      "nationality": "AUS",
      "deceased": "2016-09-08",
      "additionalNames": {
        "ANY_ADDITIONAL_PROPERTY": "default"
      },
      "additionalDetails": {
        "height": 1,
        "heightImperial": "text",
        "weight": 1,
        "weightImperial": 1,
        "dominantHand": "LEFT",
        "dominantFoot": "LEFT",
        "homeTown": "text",
        "school": "text",
        "schoolClass": "text",
        "college": "text",
        "collegeClass": "text",
        "representation": "text",
        "juniorAssociationLeague": "text"
      },
      "social": {
        "website": "http://www.example.com",
        "facebook": "https://www.facebook.com/example",
        "twitter": "https://www.twitter.com/example",
        "wikipedia": "https://en.wikipedia.org/wiki/example",
        "instagram": "https://www.instagram.com/example"
      },
      "historicalNames": [
        {
          "dateStart": "2025-11-19",
          "dateEnd": "2025-11-19",
          "nameFullLocal": "text",
          "nameGivenLocal": "text",
          "nameFamilyLocal": "text",
          "nameFullLatin": "text",
          "nameGivenLatin": "text",
          "nameFamilyLatin": "text"
        }
      ],
      "representing": "AUSTRALIA",
      "externalId": "A123",
      "updated": "2025-11-19T05:48:26.384Z",
      "added": "2025-11-19T05:48:26.384Z",
      "images": [
        {
          "imageId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "organizationId": "9",
          "organization": {
            "resourceType": "organizations",
            "id": "9"
          },
          "baseType": "entity",
          "baseId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "fileType": "png",
          "imageType": "LOGO",
          "secondaryType": "entity",
          "secondaryId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "rating": "LOW",
          "url": "text",
          "maximumHeight": 200,
          "maximumWidth": 200,
          "updated": "2025-11-19T05:48:26.384Z",
          "added": "2025-11-19T05:48:26.384Z"
        }
      ]
    }
  ]
}

Delete a person

delete
/badminton/o/{organizationId}/persons/{personId}

Delete a specific person

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
organizationIdstring · min: 5 · max: 5Required

The unique identifier of the organization

Example: b1a23
personIdstring · uuidRequired

The unique identifier of the person

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
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
/badminton/o/{organizationId}/persons/{personId}
DELETE /v1/badminton/o/{organizationId}/persons/{personId} 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": [
    {
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "status": "ACTIVE",
      "gender": "MALE",
      "nameFullLocal": "John Smith",
      "nameAbbreviated": "Pat",
      "languageLocal": "en",
      "nameGivenLocal": "John",
      "nameFamilyLocal": "Smith",
      "nameFullLatin": "John Smith",
      "nameGivenLatin": "John",
      "nameFamilyLatin": "Smith",
      "dob": "1978-08-24",
      "nationality": "AUS",
      "deceased": "2016-09-08",
      "additionalNames": {
        "ANY_ADDITIONAL_PROPERTY": "default"
      },
      "additionalDetails": {
        "height": 1,
        "heightImperial": "text",
        "weight": 1,
        "weightImperial": 1,
        "dominantHand": "LEFT",
        "dominantFoot": "LEFT",
        "homeTown": "text",
        "school": "text",
        "schoolClass": "text",
        "college": "text",
        "collegeClass": "text",
        "representation": "text",
        "juniorAssociationLeague": "text"
      },
      "social": {
        "website": "http://www.example.com",
        "facebook": "https://www.facebook.com/example",
        "twitter": "https://www.twitter.com/example",
        "wikipedia": "https://en.wikipedia.org/wiki/example",
        "instagram": "https://www.instagram.com/example"
      },
      "historicalNames": [
        {
          "dateStart": "2025-11-19",
          "dateEnd": "2025-11-19",
          "nameFullLocal": "text",
          "nameGivenLocal": "text",
          "nameFamilyLocal": "text",
          "nameFullLatin": "text",
          "nameGivenLatin": "text",
          "nameFamilyLatin": "text"
        }
      ],
      "representing": "AUSTRALIA",
      "externalId": "A123",
      "updated": "2025-11-19T05:48:26.384Z",
      "added": "2025-11-19T05:48:26.384Z",
      "images": [
        {
          "imageId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "organizationId": "9",
          "organization": {
            "resourceType": "organizations",
            "id": "9"
          },
          "baseType": "entity",
          "baseId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "fileType": "png",
          "imageType": "LOGO",
          "secondaryType": "entity",
          "secondaryId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "rating": "LOW",
          "url": "text",
          "maximumHeight": 200,
          "maximumWidth": 200,
          "updated": "2025-11-19T05:48:26.384Z",
          "added": "2025-11-19T05:48:26.384Z"
        }
      ]
    }
  ]
}

Create/Update a person

post
/badminton/o/{organizationId}/persons/force

Depending on data, Add a new person or update an existing one

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
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
Body
personIdstring · uuidOptional

The unique identifier of the person

Example: 009e9276-5c80-11e8-9c2d-fa7ae01bbebc
statusstring · enum · max: 30Required

Status

  • ACTIVE Active
  • DECEASED Deceased
  • INACTIVE Inactive
  • PENDING Pending
  • UNREGISTERED UnRegistered
Default: ACTIVEExample: ACTIVEPossible values:
genderstring · enumRequired

The gender of the person

  • FEMALE Female
  • MALE Male
  • UNKNOWN Unknown
Example: MALEPossible values:
nameFullLocalstring · max: 200Required

The full name of the person in local language

Example: John Smith
nameAbbreviatedstring | nullableOptional

An abbreviated name for a person

Example: Pat
languageLocalstring | nullableOptional

The language code of the full name in local language. This code is a two letter (lower-case) ISO 639-1 language code.

Example: en
nameGivenLocalstring | nullableOptional

Given name of the person in local language

Example: John
nameFamilyLocalstring | nullableOptional

Family name of the person in local language

Example: Smith
nameFullLatinstring | nullableOptional

The full name of the person in latin characters

Example: John Smith
nameGivenLatinstring | nullableOptional

Given name of the person in latin characters

Example: John
nameFamilyLatinstring | nullableOptional

Family name of the person in latin characters

Example: Smith
dobstring · date | nullableOptional

Date of Birth

Example: 1978-08-24
nationalitystring | nullableOptional

A 3 letter nationality code. We recommend you use ISO-3166 where available.

Example: AUS
deceasedstring · date | nullableOptional

Date deceased

Example: 2016-09-08
representingstring | nullableOptional

Who the person or team was representing

Example: AUSTRALIA
externalIdstring | nullableOptional

The Id of the data as set by the provider of the data

Example: A123Pattern: ^[0-9A-Za-z/_-]+$
Responses
200

Successful operation

application/json
post
/badminton/o/{organizationId}/persons/force
POST /v1/badminton/o/{organizationId}/persons/force HTTP/1.1
Host: api.dc.connect.sportradar.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1186

{
  "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
  "status": "ACTIVE",
  "gender": "MALE",
  "nameFullLocal": "John Smith",
  "nameAbbreviated": "Pat",
  "languageLocal": "en",
  "nameGivenLocal": "John",
  "nameFamilyLocal": "Smith",
  "nameFullLatin": "John Smith",
  "nameGivenLatin": "John",
  "nameFamilyLatin": "Smith",
  "dob": "1978-08-24",
  "nationality": "AUS",
  "deceased": "2016-09-08",
  "additionalNames": {
    "ANY_ADDITIONAL_PROPERTY": "default"
  },
  "additionalDetails": {
    "height": 1,
    "heightImperial": "text",
    "weight": 1,
    "weightImperial": 1,
    "dominantHand": "LEFT",
    "dominantFoot": "LEFT",
    "homeTown": "text",
    "school": "text",
    "schoolClass": "text",
    "college": "text",
    "collegeClass": "text",
    "representation": "text",
    "juniorAssociationLeague": "text"
  },
  "social": {
    "website": "http://www.example.com",
    "facebook": "https://www.facebook.com/example",
    "twitter": "https://www.twitter.com/example",
    "wikipedia": "https://en.wikipedia.org/wiki/example",
    "instagram": "https://www.instagram.com/example"
  },
  "historicalNames": [
    {
      "dateStart": "2025-11-19",
      "dateEnd": "2025-11-19",
      "nameFullLocal": "text",
      "nameGivenLocal": "text",
      "nameFamilyLocal": "text",
      "nameFullLatin": "text",
      "nameGivenLatin": "text",
      "nameFamilyLatin": "text"
    }
  ],
  "representing": "AUSTRALIA",
  "externalId": "A123"
}
{
  "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": [
    {
      "personId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
      "organizationId": "9",
      "organization": {
        "resourceType": "organizations",
        "id": "9"
      },
      "status": "ACTIVE",
      "gender": "MALE",
      "nameFullLocal": "John Smith",
      "nameAbbreviated": "Pat",
      "languageLocal": "en",
      "nameGivenLocal": "John",
      "nameFamilyLocal": "Smith",
      "nameFullLatin": "John Smith",
      "nameGivenLatin": "John",
      "nameFamilyLatin": "Smith",
      "dob": "1978-08-24",
      "nationality": "AUS",
      "deceased": "2016-09-08",
      "additionalNames": {
        "ANY_ADDITIONAL_PROPERTY": "default"
      },
      "additionalDetails": {
        "height": 1,
        "heightImperial": "text",
        "weight": 1,
        "weightImperial": 1,
        "dominantHand": "LEFT",
        "dominantFoot": "LEFT",
        "homeTown": "text",
        "school": "text",
        "schoolClass": "text",
        "college": "text",
        "collegeClass": "text",
        "representation": "text",
        "juniorAssociationLeague": "text"
      },
      "social": {
        "website": "http://www.example.com",
        "facebook": "https://www.facebook.com/example",
        "twitter": "https://www.twitter.com/example",
        "wikipedia": "https://en.wikipedia.org/wiki/example",
        "instagram": "https://www.instagram.com/example"
      },
      "historicalNames": [
        {
          "dateStart": "2025-11-19",
          "dateEnd": "2025-11-19",
          "nameFullLocal": "text",
          "nameGivenLocal": "text",
          "nameFamilyLocal": "text",
          "nameFullLatin": "text",
          "nameGivenLatin": "text",
          "nameFamilyLatin": "text"
        }
      ],
      "representing": "AUSTRALIA",
      "externalId": "A123",
      "updated": "2025-11-19T05:48:26.384Z",
      "added": "2025-11-19T05:48:26.384Z",
      "images": [
        {
          "imageId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "organizationId": "9",
          "organization": {
            "resourceType": "organizations",
            "id": "9"
          },
          "baseType": "entity",
          "baseId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "fileType": "png",
          "imageType": "LOGO",
          "secondaryType": "entity",
          "secondaryId": "009e9276-5c80-11e8-9c2d-fa7ae01bbebc",
          "rating": "LOW",
          "url": "text",
          "maximumHeight": 200,
          "maximumWidth": 200,
          "updated": "2025-11-19T05:48:26.384Z",
          "added": "2025-11-19T05:48:26.384Z"
        }
      ]
    }
  ]
}
PreviousAuthorizationNextCompetitions

Last updated

Was this helpful?