System
AirBands DynaMo ForceDecks ForceFrame HumanTrak NordBord SmartJump SmartSpeed MoveHealth VALD Hub
Contact us

Search

A guide to using the External ForceFrame API

Liesl Thrum
  • Updated

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

The External ForceFrame API can be utilised to access team and athlete test data.

Identify your region

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

Please note that only tenant data which resides within the region of the API endpoint used is accessible. Therefore, if a tenant's data resides in Australia (East), it will only be accessible from that region's API.

Choose your region below and copy the endpoint URL provided.

Australia (East)
https://prd-aue-api-externalforceframe.valdperformance.com/swagger/index.html
United States (East)
https://prd-use-api-externalforceframe.valdperformance.com/swagger/index.html
Europe (West)
https://prd-euw-api-externalforceframe.valdperformance.com/swagger/index.html

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

Scenario 1: Retrieve a collection of tests for a tenant
Updated

This is the recommended method to retrieve a list of tests for a tenant.

URL

/tests/v2

Path Parameters

None.

Query Parameters

Parameter Required Description
tenantId True ID of the tenant from which to retrieve tests.
modifiedFromUtc True

Retrieve tests modified after the specified UTC date.

Format: YYYY-MM-DDT00:00:00.000Z
profileId False ID of the athlete from which to retrieve tests.

Description

  1. Set the required parameters.
    • Set the tenantId parameter. This is your organization's unique identifier.
    • Set the modifiedFromUtc parameter. This is the date and time from which you want to retrieve test data (formatted in UTC).
  2. Retrieve your data. Here are a few examples of how to structure your requests:

Request 1: Retrieve all tests modified after a specific date and time

/tests/v2?TenantId={tenantId}&ModifiedFromUtc={modifiedFromUtc}

  • To get the next set of paged records, use the modifiedDateUtc value of the last record as the value for the modifiedFromUtc query parameter in your next request.
  • This will return all tests for the tenant from the specified date and time.

Request 2: Retrieve tests for a specific profile

/tests/v2?TenantId={tenantId}&ModifiedFromUtc={modifiedFromUtc}&ProfileId={profileId}

  • As with Request 1, use the modifiedDateUtc value of the last record for pagination.
  • This request will return tests filtered by tenant and profile.

Request 3: Retrieve all tests modified in the last 2 hours

/tests/v2?TenantId={tenantId}&ModifiedFromUtc={modifiedFromUtc}

  • If the current UTC time is 2024-02-12T09:00:00.1234567Z, set modifiedFromUtc to 2 hours earlier (i.e. 2024-02-12T07:00:00.1234567Z).
  • This will return all records modified in the past 2 hours.

Note: You cannot retrieve tests using a specific date range, as described in the previous example.

  1. Repeat the above steps until you receive a 204 No Content status code, which indicates there are no more records to retrieve.
Tests are returned in ascending order of {modifiedFromUtc} (i.e. oldest to newest).

Response

Example response

{
  "tests": [
    {
      "profileId": "<PROFILE-ID>",
      "testId": "<TEST-ID>",
      "testDateUtc": "2023-01-25T00:00:00.000Z",
      "testTypeId": "<TEST-TYPE-ID>",
      "testPositionId": "<TEST-POSITION-ID>",
      "notes": "Ankle Testing",
      "innerLeftAvgForce": 297,
      "innerLeftImpulse": 2796,
      "innerLeftMaxForce": 326,
      "innerLeftRepetitions": 3,
      "innerRightAvgForce": 293,
      "innerRightImpulse": 2758,
      "innerRightMaxForce": 320,
      "innerRightRepetitions": 3,
      "outerLeftAvgForce": 337,
      "outerLeftImpulse": 3173,
      "outerLeftMaxForce": 340,
      "outerLeftRepetitions": 3,
      "outerRightAvgForce": 347,
      "outerRightImpulse": 3267,
      "outerRightMaxForce": 386,
      "outerRightRepetitions": 3,
      "device": "ForceFrame - 1337",
      "modifiedDateUtc": "2023-10-02T03:32:13.5367851Z",
      "testTypeName": "Ankle IN/EV",
      "testPositionName": "Ankle Inversion/Eversion - Supine"
    }
  ]
}

