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

Retrieve background checks for a specific USSF ID with optional filters. Only background checks with expiration dates no more than 2 years in the past are returned. Use the only_latest parameter to retrieve only the most recent background check for the user.

• 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

Background Check API Documentation

Overview

The Background Check API provides endpoints for retrieving and testing background check data for USSF members. This API is part of the U.S. Soccer Learning Center certification system and allows member organizations to access verified background check information.

API Change: Background Check Resource Identifier

Summary:
The API now uses a uid (UUID string) as the unique identifier for background check resources, instead of the internal numeric id. This change improves security, prevents resource enumeration, and aligns with best practices for public APIs.

Details:

• The id field (internal database integer) is no longer included in API responses.
• A new uid field (string, UUID format) is now present in all background check API responses and should be used as the unique identifier for referencing background checks in all API requests and webhooks.
• All endpoints that previously returned or accepted a background check id now use the uid field.
• The uid is a globally unique identifier and is safe to expose externally.

Example Response (Before):

{
"id": 123,
"created_on": "2024-01-15T10:30:00Z",
"status": "approved",
...
}

Example Response (Now):

{
"uid": "b7e23ec2-8d5c-4c2a-9e2e-1b2c3d4e5f6a",
"created_on": "2024-01-15T10:30:00Z",
"status": "approved",
...
}

Migration Notes:

• All client applications should update their logic to use the uid field for referencing background checks.
• The numeric id is now considered an internal-only field and should not be used in API requests or responses.

Benefits:

• Enhanced security and privacy.
• Prevents enumeration of resources via predictable IDs.
• Aligns with modern API design standards.

Authentication

All endpoints require Bearer token authentication. You must first authenticate using the /login endpoint to obtain an access token.

Endpoints

1. Get Background Checks by USSF ID

Endpoint: GET /background-checks/ussf/{ussf_id}

Description: Retrieve background checks for a specific USSF ID with optional filters. Only background checks with expiration dates no more than 2 years in the past are returned. If no background checks are found, validates that the USSF ID exists.

Parameters:

• ussf_id (path, required): USSF ID to search for (16-digit numeric identifier)
• exclude_cancelled (query, optional): Exclude cancelled background checks from results (default: false)
• only_latest (query, optional): If true, returns only the most recent background check for the user. If false or not specified, returns all background checks with expiration dates no more than 2 years in the past (default: false)

Example Request:

curl -X GET "https://connect.learning.ussoccer.com/certifications/background-checks/ussf/1234567891234567?exclude_cancelled=true&only_latest=true" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Request (Latest Only):

curl -X GET "https://connect.learning.ussoccer.com/certifications/background-checks/ussf/1234567891234567?only_latest=true" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response (200):

[
{
  "uid": "b7e23ec2-8d5c-4c2a-9e2e-1b2c3d4e5f6a",
  "created_on": "2024-06-20T11:55:18Z",
  "submitted_at": "2024-06-20T11:55:18Z",
  "updated_on": "2025-06-20T11:55:18Z",
  "expiration_date": "2026-06-20T11:55:18Z",
  "is_expired": false,
  "status": "approved"
},
{
  "uid": "c8f34fd3-9e6d-5d3b-0f3f-2c3d4e5f6a7b",
  "created_on": "2024-06-20T11:55:18Z",
  "submitted_at": "2024-06-20T11:55:18Z",
  "updated_on": "2025-06-20T11:55:18Z",
  "expiration_date": "2026-06-20T11:55:18Z",
  "is_expired": false,
  "status": "not approved"
}
]

Example Response (200) with only_latest=true:

[
{
  "uid": "b7e23ec2-8d5c-4c2a-9e2e-1b2c3d4e5f6a",
  "created_on": "2024-06-20T11:55:18Z",
  "submitted_at": "2024-06-20T11:55:18Z",
  "updated_on": "2025-06-20T11:55:18Z",
  "expiration_date": "2026-06-20T11:55:18Z",
  "is_expired": false,
  "status": "approved"
}
]

