Integration (API) Best Practices

This article assumes you have a sound knowledge of API integrations.

As of November 2023, you must ensure you are using the tenant's corresponding region-based API URL (Australia (East), United States (East), or Europe (West)). Each region-specific URL has been listed under the relevant API heading below.

When integrating with VALD through our external APIs, it is best practice to consume the team level endpoints rather than iterating through each athlete in a team.

When retrieving tests through our API endpoints, it is now mandatory to supply the last point in time you successfully retrieved tests for the tenant. This would usually be done with a query parameter modifiedFromUTC or modifiedFrom.

Generally speaking, retrieving tests would look something like this:

1. Retrieve the initial page using a URL similar to /teams/{teamId}/tests?modifiedFromUTC={timestampOfLastRequest}.
2. Save the date and time of the request into the timestampOfCurrentRequest variable.
3. Check the currentPage and totalPages properties in the returned DTO.
   Note this does not currently exist for SmartSpeed API (more on this below).
4. If currentPage < totalPages retrieve the next page using /v2022q2/teams/{teamId}/tests?modifiedFromUTC={timestampOfLastRequest}&page={currentPage+1}.
5. Repeat steps 3 and 4 until currentPage = totalPages.
6. Set timestampOfLastRequest to the value in timestampOfCurrentRequest.

Jump to:

• NordBord
• HumanTrak 2.0
• ForceFrame
• DynaMo
• ForceDecks
• SmartSpeed

NordBord API

Test Endpoint for a Specific Team
URL: /tests

Path Parameters:

None.

Important Query Parameters:

HumanTrak 2.0 API

There are three steps to retrieve HumanTrak 2.0 data detailed below. Please read through each step carefully.

1. Retrieve test data
2. Retrieve test descriptions
3. Interpret test data

Step 1: Retrieve Test Data
URL: /v1/tests-by-modified-date

Path Parameters:

None.

Important Query Parameters:

Description:

To iterate through all HumanTrak test results for this Tenant, use the following steps.

Note: Tests are returned in ascending order of Modification Date (i.e. oldest to newest).

1. Set the startDate variable.
   1. If HumanTrak 2.0 test data has been previously retrieved and saved for this Tenant, do the following:
      1. From the saved test data, find the test with the most recent ModifiedDateUtc and set startDate to this ModifiedDateUtc.
   2. Otherwise, if this is the first time:
      1. Set startDate variable to 1970-01-01T00:00:00Z
2. Retrieve a page of data using /v1/tests-by-modified-date?TenantId={tenantId}&ModifiedFromUtc={startDate}.
3. Upsert the retrieved test data (i.e. update tests that already exist in your database and insert new tests that don't exist).
4. In your saved data, find the test with the most recent ModifiedDateUtc. Save this date into the lastModifiedDateUtc variable.
5. Retrieve the next page of data using /v1/tests-by-modified-date?TenantId={tenantId}&ModifiedFromUtc={lastModifiedDateUtc}.
6. Upsert the retrieved test data.
7. Repeat steps 4 - 6 until No Content 204 Status Code is returned.

Step 2: Retrieve Test Descriptions
URL: /v1/test-type/metrics

Path Parameters:

None.

Important Query Parameters:

None.

Description:

Use to retrieve Test Type and Metric Descriptions to help interpret the Test Data.

Step 3: Interpret Test Data

Description:

Test Data from Step 1 provides Code and Value pairs to describe a Test.

• Code is a Test Metric ID
• Value is the recorded measurement for the Test Metric

Test Descriptions from Step 2 provides information (including Names and Units) about the Test Metric Codes.

Match the Code IDs from Step 1 and Step 2 to interpret the Test Data.

ForceFrame API

Test Endpoint for a Specific Team
URL: /tests

Path Parameters:

None.

Important Query Parameters:

DynaMo API

Test Endpoint for a Specific Team
URL: /v2021q2/teams/{teamId}/tests

Path Parameters:

Important Query Parameters:

ForceDecks API

Test Endpoint for a Specific Team
URL: /v2019q3/teams/{teamId}/tests/{page}

Path Parameters:

Important Query Parameters:

SmartSpeed API

Test Endpoint for a Specific Team
URL /v1/team/{teamId}/tests

Path Parameters:

Important Query Parameters:

This API does not return the number of pages as per the best practice section at the top of this article.

To iterate through the total pages using the SmartSpeed API External Test Endpoint, use the following steps.

1. Set currentPage variable to 1.
2. Retrieve the first page of data using /v1/team/{teamId}/tests?ModifiedFromUTC={timestampOfLastRequest}&Page={currentPage}.
3. Save the date and time of the request into the timestampOfCurrentRequest variable.
4. Check if the returned data array is empty or contains tests.
   1. If contains tests:
      1. Increment currentPage by 1.
      2. Retrieve the next page using /v1/team/{teamId}/tests?ModifiedFromUTC={timestampOfLastRequest}&Page={currentPage}.
      3. Return to the start of step 4.
   2. If empty:
      1. Set timestampOfLastRequest to the value in timestampOfCurrentRequest.
      2. There is no more data to retrieve.

DECOMMISSIONED - DashBord API

DashBord API has been decommissioned and replaced with four region-specific APIs: NordBord, ForceFrame, External Profile, and External Tenant. See our API November 2023 Update for more details.

https://dbapi.valdperformance.com/index.html?urls.primaryName=v2021q2

Test Endpoint for a Specific Team
URL: /v2021q2/teams/{teamId}/tests

Path Parameters:

Important Query Parameters: