Developer Tools: Integrate your PMS / AMS with VALD Hub

You can now integrate your Patient Management System (PMS) or Athlete Management System (AMS) with VALD Hub through our external API. The integration allows for a one-way sync (PMS / AMS → VALD Hub) of profile data, reducing double handling for clinicians and providing an easier workflow for users wishing to use both systems to view patient or athlete data.

This article is intended to be used by product developers who are looking to integrate their PMS / AMS software with VALD Hub. This guide does not go through relevant steps for a clinician to link their systems.

Jump to:

• Obtain your Tenant ID from VALD Hub
• Obtain Client credentials from VALD Support
• Push data to VALD Hub
• Rate Limits
• Redirect users from your PMS / AMS to VALD Hub
• Validate the sync in VALD Hub
• Obtain a VALD Profile ID for an athlete / patient
• Troubleshooting

Obtain your Tenant ID from VALD Hub

To identify the tenant for which you are integrating data, you must obtain the Tenant ID from within their VALD Hub account. Use the instructions located in our Find your VALD Tenant (Organisation) ID article.

Obtain Client credentials from VALD Support

To begin the integration process, you must firstly contact support@vald.com, advising that you are a PMS / AMS provider wishing to integrate your management software with VALD Hub for a mutual client(s). You must provide evidence that you have the required authorisation from your client to access their VALD data.¹

Our support team will then provide you with a VALD Client ID and Client Secret.²

Note: While clinicians (or other users of the PMS / AMS and VALD Hub) can reach out to VALD support to obtain their Client ID and Secret themselves, these details will need to be passed onto their software vendor to complete the integration process.

Authentication is performed via the Client Credentials OAuth 2 Flow. Once authenticated, an application should request an Access Token for use as a Bearer Token within the Authorization Header of an HTTP request.

Push data to VALD Hub

When communicating with VALD's API you must now use the region-specific URL for the tenant you are currently processing. Unsure which region to use for a tenant? Contact support@vald.com.

The following steps reference the Australian External Profile API URL. See our API November 2023 Update for the correct region-based URL if the tenant is outside of Australia.

Steps on how to push data through to VALD Hub can be found in this Swagger UI documentation.

It is recommended that before pushing data to VALD, an HTTP DELETE call is performed to /profiles/syncids. This will ensure that if the mutual client has previously integrated with another system, any links have been removed and will not interfere with your integration.

const deleteResponse = await
axios.delete('https://prd-aue-api-externalprofile.valdperformance.com/profiles/syncids?tenantid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
{
headers: {"Authorization": 'Bearer ${accessToken}'}
}
);

To send data to VALD you must obtain an access token, which is valid for 120 minutes. This is done through a server-side API call to VALD's Identity Server.

Some sample code for the token request, based on the Node.js back-end would be:

const params = new URLSearchParams();
params.append("grant_type", "client_credentials");
params.append("client_Id", "[insert client_id here]");
params.append("client_secret", "[insert client_secret here]");

const response = await axios.post('https://security.valdperformance.com/connect/token', params);
const accessToken = response.data.access_token;

The data which can be submitted must be presented in the following format in another server-side API call:

const body = {
DateOfBirth: "1970-03-31T00:00:00Z",
Email: "john.hancock@somedomain.com",
GivenName: "John",
FamilyName: "Hancock",
TenantId: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
SyncId: "XXXXXXXX",
Sex: "Male",
};

const postResponse = await axios.post('https://prd-aue-api-externalprofile.valdperformance.com/profiles/import',
body,
{
headers: {"Authorization": 'Bearer ${accessToken}'}
}
);

where:

TenantId is:	The tenant id within VALD for which the patient / athlete is being added or edited.
SyncId is:	The identifier for the patient / athlete in your PMS / AMS system.

Rate Limits

Rate limiting is currently set to 25 requests in a five second period. This may change in the future.

Redirect users from your PMS / AMS to VALD Hub

The unique TenantID and SyncID are used on a redirection landing page to direct the user to the corresponding profile in VALD Hub.

This redirection can be built into the patient / athlete's profile page in your management system. The button within your PMS / AMS must navigate to the below link, with tenantId referencing the correct tenant, and syncId pulling in the relevant patient or athlete's identifier.

https://hub.valdperformance.com/app/pmsRedir?tenantId={tenantId}&syncId={syncId}

Validate the sync

To confirm that the sync has worked as expected, navigate to the Profiles tab in the client's VALD Hub account. Use the search bar to find any new patients that were created in your PMS / AMS since the sync was initiated.

Obtain a VALD Profile ID for an athlete / patient

When using our external measurement APIs, VALD's unique identifier for the patient / athlete must be provided. If this information is not available to your application, it can be retrieved using the profiles endpoint which, given the Sync ID and Tenant ID will return profiles matching the parameters, including their unique Profile ID which can then be used with external measurement APIs.

Troubleshooting

I cannot post data to the External Profile API

Check your data structure. It must match the structure exactly as defined in the Swagger documentation. See the sample code above for an example.

The redirection is not linking to the correct profile / I'm receiving a 'Failed to Load Profile' error

Check to ensure that the TenantId and SyncId are correct.

I am receiving a '429' response

Please see the Rate Limits section above for more details.