Example Response (200) with null values:

[
{
  "uid": "d9f45ge4-0f7e-6e4c-1g4g-3d4e5f6a7b8c",
  "created_on": "2024-06-20T11:55:18Z",
  "submitted_at": null,
  "updated_on": null,
  "expiration_date": null,
  "is_expired": false,
  "status": "not submitted"
}
]

Note: When only_latest=true is used, the response will contain only the most recent background check for the user. The response is still an array, but it will contain at most one item. If no background checks are found, an empty array [] is returned.

Error Responses:

• 400 Bad Request - Validation error

{
  "message": "ussf_id is required"
}

• 404 Not Found - USSF ID not found

{
  "message": "ussf_id does not exist"
}

• 410 Gone - USSF ID has been changed

{
  "message": "ussf_id has been changed",
  "new_ussf_id": "7654321987654321"
}

2. Test Background Check Webhook

Endpoint: POST /test-webhooks/{ussf_id}/background-checks

Description: Trigger a test webhook for background check updates for a specific USSF ID. Requires the customer to have a background_check_update_webhook URL configured. Optionally accepts a JSON payload to override webhook data values.

Parameters:

• ussf_id (path, required): USSF ID to test webhook for (16-digit numeric identifier)

Headers:

• Customer (required): Customer ID header
• Authorization (required): Bearer token

Request Body (optional):

{
"uid": "b7e23ec2-8d5c-4c2a-9e2e-1b2c3d4e5f6a",
"status": "approved",
"is_expired": true,
"created_on": "2024-01-01T00:00:00Z",
"submitted_at": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z",
"expiration_date": "2025-01-01T00:00:00Z"
}

Example Request:

curl -X POST "https://connect.learning.ussoccer.com/certifications/test-webhooks/1234567891234567/background-checks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Customer: 42" \
-H "Content-Type: application/json" \
-d '{"uid": "b7e23ec2-8d5c-4c2a-9e2e-1b2c3d4e5f6a", "status": "approved", "is_expired": true}'

Example Response (200):

{
"message": "Background check webhook sent successfully",
"data": {
  "uid": "b7e23ec2-8d5c-4c2a-9e2e-1b2c3d4e5f6a",
  "created_on": "2024-06-20T11:55:18Z",
  "submitted_at": "2024-06-20T11:55:18Z",
  "updated_on": "2025-06-20T11:55:18Z",
  "expiration_date": "2026-06-20T11:55:18Z",
  "is_expired": false,
  "status": "approved"
}
}

Error Responses:

• 400 Bad Request - Validation error

{
  "message": "ussf_id is required"
}

• 403 Forbidden - Customer not authorized or missing webhook URL

{
  "message": "customer background_check_update_webhook must be filled"
}

• 404 Not Found - No background check data found for USSF ID

{
  "message": "no background check data found for ussf_id"
}

Data Models

BackgroundCheckResponse

Status Values

The status field can have the following values:

• approved - Background check has been completed and approved by the screening provider
• not approved - Background check has been completed but was not approved (failed screening)
• cancelled - Background check was cancelled and is no longer active
• not submitted - Background check record exists but has not been submitted for screening yet
• submitted - Background check has been submitted to the screening provider but is not yet being processed
• pending - Background check is being processed by the provider and awating the result

Webhook Integration

Background Check Update Webhook

When background check data changes, a webhook will be sent to your configured endpoint with the following payload:

{
"event_type": "background_check_updated",
"timestamp": "2024-06-20T11:55:18Z",
"data": {
  "ussf_id": "1234567891234567",
  "uid": "b7e23ec2-8d5c-4c2a-9e2e-1b2c3d4e5f6a",
  "created_on": "2024-06-20T11:55:18Z",
  "submitted_at": "2024-06-20T11:55:18Z",
  "updated_on": "2025-06-20T11:55:18Z",
  "expiration_date": "2026-06-20T11:55:18Z",
  "is_expired": false,
  "status": "approved"
}
}

