Contribute A Matchup

Overview

The following section describes how to contribute matchups to USTA. A matchup is defined as a single outcome from a Singles or Doubles match.

You must be permissioned to contribute data to USTA. Contact your USTA representative to apply for credentials.

Restrictions

The following define data that will be accepted by USTA for play activity. Any conditions not met will result in rejection of the matchup.

All player participants of the match have accepted USTA terms and conditions
The match score is formatted to comply with one of the predined match formats (see Match Formats below)

Each player participant must be uniquely identified using EITHER/OR:

USTA uaid

OR Combination Of:

firstName (>1 letter)l
lastName (>1 letter)
gender (M/F)
dob (YYYY-MM-DD)
email

Score Formats

The following section describes the mandatory score formats accepted by USTA. Each matchup must adhere one of the score formats.

Format Type	Examples

Format Type

Examples

TODS

(used in score fiield only)

“6-3 3-6 7-6(7-3)”

matchScore #1: score: 6,3 tiebreaker 0,0

matchScore #2: score: 3,6 tiebreaker 0,0

matchScore #3: score: 7,6 tiebreaker 7,3

“5-3 4-5 [10-8]”

matchScore #1: score: 5,3 tiebreaker 0,0

matchScore #2: score: 4,5 tiebreaker 0,0

matchScore #3: score: 0,0 tiebreaker 10,8

“7-6(7-5) 6-4 4-6 4-6 13-12(7-5)”

matchScore #1: score: 7,6 tiebreaker 7,5

matchScore #2: score: 6,4 tiebreaker 0,0

matchScore #3: score: 4,6 tiebreaker 0,0

matchScore #4: score: 4,6 tiebreaker 0,0

matchScore #5: score: 13,12 tiebreaker 7,5

“[10-4] [5-10] [10-6]”

matchScore #1: score: 0,0 tiebreaker 10,4

matchScore #2: score: 0,0 tiebreaker 5,10

matchScore #3: score: 0,0 tiebreaker 10,6

USTA

(used in ustaScore field only)

[[ 6,7,5,7 ], [ 6,4,0,0 ], [ 0,1,7,5 ]]

matchScore #1: score: 6,7 tiebreaker 5,7

matchScore #2: score: 6,4 tiebreaker 0,0

matchScore #3: score: 0,1 tiebreaker 7,5

[[ 6,4,0,0 ]]

matchScore #1: score: 6,4 no tiebreaker

[[ 0,1,0,0 ]]

matchScore #1: score: 0,1 no tiebreaker

API

The following section describe how to structure the call to contribute matchups to USTA. Up to 20 matchups can be submitted in a single call. If no uaid is provided for a player, then the identifying fields must be supplied. If they match to an existing player, the matchup will be applied to the existing uaid. If no uaid is supplied, it is the responsibility of the contributor to collect from the player acceptance of the USTA terms and conditions and supply the acceptance flag along with the identifying fields.

All players must consent to USTA terms and conditions. If uaid is supplied with the matchup, it is implied that USTA has collected consent. If identifying fields are supplied instead of uaid, the contributor must collect consent from the player and supply the consent in the isAcceptedUSTATerms field of each player.

URI

Production:
  POST https://api-ustaconnect.usta.com/v1/usta-service/dataexchange/matchups
  
Stage:
  POST https://stage-api-ustaconnect.usta.com/v1/usta-service/dataexchange/matchups

Body

The body of the call contains an array of Matchups. For performance on the wire, use only 1 array element.

