Quick Reference: Retrieve SafePlay Info

Overview

This guide is a quick reference that lists the steps for looking up the status or details of an individual's SafePlay certification given an email address. Integrating your application with USTA.com is easy. You can use any programming language or tool that supports HTTPS communications.  

Before Development

Before you begin development of your browser-based application, contact USTA to discuss what data you will need to access from USTA.  Credentials will be issued for use to connect via HTTP.

Credentials:

1. client id
2. client secret

Scope:

1. Read/Write
2. Which data

Environments:

1. Stage (preproduction)
2. Prod

Building Your Application

The following is a quick guide for looking up SafePlay info.  These APIs operate in the 'Unbound' mode.  More on the unbound mode can be found on the API Reference page.  

It should be noted that the best use of this API is machine to machine.  If you are building this functionality into a browser-based application, please heed the warnings about exposure of the access token when saved in cookies.  Follow the steps below to retrieve the SafePlay info.

Step 1:  Retrieve a JWT Token

This API calls the USTA OAuth Service to retrieve a JWT token that will be used to define the scope of permissions for future calls.  Please note that if you are working within the context of a browser application, this token will be visible to users and could be used for subsequent calls.  

The scope restricts access as defined by USTA at the time of client_id setup.

Headers

This API call uses Basic Authorization.  Use the supplied client_id and secret to generate a Basic Authentication token.  There are many online generators you can use for testing.  One is here.

HTTP Call

This is the API call.  Please note the difference in base urls:

Test:  https://stage-services.usta.com

Prod: https://services.usta.com

Result

The important info returned from this call are the following:

jti:  token that will be passed in subsequent calls

exprires_in: the Time To Live of the token

{
    "access_token": "eyJh...,
    "token_type": "bearer",
    "expires_in": 43199,
    "scope": "safeplay:status safeplay:details",
    "client_name": "ClubBling",
    "jti": "7b5f8ede-bbc1-4b2b-b127-a6f0e9dfb8cd"
}

Example

This example uses CURL from the command line.

Step 2:  Retrieve Approval Status Using JWT Token

This API call is used to retrieve a 'thumbs up/thumbs down' assessment of whether the provider is SafePlay approved.  This result is calculated based on the following criteria:

• Legal Agreement Date
• NCSI Status
• SafeSport Completion
• SafeSport Expiration

Headers

Data/Payload

Email is used as the unique identifier for looking up SafePlay status.

Result

The result is calculated summary status of true/false.

{
    "isApproved": false
}

Example

This example uses CURL from the command line.

Step 2:  Retrieve Approval Details Using JWT Token (Optional)

Similar to the call above, you can optionally see the inputs that went into the calculation of the isApproved call.

Headers

Data/Payload

Result

The result shows the current values associated with the inputs:

• Legal Agreement Date
• NCSI Status
• SafeSport Completion
• SafeSport Expiration

{
    "legalAgreementAcceptDate": "2019-05-14",
    "legalAgreementExpireDate": "2021-05-14",
    "legalAgreementStatus": "Accepted",
    "ncsiCheckTimestamp": "2019-06-28T12:03:04",
    "ncsiExpiryDate": "2019-06-19",
    "ncsiCheckStatus": "Expired",
    "safeSportCompleteDateTime": "2018-10-25T10:56:07",
    "safeSportExpiryDate": "2020-10-25",
    "safeSportStatus": "COMPLETE",
    "safePlayStatus": "EXPIRED",
    "safePlayStatusDisplayValue": "Expired"
}

Example

This example uses CURL from the command line.