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

You must first retrieve an access token using machine-to-machine method. See USTA Connect - Authentication OKTA for more on how to request a token.

Base URLs

Replace {BASE_URL} with the following value:

PROD: https://api-ustaconnect.usta.com

STAGE: https://stage-api-ustaconnect.usta.com

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

POST {BASE_URL}/v1/usta-service/dataexchange/matchups

Request Body Schema

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	Type	Required/Optional	Values

Field	Type	Required/Optional	Values
eventId	String	Optional	Unique identifier for the league or tournament
eventName	String	Required	Name of league or tournament
category	String	Optional	Text description of event ie “Anytown Winter League”
subCategory	String	Optional	Text description of group within event ie “Women’s 50 And Over”
startDate	String	Required	YYYY-MM-DD (*ITF does not allow dates in the future)
endDate	String	Required	YYYY-MM-DD (*ITF does not allow dates in the future)
eventType	String	Required	LEAGUE JUNIOR_TEAM_TENNIS JUNIOR_CIRCUIT TOURNAMENT UNSANCTIONED_TOURNAMENTS WTN_PLAY USTA_FLEX DUAL_MATCH HIGH_SCHOOL_TOURNAMENT TENNIS_ON_CAMPUS TENNIS_ON_CAMPUS_DUAL_MATCH JUNIOR_FLEX_LEAGUE ADULT_FLEX_LEAGUE
facility.name	String	Required
facility.addressLine1	String	Optional
facility.addressLine2	String	Optional
facility.city	String	Optional
facility.state	String	Optional
facility.zipcode	String	Optional
matchDate	String	Required	YYYY-MM-DD
matchId	Integer	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	String	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	String	Required	SINGLES DOUBLES
matchUrl	String	Optional	Link to website for match scorecard or similar.
playLevel	String	Optional	NTRP, WTN, UTR
positionId	String	Optional	Text description ie “1st Singles”
ustaScore	Array<Integer>	Required/Optional (Either ustaScore or score must be present)	USTA match format score (See Match Format section)
score	String	Required.Optional (Either ustaScore or score must be present)	TODS match format score (See Match Format section)
scoreFormat	String	Required	TODS USTA
side_1_player_1.uaid side_1_player_2.uaid side_2_player_1.uaid side_2_player_2.uaid	String	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	String	Optional
team_1.captain team_2.captain	String	Optional
team_1.co_captain team_2.co_captain	String	Optional
team_1.home team_2.home	Boolean	Optional	Required if there are teams being submitted. This identifies whether the team is the home or away team.
url	String	Optional	Link to league or tournament website
winningSide	String	Required	0 (Ties) 1 2

Request example

{
  "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"
      }
    }
}

Responses

When a customer is contributed, the identifying fields will be compared to all existing USTA customers.

In the event that a match is found to an existing customer, the existing UAID will be returned.
In the event that no match is found and all required fields are present in the contribution, a new USTA customer will be created and the new UAID will be returned.

Status	Body	Meaning

Status	Body	Meaning
200 - Success	`{ "sourceName": "string", "matchup": { "matchUpName": "string", "ustaID": "string", "externalID": "string" }, "updatedAt": "2026-01-14T13:33:42.790Z" }`	Standard Response
400 - Bad request		The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
401 - UNAUTHORIZED		Indicates that the request requires user authentication information. The client MAY repeat the request with a suitable Authorization header field.
403 - FORBIDDEN		Unauthorized request. The client does not have access rights to the content. Unlike 401, the client’s identity is known to the server.
404 - NOT FOUND		The server can not find the requested resource.
429 - TOO MANY REQUESTS		Rate limiting. The user has sent too many requests in a given amount of time.