Scenario 2: Retrieve a collection of tests for a tenant
Planned for deprecation

This approach is no longer preferable and will be deprecated in future. Please use Scenario 1 above to retrieve a collection of tests for a tenant.

Details

URL: /tests
Path Parameters: None
Query Parameters:
Parameter Required Description
tenantId True ID of the tenant from which to retrieve tests.
modifiedFromUtc True

Retrieve tests modified after the specified UTC date.

Format: YYYY-MM-DDT00:00:00.000Z
testFromUtc True

Retrieve tests recorded after the specified UTC date.

Format: YYYY-MM-DDT00:00:00.000Z
testToUtc True

Retrieve tests recorded before the specified UTC date.

Format: YYYY-MM-DDT00:00:00.000Z
athleteId False ID of the athlete from which to retrieve tests.
page False The page number to return.
Default is 1.
pageSize False The number of tests returned by a single page.
Default is 1 – max value is 100.

Description

  1. Set the required parameters.
    1. Ensure the testFromUtc and testToUtc are within six months of each other.
    2. Use the modifiedFromUtc as a mechanism to refine the tests down further. If unsure, set this parameter to be equal to testFromUtc.
    3. Set page equal to 1.
  2. Retrieve a page of data using

    /tests?TenantId={tenantId}&ModifiedFromUtc={modifiedFromUtc}&TestFromUtc={testFromUtc}&TestToUtc={testToUtc}&Page={page}

  3. Increment the page parameter.
  4. Repeat steps 2 - 3 until a No Content 204 status code is returned.

Note: Tests are returned in descending order of test date (i.e. newest to oldest).

Response

Example response

{
    "tests": [
        {
            "athleteId": "<PROFILE-ID>",
            "testId": "<TEST-ID>",
            "testDateUtc": "2023-04-24T03:51:32.933Z",
            "testTypeId": "0ca48841-2ddc-40b9-935a-bc7097870d4c",
            "testPositionId": "fb5672f3-da6a-4e17-b515-e2458d81c1f0",
            "notes": "Training Camp (April)",
            "innerLeftAvgForce": 163.60714285714283,
            "innerLeftImpulse": 589.35,
            "innerLeftMaxForce": 184.5,
            "innerLeftRepetitions": 7,
            "innerRightAvgForce": 108.625,
            "innerRightImpulse": 444.12499999999994,
            "innerRightMaxForce": 113.25,
            "innerRightRepetitions": 8,
            "outerLeftAvgForce": 32.5,
            "outerLeftImpulse": 0.0,
            "outerLeftMaxForce": 32.5,
            "outerLeftRepetitions": 0,
            "outerRightAvgForce": 24.625,
            "outerRightImpulse": 0.0,
            "outerRightMaxForce": 24.625,
            "outerRightRepetitions": 0,
            "device": "ForceFrame-1359",
            "modifiedDateUtc": "2023-10-02T03:33:05.871Z",
            "testTypeName": "Neck Lateral Flexion",
            "testPositionName": "Neck Lateral Flexion - Quadruped"
        },
        ...
        {
            "athleteId": "<PROFILE-ID>",
            "testId": "<TEST-ID>",
            "testDateUtc": "2023-01-25T00:00:00.000Z",
            "testTypeId": "3ba718ba-abaf-44e2-8186-3ac4c16c7149",
            "testPositionId": "6d0049c8-019e-463c-a6e1-dd92eeb379d9",
            "notes": "Training Camp (January)",
            "innerLeftAvgForce": 0.0,
            "innerLeftImpulse": 0.0,
            "innerLeftMaxForce": 0.0,
            "innerLeftRepetitions": 3,
            "innerRightAvgForce": 0.0,
            "innerRightImpulse": 0.0,
            "innerRightMaxForce": 0.0,
            "innerRightRepetitions": 3,
            "outerLeftAvgForce": 289.0,
            "outerLeftImpulse": 2727.0,
            "outerLeftMaxForce": 332.0,
            "outerLeftRepetitions": 3,
            "outerRightAvgForce": 290.0,
            "outerRightImpulse": 2733.0,
            "outerRightMaxForce": 330.0,
            "outerRightRepetitions": 3,
            "device": "ForceFrame - 1337",
            "modifiedDateUtc": "2023-10-02T03:33:13.854Z",
            "testTypeName": "Elbow Extension",
            "testPositionName": "Elbow Extension - Seated"
        }
    ],
    "page": 1,
    "pageCount": 3
}

