A guide to using the External HumanTrak 2.0 API

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

• Identify your region
• Retrieve test data
• Retrieve test descriptions
• Interpret test data
• Example use case

Identify your region

The endpoint you use to interact with the HumanTrak 2.0 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.

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.

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.

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 [name] and [unit]) about the Test Metric Codes.

Match the Code IDs from Step 1 and Step 2 to interpret the test data and provide you with metric results.

Example use case

These are example responses one would receive if retrieving data for a Squat Test through the HumanTrak 2.0 API.

Retrieve test data

Response:

{
  "testId": "<TEST-ID>",
  "profileId": "<PROFILE-ID>",
  "testTypeCode": "TT_SQUAT-DL",
  "summaryMetricResults": [
    {
      "code": "SMT_SQUAT-DL_KNEE-FLEX-LEFT-PEAK_AVG",
      "value": 118.34
    },
    {
      "code": "SMT_SQUAT-DL_KNEE-FLEX-RIGHT-PEAK_AVG",
      "value": 117.91
    }
  ],
  "asymmetryMetricResults": [
    {
      "code": "AMT_SQUAT-DL_KNEE-FLEX-PEAK_AVG",
      "value": -0.37
    }
  ]
}

Retrieve test descriptions

Response:

[
  {
    "code": "TT_SQUAT-DL",
    "name": "Squat",
    "metricGroups": [
      {
        "code": "MG_SQUAT-DL_KNEE-FLEX-PEAK",
        "longName": "Peak Knee Flexion",
        "summaryMetricTypes": [
          {
            "code": "SMT_SQUAT-DL_KNEE-FLEX-LEFT-PEAK_AVG",
            "name": "Average Peak Knee Flexion Left",
            "unit": "Degrees",
            "calculationType": "Average"
          },
          {
            "code": "SMT_SQUAT-DL_KNEE-FLEX-RIGHT-PEAK_AVG",
            "name": "Average Peak Knee Flexion Right",
            "unit": "Degrees",
            "calculationType": "Average"
          }
        ],
        "asymmetryMetricTypes": [
          {
            "code": "AMT_SQUAT-DL_KNEE-FLEX-PEAK_AVG",
            "name": "Asymmetry Average Peak Knee Flexion",
            "leftSummaryMetricTypeCode": "SMT_SQUAT-DL_KNEE-FLEX-LEFT-PEAK_AVG",
            "rightSummaryMetricTypeCode": "SMT_SQUAT-DL_KNEE-FLEX-RIGHT-PEAK_AVG"
          }
        ]
      }
    ]
  }
]]

Interpret test data

To interpret the test data, you must combine the metric [value] from the "Retrieve test data" set with the metric [name] and [unit] from the "Retrieve test descriptions" step. This will then fully describe the metric result as [name] : [value] [unit].

{
  "testId": "<TEST-ID>",
  "profileId": "<PROFILE-ID>",
  "name": "Squat",
  "summaryMetricResults": [
    {
      "name": "Average Peak Knee Flexion Left",
      "unit": "Degrees",
      "calculationType": "Average",
      "value": 118.34
    },
    {
      "name": "Average Peak Knee Flexion Right",
      "unit": "Degrees",
      "calculationType": "Average",
      "value": 117.91
    }
  ],
  "asymmetryMetricResults": [
    {
      "name": "Asymmetry Average Peak Knee Flexion",
      "leftSummaryMetricTypeCode": "SMT_SQUAT-DL_KNEE-FLEX-LEFT-PEAK_AVG",
      "rightSummaryMetricTypeCode": "SMT_SQUAT-DL_KNEE-FLEX-RIGHT-PEAK_AVG",
      "value": -0.37
    }
  ]
}

Output:

• Average Peak Knee Flexion Left: 118.34 Degrees
• Average Peak Knee Flexion Right: 117.91 Degrees
• Asymmetry Average Peak Knee Flexion: -0.37%.