U.S.S.F. Learning Center certification version v1.0.1

Used to login to the Certification API.

Send your credentials to this endpoint before using the API.

The API is using JSON Web Tokens - https://jwt.io/ for authorization.

The response of this request includes two tokens:

• the Access Token is used for authorization of subsequent requests.
  • It must be included in the header of any request as Authorization: Bearer {access_token}
    • for example:

        Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1Ni
      

  • access tokens are valid for one hour and must be refreshed when they are expired
  • the token consists of three parts separated by dots - .
    • Header - base64 encoded
      • it contains the type of the token (JWT) and the signing algorithm
      • for example:

          {
            "alg": "HS256",
            "typ": "JWT"
          }
        

      • HS256 stands for HMAC SHA 256, a 256-bit encryption algorithm
      • typ is always JWT
    • Payload - base64 encoded
      • it contains data about the expiration date of the token, the issuer and the id of the user
      • for example:

          {
            "iss": "connect.learning.ussoccer.com",
            "exp": 1553867094,
            "id": 122
          }
        

        • iss:
          • the domain of the API - connect.learning.ussoccer.com
        • exp:
          • the date when the tokens will expire
          • format is the number of seconds since UNIX epoch
          • make sure to configure NTP or similar on your servers
        • id:
          • id of your account
    • Signature
      • We will use the signature to verify that the token is valid
• the Refresh Token is used to get a new access token.
  • it's valid for 24-hours
  • when the refresh token is expired, you need to login again
• Recommended API implementation
  • Step 1: Login to get a set of tokens. Use the access_token in the http header of all following requests for authorization

Used to get a new set of tokens.

It returns two new tokens.

When your refresh token is invalid, you will need to login again.

• Recommended API implementation
  • Step 2: Refresh your access token when it is expired or about to expire. Replace the old tokens with new returned set

• This endpoint is designed to provide you with the complete list of all certifications that may be reported via this API, and their attributes

• When you create your API credentials with us, you will provide a webhook URL that we will call any time there is any change to the complete list of tracked certifications.

• Recommended API implementation

  • Step 3: retrieve and store the complete list of certifications

• There are no additional request parameters

• The response will include all certifications which currently exist, with the following attributes:

  • License_id
    • The unique identifier of this license
    • This is the value that will be used in all other responses
  • Name
    • The official name of a certification
    • This is the value we recommend you display in any user interface
  • Discipline
    • The top-level categorization of this certification, such as “coach” or “referee”
  • Type
    • The second-level categorization of this certification
    • This value is designed to delineate certifications in a primary educational pathway from supplemental pathways or specializations
  • Rank
    • In some disciplines and types, some certifications may be redundant if multiple are simultaneously active
    • 1 is the “highest” rank
    • Example : a Regional referee license has a higher rank value than a Grassroots referee license, because if both are simultaneously active, the activities that the lower rank license qualifies the user for are a subset of those for the higher license.

• This endpoint is designed to help you find the 16-digit USSF-ID of a known person in your records. You will use this ID for all further interactions with the API. We will not return any personal information (name, DOB, etc.) via the API, so you must already have this information in your system for the people you wish to retrieve certifications for. If you already have a person’s 16-digit USSF ID, you do not need to use this endpoint.

• Recommended API implementation

  • Step 4: retrieve and store the USSF-ID for all of your users
  • Repeat for any new users

• Query parameters:

  • Email address - email (string)
  • First name - first_name (string)
  • Last name - last_name (string)
  • Date of birth - dob (string) - YYYY-MM-DD format

• You MUST include at least email address, OR all three of: first name, last name, and date of birth

• Optionally, you may include first name, last name, and/or date of birth along with an email address if you wish to increase the confidence of your match

• We will search our records for an EXACT MATCH of the data you provide. Partial matches will NOT be included in responses.

• Responses you may receive:

  • Match
    • This means we found exactly one record that exactly matches ALL of your query parameters
    • The response will include the person’s 16-digit USSF-ID, which you should store and use for any further requests regarding this person
  • Multiple_matches
    • This means we found more than one record that exactly matches your query parameters
    • NOTE: this response is not possible if you include an email address in your query parameters. The primary email address on every user record in the Learning Center is unique.
    • If you receive this response, we recommend asking the user to provide the exact email address that is used on their Learning Center profile, and query on that value only- exclude first name, last name, and date of birth.
  • No_match
    • This means we could not find any records that exactly match your query parameters
    • Possible explanations:
      • There is an error in your query parameters
      • The user does not exist in the Learning Center
      • The user provided different information on their Learning Center profile than they have in your records, for example:
        • Alternate email address
        • Nickname or abbreviated first name
        • Different last name due to marriage or other reason
        • Middle name was appended to first or last name fields
        • Special character in a name in one system but not the other (hyphen, accent, apostrophe, etc.)
    • If you receive this response, we recommend asking the user to provide the exact email address that is used on their Learning Center profile, and query on that value only- exclude first name, last name, and date of birth.