Scenario 3: Retrieve a single test

Details

URL: /tests/{testId}
Path Parameters:
Parameter Required Description
testId True ID of test to retrieve.
Query Parameters:
Parameter Required Description
tenantId True ID of the tenant from which to retrieve tests.

Description

Use to retrieve summary information about a test.

Response

Example response

{
    "athleteId": "<PROFILE-ID>",
    "testId": "<TEST-ID>",
    "testDateUtc": "2023-04-24T03:51:32.933Z",
    "testTypeId": "0ca48841-2ddc-40b9-935a-bc7097870d4c",
    "testPositionId": "fb5672f3-da6a-4e17-b515-e2458d81c1f0",
    "notes": "Training Camp (April)",
    "innerLeftAvgForce": 163.60714285714283,
    "innerLeftImpulse": 589.35,
    "innerLeftMaxForce": 184.5,
    "innerLeftRepetitions": 7,
    "innerRightAvgForce": 108.625,
    "innerRightImpulse": 444.12499999999994,
    "innerRightMaxForce": 113.25,
    "innerRightRepetitions": 8,
    "outerLeftAvgForce": 32.5,
    "outerLeftImpulse": 0.0,
    "outerLeftMaxForce": 32.5,
    "outerLeftRepetitions": 0,
    "outerRightAvgForce": 24.625,
    "outerRightImpulse": 0.0,
    "outerRightMaxForce": 24.625,
    "outerRightRepetitions": 0,
    "device": "ForceFrame-1359",
    "modifiedDateUtc": "2023-10-02T03:33:05.871Z",
    "testTypeName": "Neck Lateral Flexion",
    "testPositionName": "Neck Lateral Flexion - Quadruped"
}

Scenario 4: Retrieve a ForceFrame force trace associated with a single test

Details

URL: /tests/{testId}/forceframetrace
Path Parameters:
Parameter Required Description
testId True ID of test to retrieve.
Query Parameters:
Parameter Required Description
tenantId True ID of the tenant from which to retrieve tests.

Description

Use to retrieve a ForceFrame force trace.

Response

Example response

{
    "athleteId": "<PROFILE-ID>",
    "testId": "<TEST-ID>",
    "testTypeId": "0ca48841-2ddc-40b9-935a-bc7097870d4c",
    "testTypeName": "Neck Lateral Flexion",
    "testPositionId": "fb5672f3-da6a-4e17-b515-e2458d81c1f0",
    "testPositionName": "Neck Lateral Flexion - Quadruped",
    "forces": [
        {
            "ticks": 638179046401209472,
            "innerLeftForce": 0.0,
            "innerRightForce": 0.0,
            "outerLeftForce": 0.0,
            "outerRightForce": 0.0
        },
        ...
        {
            "ticks": 638179050916719232,
            "innerLeftForce": 0.0,
            "innerRightForce": -1.0,
            "outerLeftForce": -0.0,
            "outerRightForce": 0.5
        }
    ],
    "device": "ForceFrame-1359",
    "testDateUTC": "2023-04-24T03:51:32.933Z",
    "notes": "Training Camp (April)"
}

Comments

0 comments

Please sign in to leave a comment.

Related articles