Field Descriptions:

• event_type (string): Always background_check_updated for this webhook.
• timestamp (string): ISO 8601 timestamp when the event occurred.
• data (object): Background check data, including:
• ussf_id (string): 16-digit USSF ID of the user of the background check.
• uid (string): Background check UUID identifier.
• created_on (string): When the background check was created.
• submitted_at (string|null): When the background check was submitted (nullable).
• updated_on (string|null): When the background check was last updated (nullable).
• expiration_date (string|null): When the background check expires (nullable).
• is_expired (boolean): Whether the background check is expired.
• status (string): Computed status of the background check.

Webhook Security

All incoming webhook notifications include an Authorization header with a unique key for your organization. Unverified requests should be blocked.

Rate Limiting

Standard rate limiting applies to all endpoints. Please implement appropriate retry logic with exponential backoff for failed requests.

Testing

Use the test endpoints to verify your webhook integration:

1. Test Background Check Retrieval: Use the GET endpoint with known USSF IDs
2. Test Webhook Delivery: Use the POST test endpoint to trigger webhook delivery
3. Test Error Handling: Test with invalid USSF IDs and missing parameters

Best Practices

1. Store USSF IDs: Store the 16-digit USSF ID for all users in your system
2. Handle USSF ID Changes: Implement logic to handle 410 responses when USSF IDs change
3. Validate Webhooks: Always validate the Authorization header on incoming webhooks
4. Implement Retry Logic: Use exponential backoff for failed API calls
5. Monitor Expiration: Track background check expiration dates and notify users when renewals are needed
6. Use UUIDs: Always use the uid field for referencing background checks, never the internal id

Migration Guide

For Existing Integrations

If you have existing integrations that use the old id field:

1. Update Response Parsing: Change your code to use uid instead of id
2. Update Storage: Store the uid value instead of the numeric id
3. Update References: Use uid in any API requests or webhook processing
4. Test Thoroughly: Verify all functionality works with the new UUID format

Example Migration

Before:

const backgroundCheck = response.data[0];
const checkId = backgroundCheck.id; // numeric ID

After:

const backgroundCheck = response.data[0];
const checkUid = backgroundCheck.uid; // UUID string

Support

For API credentials and support, please contact panderson@ussoccer.org.

Trigger a test webhook for background check updates for a specific USSF ID. Requires the customer to have a background_check_update_webhook URL configured. Optionally accepts a JSON payload to override webhook data values.

• This endpoint allows you to trigger a test of the "uss-licenses-update" webhook. This method normally would be called automatically by our system when a user's licenses change, but you can use this endpoint to test your webhook implementation.
• The webhook will be sent to the URL specified in your customer configuration.
• You must include the Customer header to identify which customer's webhook URL to use.

• This endpoint allows you to trigger a test of the "user-license-update" webhook. This method normally would be called automatically by our system when a user's licenses change, but you can use this endpoint to test your webhook implementation.
• The webhook will be sent to the URL specified in your customer configuration.
• You must include the Customer header to identify which customer's webhook URL to use.

• This endpoint allows you to trigger a test of the "ussf-id-update" webhook. This method normally would be called automatically by our system when a user's USSF ID changes, but you can use this endpoint to test your webhook implementation.
• The webhook will be sent to the URL specified in your customer configuration.
• You must include the Customer header to identify which customer's webhook URL to use.

• This endpoint allows you to trigger a test of the "user-update" webhook.
• Since these changes can vary in structure, the webhook payload only includes the USSF ID and what changed.
• You will need to make a follow-up API call to get the updated data.
• The webhook will be sent to the URL specified in your customer configuration.
• You must include the Customer header to identify which customer's webhook URL to use.