Our external API allows you to integrate your Patient Management System (PMS) or Athlete Management System (AMS) with VALD Hub. 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:
Requesting API access
Locate organization ID(s)
To identify the tenant for which you are integrating data, you must obtain the tenant's ID from within their VALD Hub platform – known commonly as the organization ID.
If you do not already have a VALD Hub account with the organization, find someone who does. You or this nominated person should follow the instructions here to locate and copy the organization ID.
Send access request email
Email support@vald.com advising that you are a PMS / AMS provider wishing to integrate your software with VALD Hub. Provide the relevant organization ID(s) in your email, as well as evidence that you have sought authorization from your client to access their VALD data.
→ This should be a written authorization, such as an email, from the client. When reaching out to VALD support, you can also CC your client so our team can liaise directly with them.
Obtain API credentials
Once approved, our team will send you a welcome email containing your API clientId and clientSecret.
The link containing your API credentials will expire in seven days.
Authentication is performed via the Client Credentials OAuth 2 Flow. Once authenticated, you will receive an access token to use as a Bearer token within the authorization header of an HTTP request.
→ Clients can get in touch with VALD support themselves to obtain their credentials and pass this information on to you – their PMS / AMS software vendor.
Integrating with VALD Hub
To send data to VALD you must authenticate your request by obtaining an access token.
→ Refer to our best practices and sample code to request and cache your access tokens.
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}'}
}
);The profile data which can be imported 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",
ExternalId: "XXXXXXX",
isCreatedByUserOver18YearsOld: true,
isGuardianConsentGiven: true,
isPhotoVideoConsentGiven: true
};
const postResponse = await axios.post('https://prd-aue-api-externalprofile.valdperformance.com/profiles/import',
body,
{
headers: {"Authorization": 'Bearer ${accessToken}'}
}
);| where: | |
| TenantId is: | The tenant identifier within VALD for which the patient / athlete is being added or edited. |
| SyncId is: | Your primary key: the identifier for the patient / athlete in your PMS / AMS system. This must be unique within a VALD tenant. |
| ExternalId is: | Optional. Any additional miscellaneous ID supplied by you, as an external reference on a profile. There are no unique constraints on this property. |
| Email is: | Optional. This does not need to be unique within a VALD tenant. |
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.
Group management and security
When setting up a VALD tenant, data can be segregated into groups – this allows the administrator of the mutual VALD user to set up group-level permissions to control data their users can (or cannot) access.
Before uploading profiles to VALD, you should contact the VALD user to understand their group configuration(s) and any potential rules for assigning profiles to groups.
Note: In the case where the VALD user has been assigned group-based permissions, and profiles are created without assigning them to any groups, those profiles will only be accessible to an administrator.
→ Refer to A Guide to using the External Profiles API for instructions on how to import profiles and assign profiles to groups.
→ Refer to A Guide to using External Tenants API for details on retrieving existing group information.
Setting up a redirect to VALD Hub
The unique Tenant ID and Sync ID 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 or athlete's profile page in your management system. The button within your PMS / AMS must navigate to the below link, with the tenantId referencing the correct tenant and syncId set to the relevant patient or athlete's identifier.
VALD profile IDs for athletes / patients
When using our external measurement APIs, VALD's unique identifier for the patient or athlete must be provided. If this information is not available to your application, it can be retrieved using the GET /profiles endpoint. Given the Sync ID and Tenant ID, this endpoint will return profiles matching the supplied parameters, including our unique profileId 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.
Comments
0 comments
Please sign in to leave a comment.