• This endpoint is designed to return verified certifications of a specified person. There are several optional query parameters you may include to filter the response to your needs.

• Recommended API implementation

  • Step 5: Perform an initial license request and store all currently active certifications for all of your users
  • Repeat for any new users
  • We recommend you store all certifications, regardless of discipline, type or rank

• URI Parameters

  • USSF-ID (string)
    • This 16-digit numeric identifier will correspond to exactly one user record in the Learning Center. If you do not know a person’s USSF-ID, you can use the GET/users endpoint to find it.

• Query Parameters

  • Highest_only (boolean)
    • If TRUE, this parameter will filter the response to only include the highest ranked certification(s) within any type
      • Example 1: if a coach holds B, C, D and E coaching licenses, the C, D and E licenses may be superfluous to your needs. If you set this parameter to TRUE, you would only see the B coaching license in the response.
      • Example 2: if a ref holds a Grassroots and Regional referee license, the Grassroots license may be superfluous to your needs. If you set this parameter to TRUE, you would only see the Regional referee license in the response.
    • If FALSE, or not specified, rank of certifications will not affect the response, even if multiple simultaneously active certifications may be redundant
  • Discipline (string)
    • You may only be interested in certifications from one discipline, such as coaching, or refereeing. Use this parameter to filter the response to only the discipline you are concerned with.
    • All accepted values for discipline can be retrieved via the GET/licenses endpoint
  • Type (string)
    • Within a discipline, there may be multiple types of certifications.
      • Example: there are referee licenses that are not part of the primary pathway, such as the Beach Soccer Referee license, which is part of the referee_specialist pathway, and is not redundant when considered along with a Grassroots or Regional referee license. Use this parameter if you wish to specify only certifications from a certain type.
    • All accepted values for type can be retrieved via the GET licenses endpoint
  • license_id (string)
    • If you are only interested in verifying whether or not a person holds a specific certification, you can use this parameter to specify the exact certification you are looking for.
    • If the person does not currently hold the specified certification, the response will be an empty array
    • All accepted values for id can be retrieved via the GET licenses endpoint
  • DOB (string) – YYYY-MM-DD format
    • As an additional optional point of verification, you can include the DOB that you have on file corresponding to this individual with this USSF-ID
    • The DOB you include must match the DOB we have on file for that USSF-ID in order to successful retrieve the list of licenses
  • Response
    • If the user holds no certifications that match the query parameters you specified, or no certifications of any kind, then the response will be an empty array
    • The response will ONLY include currently active certifications in the response, with the following values:
      • USSF-ID
        • The unique 16-digit identifier of the user you queried on
      • License_id
        • The license id uniquely identifies the specific certification.
        • All possible values for license_id can be retrieved via the GET licenses endpoint
      • Issuer
        • The issuer identifies the organization that hosted the course the person took to earn this certification
      • Issue_date
        • The date the certification was issued
      • Expiration_date
        • The date the certification will expire. For some certifications, this may be NULL
      • Updated_at
        • The last timestamp when any data related to this license changed
    • If the USSF-ID you specified is for a user whose USSF-ID has changed, the response will be HTTP status code 410, with the message “ussf_id has been changed”, and their new USSF-ID will be included. You should update your records, and then repeat the call with the correct USSF-ID.
    • If we find the matching USSF-ID, but the DOB you specified does not match the DOB in our records, then the response will be HTTP status code 400 with the message “dob does not match ussf_id”
    • If the USSF-ID you specified does not exist, the response will be HTTP status code 404, with the message “ussf_id does not exist”

• This endpoint allows you to request that we update you any time a person’s list of licenses changes.
• When you create your API credentials with us, you will provide a webhook URL that we will call any time there is any change to any license of a user record you are subscribed to.
• Recommended API implementation
  • Step 6: subscribe to all of your users
  • Repeat for any new users
• URI Parameters
  • USSF-ID (string)
    • This 16-digit numeric identifier will correspond to exactly one user record in the Learning Center. If you do not know a person’s USSF-ID, you can use the GET users endpoint to find it.
• Response
  • If the call is successful, the response will simply be a HTTP Status Code 200
  • If the USSF-ID you specified is for a user whose USSF-ID has changed, the response will be HTTP status code 410, with the message “ussf_id has been changed”, and their new USSF-ID will be included. You should update your records, and then repeat the call with the correct USSF-ID.
  • If the USSF-ID you specified does not exist, the response will be HTTP status code 404, with the message “ussf_id does not exist”

• This endpoint allows you to unsubscribe from a user record you have previously subscribed to
• URI Parameters
  • USSF-ID (string)
    • This 16-digit numeric identifier will correspond to exactly one user record in the Learning Center. If you do not know a person’s USSF-ID, you can use the GET users endpoint to find it.
• Response
  • If the call is successful, the response will simply be a HTTP Status Code 200

• This endpoint is designed to return the total number of years a specified person has held a referee license. The current year is not counted until it ends. The system counts any year where an individual has held at least one referee license, not counting any intervening years if no referee license was held that year. Holding multiple referee licenses in the same year still only counts towards 1 year in the experience value. This value does not account for number of games officiated or any more specific actions the individual may or may not have performed.

• Recommended API implementation

  • Optional: Perform an initial referee experience request for any referees in your system. Repeat for any new referees as they are added to your system.

• URI Parameters

  • USSF-ID (string)

    • This 16-digit numeric identifier will correspond to exactly one user record in the Learning Center. If you do not know a person’s USSF-ID, you can use the GET/users endpoint to find it.

  • Response

    • The response will include following values:
      • USSF-ID
        • The unique 16-digit identifier of the user you queried on
      • Referee-Experience
        • Total years of experience as a referee

• This endpoint is designed to return whether or not a user has ever completed U.S. Soccer’s Grassroots Referee e-learning module. PLEASE NOTE: a “true” value does NOT indicate that this individual holds a U.S. Soccer Referee license, and it does not guarantee they are eligible to officiate games. Completion of this module does not expire. This data point is only relevant for SRC’s who do not run their courses through the Learning Center. We recommend you do NOT implement this method unless you have explicitly discussed it with your client organization, and they have requested it.

• Recommended API implementation

  • If referees in your domain are completing the full licensing procedure through the Learning Center, then it is redundant to track this certificate independently.
  • Optional: Perform an initial grassroots-referee-certificate request for any referees in your system.
  • Repeat for any new referees as they are added to your system.

• URI Parameters

  • USSF-ID (string)

    • This 16-digit numeric identifier will correspond to exactly one user record in the Learning Center. If you do not know a person’s USSF-ID, you can use the GET/users endpoint to find it.

  • Response

    • The response will include following values:
      • Has-Certificate
        • Flag indicating if the user has a grassroots certificate
      • Issue-Date
        • Certificate issue date, YYYY-MM-DD

• This endpoint allows you to request a list of all user records you are currently subscribed to.
• We expect that partners will be subscribed to many users, and there may be occasions when this response can include a large amount of data, so responses will be paginated. If the number of results exceeds one page, multiple requests must be made.
• Recommended API implementation
  • Step 10: call this endpoint and double check that the list of subscribed user records you receive matches those that you previously subscribed to in step 6, less any users you have deleted subscriptions for.
• Query Parameters
  • Page (integer)
    • The page of results you want to be returned, when results exceed one page
    • When unset, page 1 will be returned
    • USSF-ID (string)
      • This 16-digit numeric identifier will correspond to exactly one user record in the Learning Center. If you do not know a person’s USSF-ID, you can use the GET users endpoint to find it.
• Response
• For all user records you are subscribed to, the response will include the following values:
  • USSF-ID
    • The unique 16-digit identifier of a user you are subscribed to
  • Created_at
    • The last timestamp when any data related to this license changed
  • Pagination
    • Current_page: no. of the page that is returned
    • Per_page: number of records on each page
    • Last_page: number of pages
    • Total: total number of user records you are subscribed to

• This endpoint is designed to return all user licenses, that were updated during a specified time range, for all users you are subscribed to.
• The response will include ALL licenses in the response that had any change, even if they are now inactive/expired.
• We expect that partners will be subscribed to many users, and there may be occasions when this response can include a large amount of data, so responses will be paginated. If the number of results exceeds one page, multiple requests must be made.
• Recommended API implementation
  • Step 7: schedule a recurring job to call this endpoint (for example daily or weekly)
  • This can be used as a redundant check to compare against the individual license updates received for all subscribed users during the same time range
