A guide to using the External HumanTrak API

This guide is intended to provide instructions on how to interact with and use the VALD External HumanTrak API.

• Identify your region
• Optional – Retrieve test descriptions
• Step 1 – Retrieve test data
• Step 2 – Interpret test data
• Example response

Identify your region

The endpoint you use to interact with the HumanTrak API is dependant on what region you (the client) reside in.

Choose your region below and copy the endpoint URL provided.

If you are unsure which region-specific URL you should be using, please contact support@vald.com.

Optional – Retrieve Test Descriptions
URL: /v2/test-type/metrics

Path Parameters

None

Query Parameters

None

Description

If you would like to know which test types and metrics to expect from the External HumanTrak API, you may query this URL before syncing data.

Step 1 – Retrieve Test Data
URL /v2/tests-by-modified-date

Path Parameters

None

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 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 /v2/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 /v2/tests-by-modified-date?TenantId={tenantId}&ModifiedFromUtc={lastModifiedDateUtc}.

Ensure you use the exact high-precision ModifiedDateUtc value served by the API. Do not round the value of lastModifiedDateUtc.

6. Upsert the retrieved test data.
7. Repeat steps 4 - 6 until No Content 204 Status Code is returned.

Step 2 – Interpret Test Data

Description

Test Data from Step 1 provides metricGroups with contained summaryMeasurements and asymmetryMeasurements.

• metricGroups is a list of every metric a test type supports
• summaryMeasurements and asymmetryMeasurements will contain aggregates for each side of the body recorded

Example response

This is an example response one would receive if retrieving data for a Squat Test through the HumanTrak API.

{
  "testId": "<TEST_ID>",
  "startDateUtc": "2021-01-01T00:00:00Z",
  "endDateUtc": "2021-01-01T00:20:00Z",
  "profileId": "<PROFILE_ID>",
  "tenantId": "<TENANT_ID>",
  "modifiedDateUtc": "2021-01-01T00:20:00Z",
  "testTypeCode": "TT_SQUAT-DL",
  "repetitionCounts": [
    {
      "movementSide": "Both",
      "count": 6
    }
  ],
  "metricGroups": [
    {
      "code": "MG_SQUAT-DL_HIP-FLEX-AT-KNEE-FLEX-PEAK",
      "longName": "Hip Flexion at Peak Knee Flexion",
      "shortName": "Hip Flexion",
      "classification": "Secondary",
      "trendSentiment": "Negative",
      "summaryMeasurements": [
        {
          "side": "Left",
          "unit": "Degrees",
          "aggregates": {
            "max": 69.85,
            "min": 23.68,
            "avg": 43.22
          }
        },
        {
          "side": "Right",
          "unit": "Degrees",
          "aggregates": {
            "max": 71.71,
            "min": 28.26,
            "avg": 47.67
          }
        }
      ],
      "asymmetryMeasurement": {
        "unit": "Percent",
        "aggregates": {
          "max": 2.59,
          "min": 16.21,
          "avg": 9.34
        }
      }
    }
  ]
}