{
  "matchups": [
    {
      "category": "string",
      "subcategory": "string",
      "startDate": "string",
      "endDate": "string",
      "eventId": "string",
      "eventName": "string",
      "eventType": "JUNIOR_CIRCUIT",
      "externalId": "string",
      "facility": {
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "name": "string",
        "state": "string",
        "zipcode": "string"
      },
      "matchDate": "string",
      "matchId": 0,
      "matchStatus": "ABN",
      "matchType": "DOUBLES",
      "matchUrl": "string",
      "playLevel": "string",
      "positionId": "string",
      "score": "string",
      "scoreFormat": "TODS",
      "side_1_player_1": {
        "uaid": "string",
        "dob": "03-01-2000T00:00:00",
        "email": "side_1_player_1@mymail.com",
        "externalId": "side_1_player_1",
        "firstName": "Kurisu",
        "lastName": "Makise",
        "gender": "F",
        "isAcceptedUSTATerms": "Y",
        "isoNationalityCode": "JPY",
        "zipcode": "98765"
      },
      "side_1_player_2": {
        "uaid": "string",
        "dob": "03-01-2000T00:00:00",
        "email": "side_1_player_2@mymail.com",
        "externalId": "side_1_player_2",
        "firstName": "Kurisu",
        "lastName": "Makise",
        "gender": "F",
        "isAcceptedUSTATerms": "Y",
        "isoNationalityCode": "JPY",
        "zipcode": "98768"
      },
      "side_2_player_1": {
        "uaid": "string",
        "dob": "03-01-2000T00:00:00",
        "email": "side_2_player_1@mymail.com",
        "externalId": "side_2_player_1",
        "firstName": "Kurisu",
        "lastName": "Makise",
        "gender": "F",
        "isAcceptedUSTATerms": "Y",
        "isoNationalityCode": "JPY",
        "zipcode": "98768"
      },
      "side_2_player_2": {
        "uaid": "string",
        "dob": "03-01-2000T00:00:00",
        "email": "side_2_player_2@mymail.com",
        "externalId": "side_2_player_2",
        "firstName": "Kurisu",
        "lastName": "Makise",
        "gender": "F",
        "isAcceptedUSTATerms": "Y",
        "isoNationalityCode": "JPY",
        "zipcode": "98768"
      },
      "team_1": {
        "captain": "string",
        "coCaptain": "string",
        "coach": "string",
        "home": true,
        "name": "string"
      },
      "team_2": {
        "captain": "string",
        "coCaptain": "string",
        "coach": "string",
        "home": true,
        "name": "string"
      },
      "url": "string",
      "ustaScore": [
        [
          0
        ]
      ],
      "winningSide": "SIDE_1"
    }
  ],
  "sourceName": "BIG_LEAGUE_SPORTS"
}

Fields

The following section describes the usage of the fields.

The most important consideration is the score format you wish to use. Two formats are supported. Each matchup must use one or the other but not both. See Match Formats Section above.

The matchid defines a unique match up. This is what is used for de-duping.

Field	Required/Optional	Values

Field	Required/Optional	Values
eventId	Optional	Unique identifier for the league or tournament
eventName	Required	Name of league or tournament
category	Optional	Text description of event ie “Anytown Winter League”
subCategory	Optional	Text description of group within event ie “Women’s 50 And Over”
startDate	Required	YYYY-MM-DD (*ITF does not allow dates in the future)
endDate	Required	YYYY-MM-DD (*ITF does not allow dates in the future)
eventType	Required	LEAGUE JUNIOR_TEAM_TENNIS
facility.name	Required
facility.addressLine1	Optional
facility.addressLine2	Optional
facility.city	Optional
facility.state	Optional
facility.zipcode	Optional
matchDate	Required	YYYY-MM-DD
matchId	Required	Must be unique for each matchup/contributor. This ID will be used to resubmit scores to USTA along with the sourceName. Ex. 2022-08-10-1
matchStatus	Required	The match status code should be used on a submission ABN - Abandoned BYE - Bye CO - Completed DEF - Defaulted DDEF - Double Default DR - Dead Rubber IP - In progress RET - Retired SUS - Suspended WO - Walkover
matchType	Required	SINGLES DOUBLES
matchUrl	Optional	Link to website for match scorecard or similar.
playLevel	Optional	NTRP, WTN, UTR
positionId	Optional	Text description ie “1st Singles”
ustaScore	Required/Optional (Either ustaScore or score must be present)	USTA match format score (See Match Format section)
score	Required.Optional (Either ustaScore or score must be present)	TODS match format score (See Match Format section)
scoreFormat	Required	TODS USTA
side_1_player_1.uaid side_1_player_2.uaid side_2_player_1.uaid side_2_player_2.uaid	Required	The UAID of the player. This is the USTA number. 2 UAIDs are expected for singles matches and 4 UAIDs for doubles matches.
team_1.name team_2.name	Optional
team_1.captain team_2.captain	Optional
team_1.co_captain team_2.co_captain	Optional
team_1.home team_2.home	Optional	Required if there are teams being submitted. This identifies whether the team is the home or away team.
url	Optional	Link to league or tournament website
winningSide	Required	0 (Ties) 1 2