• Query Parameters
  • Start_date (datetime)
    • The start of the time range you wish to query against for any license changes
  • End_date (datetime)
    • The end of the time range you wish to query against for any license changes
  • Page (integer)
    • The page of results you want to be returned, when results exceed one page
    • When unset, page 1 will be returned
• Response
  • For all users records you are subscribed to, for any license that changed during the specified time range, the response will include the following values:
    • USSF-ID
      • The unique 16-digit identifier of the user you queried on
    • Action
      • The type of change that occurred to this license
        • Added: the user earned a new license
        • Updated: one or more attributes of this license changed
        • Removed: this license expired or was otherwise removed/made inactive for this user
    • License_id
      • The license id uniquely identifies the specific certification.
      • All possible values for license_id can be retrieved via the GET licenses endpoint
    • Issuer
      • The issuer identifies the organization that hosted the course the person took to earn this certification
    • Issue_date
      • The date the certification was issued
    • Expiration_date
      • The date the certification will expire. For some certifications, this may be NULL
    • Updated_at
      • The last timestamp when any data related to this license changed
    • Pagination
      • Current_page: no. of the page that is returned
      • Per_page: number of records on each page
      • Last_page: number of pages
      • Total: total number of updated results within the time range you specified

• The /background-checks/ endpoints are designed to give U.S. Soccer member organizations a method of indicating participants for whom they wish to subsidize the cost of a federal background screening initiated in the Learning Center. Before an API key holder can utilize any of these endpoints, a U.S. Soccer member organization must contact U.S. Soccer and indicate that their technology provider has been authorized to request background check subsidies for their organization.
• This endpoint lists all U.S. Soccer member organizations you are allowed to create background check subsidies for.
• If the returned list is empty, you will not be able to utilize the other /background-checks/ endpoints.

• This endpoint returns a list of any background check subsidy entries you have previously created matching the parameters you submit.
• You may only request entries for a U.S. Soccer member organization that you have been authorized for.
• The parameter payer_organization is required. All others are optional.

• This endpoint allows you to create an entry that indicates that the specified individual should not be charged for the next background screening they initiate in the Learning Center. The payer_organization will be billed for the cost of the background screening. You may only create subsidy entries for organizations that ave previously authorized you to do so.
• You can create a subsidy entry for an existing Learning Center user by USSF_ID or email address.
• You can also create a subsidy entry for an individual that does not yet have a Learning Center account by email address. U.S. Soccer will not validate the identity of the individual that claims the subsidy.
• Subsidies are valid for one year and will expire if they are not used.
• Once a subsidy is used, you would need to post it again if the individual should receive a subsidy a second time. Clear background screenings are valid for two years, so at most, for a single individual, you would need to repeat the POST method once every two years.
• If a new subsidy for the same payer organization is created when one already exists and is unused, the dates will simply be updated.
• If multiple subsidies have been created for the same user, but different payer organizations, the oldest subsidy will be used first.

• This endpoint allows you to delete a previously created subsidy, only if it has not yet been used.
• You may only delete subsidies from a payer_organization that you have been authorized for.

• This endpoint is designed to provide you with any updated certification information on a user you are subscribed to.
• When you create your API credentials with us, you will provide a webhook URL that we will call any time there is any change to any certification of a user record you are subscribed to.
• For authorization all incoming webhook notifications will include an http header (Authorization) with a key that we will provide you with. This key is unique to each partner and should be used to secure the webhooks. Unverified requests should be blocked.
• Recommended API implementation
  • Step 8: configure your endpoint to receive these updates and validate the Authorization key for security.
• The request will include the following values:
  • USSF-ID
    • The unique 16-digit identifier of the user whose certification changed
  • Action
    • The type of change that occurred to this certification
      • Added: the user earned a new certification
      • Updated: one or more attributes of this certification changed
      • Removed: this certification expired or was otherwise removed/made inactive for this user
  • License_id
    • The license id uniquely identifies the specific certification.
    • All possible values for license_id can be retrieved via the get licenses endpoint
  • Issuer
    • The issuer identifies the organization that hosted the course the person took to earn this certification
  • Issue_date
    • The date the certification was issued
  • Expiration_date
    • The date the certification will expire. For some certifications, this may be NULL
  • Updated_at
    • The last timestamp when any data related to this certification changed

