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

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.

Retrieve test descriptions (Optional)
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.

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:

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.

Interpret test data

Description

Test data 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 for 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
        }
      }
    }
  ]
}

Retrieve repetition data
URL: GET /v2/test/{testId}/repetitions

Once you've identified the test to be analyzed, you can pull all its repetition‑level data as well. This is especially useful if you need granular, rep‑by‑rep insights.

Path Parameters

Query Parameters

Description

To retrieve repetitions for a test:

1. First, retrieve the list of tests using Steps 1 above.
   From those responses, you will have:
   • testId
   • tenantId
   • profileId
2. For each test you want to analyze, send a GET request to the endpoint.
   You will receive a structured list of repetitions, where each rep includes:
   • the rep number
   • the side (both/left/right)
   • all associated metrics and metric values

Example response

{
  "testTypeCode": "TT_SQUAT-DL",
  "repetitions": [
    {
      "number": 1,
      "side": "Both",
      "metrics": [
        {
          "metricGroupCode": "MG_SQUAT-DL_ANKLE-DORSIFLEXION-AT-PEAK-KNEE-FLEXION",
          "values": {
            "isSided": true,
            "leftValue": 11.11
            "rightValue": 13.89            
          }
        },
        {
          "metricGroupCode": "MG_SQUAT-DL_PELVIS-ANTERIOR-TILT-AT-KNEE-FLEX-PEAK",
          "values": {
            "isSided": false,
            "unsidedValue": 22.22
          }
        }
      ]
    }
  ]
}

Interpret repetition data

To make it easier for practitioners and analysts to work with the response:

number
Represents the repetition number (1, 2, 3, …).

side
Indicates which side the repetition applies to.

• "Both" → A bilateral test repetition (e.g. squat).
• "Left" or "Right" → A unilateral test repetition (e.g. single-leg squat).
• "NotApplicable" → A test repetition with no sidedness (e.g. trunk flexion).

isSided (for each metric)

• If true, the metric returns both a leftValue and rightValue.
• If false, the metric returns a single unsidedValue.

Important for unilateral tests:

Each repetition corresponds to only one side.

• The performing side returns its value.
• The non‑performing side will return null for sided metrics.

This structure allows for clean downstream analysis regardless of movement type, especially when blending bilateral and unilateral tests in multi‑test pipelines.