Error Codes

The following are a list of error codes and descriptions that are returned to the Contributor:

HTTP Error Code	Application Error Code	Description

HTTP Error Code	Application Error Code	Description
400		The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
401		Indicates that the request requires user authentication information. The client MAY repeat the request with a suitable Authorization header field.
403		Unauthorized request. The client does not have access rights to the content. Unlike 401, the client’s identity is known to the server.
404		The server can not find the requested resource.
429		Rate limiting. The user has sent too many requests in a given amount of time.

Sample Curl

The following is a sample curl illustrating the contribution of a doubles matchup.

Where:

--header 'Authorization: Bearer eyJraW...

specifies the token that you retrieved using the https://stage-account.usta.com/oauth2/token endpoint.

curl --location --request POST 'https://stage-services.usta.com/v1/dataexchange/matchups' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraW...
--data-raw '{
  "sourceName": "TENNISLINK",
  "matchup":{
      "matchId": "1009063181",
      "matchDate": "2022-05-26",
      "matchStatus": "RET",
      "matchType": "DOUBLES",
      "playLevel": "7",
      "category": "Mixed 40&Over",
      "subcategory": "7.0 Laf (40&O) Mixed",
      "eventType": "LEAGUE",
      "url": "someUrl",
      "matchUrl": "testingUrl",
      "externalId": "86808",
      "eventName": "2022 LAF Mixed 40 & Over 7.0 Laf (40&O) Mixed",
      "startDate": "2022-05-07",
       "endDate": "2022-08-05",
      "side_1_player_1": {
        "uaid": "922057368",
        "isoNationalityCode" : "USA",
        "gender" :"F",
        "dob": "1980-05-26",
        "isAcceptedUSTATerms": "Y"
      },
       "side_1_player_2": {
        "uaid": "2018456061",
        "gender" :"M",
        "dob": "1980-06-26",
        "isoNationalityCode" : "USA",
        "isAcceptedUSTATerms": "Y"
      },
      "side_2_player_1": {
        "uaid": "11197737",
        "gender" :"F",
        "dob": "1980-04-26",
        "isoNationalityCode" : "USA",
        "isAcceptedUSTATerms": "Y"
      },
       "side_2_player_2": {
        "uaid": "919306164",
        "gender" :"M",
        "dob": "1980-03-26",
        "isoNationalityCode" : "USA",
        "isAcceptedUSTATerms": "Y"
      },
      "winningSide": "1",
      "scoreFormat" : "TODS",
      "ustaScore": [
        [6,2,0,0],
        [6,2,0,0]
      ],
      "score": "6-3 6-3",
      "team_1": {
        "name": "Gary, YSC, LFT Mxd 7.0 40",
        "captain": "Diana Gary",
        "coCaptain": "",
        "home": false
      },
      "team_2": {
        "name": "Benoit, Reds, LFT 40",
        "captain": "Toni Benoit",
        "coCaptain": "",
        "home": true
      },
      "facility": {
        "name": "Youngsville Sports Complex",
        "addressLine1": "801 Savoy Rd",
        "addressLine2": "",
        "city": "Youngsville",
        "state": "LA",
        "zipcode": "70592"
      }
    }
}'

1 Overview
2 Restrictions
3 Score Formats
4 API
- 4.1 URI
- 4.2 Body
- 4.3 Fields
- 4.4 Error Codes
5 Sample Curl