• This endpoint is designed to provide an updated list of certifications that are tracked by U.S. Soccer. We will always send the complete list.
• When you create your API credentials with us, you will provide a webhook URL that we will call any time there is any change to the complete list of tracked certifications
• For authorization all incoming webhook notifications will include an http header (Authorization) with a key that we will provide you with. This key is unique to each partner and should be used to secure the webhooks. Unverified requests should be blocked.
• Recommended API implementation
  • Step 9: configure your endpoint to receive these updates and validate the Authorization key for security.
• The request will include all certifications which currently exist, with the following attributes:
  • Name
    • The official name of a certification
    • This is the value we recommend you display in any user interface
  • License ID
    • The unique identifier of this license
    • This is the value that will be used in all other responses
  • Discipline
    • The top-level categorization of this certification, such as “coach” or “referee”
  • Type
    • The second-level categorization of this certification
    • This value is designed to delineate certifications in a primary educational pathway from supplemental pathways or specializations
  • Rank
    • In some disciplines and types, some certifications may be redundant if multiple are simultaneously active
    • 1 is the “highest” rank
    • Example : a Regional referee license has a higher rank value than a Grassroots referee license, because if both are simultaneously active, the activities that the lower rank license qualifies the user for are a subset of those for the higher license.

• This endpoint is designed to notify your system if a subscribed user's USSF-ID ever changes
• When you create your API credentials with us, you will provide a webhook URL that we will call any time there is any change to the USSF-ID of a subscribed user the USSF-ID of subscribed user
• For authorization all incoming webhook notifications will include an http header (Authorization) with a key that we will provide you with. This key is unique to each partner and should be used to secure the webhooks. Unverified requests should be blocked.
• Recommended API implementation
  • Step 10: configure your endpoint to receive these updates and validate the Authorization key for security.
• The request will include the following attributes:
  • Current USSF-ID
    • The OLD unique 16-digit initial identifier of the user
  • New USSF-ID
    • The NEW unique 16-digit updated identifier of the user

• This endpoint is designed to notify your system if a subscribed user's non-license data changes.
• When you create your API credentials with us, you will provide a webhook URL that we will call any time there is change.
• Because the structure of the changed data can vary, the data itself is not included in this call. You will have to perform a follow-up call to retrieve the new data.
• For authorization all incoming webhook notifications will include an http header (Authorization) with a key that we will provide you with. This key is unique to each partner and should be used to secure the webhooks. Unverified requests should be blocked.
• Recommended API implementation
  • Optional: configure your endpoint to receive these updates and validate the Authorization key for security.
  • If you receive this call on your endpoint, use the “changed” data to determine what follow-up call you should perform to retrieve the new data.
• The request will include the following attributes:
  • USSF-ID
    • The unique 16-digit initial identifier of the user
  • Changed
    • referee_experience as a change value
    • grassroots_referee_certificate as a change value

• This endpoint allows you to trigger a test of the “uss-licenses-update” webhook. This method normally will only be invoked when there is a change to our master list of all available licenses.
• Since these changes are rare, we strongly recommend you perform this test to ensure we can successfully send you these updates when they happen.
• Recommended API implementation
  • Step 11: call this endpoint and make sure that your webhook URL for this method receives our call
• Response
  • If the call is successful, the response will simply be a HTTP Status Code 200

• This endpoint allows you to trigger a test of the “user-license-update” webhook. This method will normally only be invoked when there is a change to the licenses of a user record you are subscribed to.
• Since you may not know when the next change will occur, we strongly recommend you perform this test to ensure we can successfully send you these updates when they happen.
• Recommended API implementation
  • Step 12: call this endpoint and make sure that your webhook URL for this method receives our call
• Response
  • If the call is successful, the response will simply be a HTTP Status Code 200
• URI Parameters
  • USSF-ID (string)
    • This 16-digit numeric identifier will correspond to exactly one user record in the Learning Center.
    • If you do not know a person’s USSF-ID, you can use the GET/users endpoint to find it.

• This endpoint allows you to trigger a test of the “ussf-id-update” webhook. This method normally will only be invoked if a subscribed user's USSF-ID ever changes.
• Since these changes are rare, we strongly recommend you perform this test to ensure we can successfully send you these updates when they happen.
• Recommended API implementation
  • Step 13: call this endpoint and make sure that your webhook URL for this method receives our call
• Response
  • If the call is successful, the response will simply be a HTTP Status Code 200

• This endpoint allows you to trigger a test of the “user-update” webhook.
• Since these changes are rare, we strongly recommend you perform this test to ensure we can successfully send you these updates when they happen.
• Response
  • If the call is successful, the response will simply be a HTTP Status Code 200