How to integrate with VALD APIs

This article assumes you have a sound knowledge of API integrations.

Welcome to our VALD API documentation! This article provides an overview of how to get started with our APIs, including access instructions, testing workflows, best practices, and getting production-ready.

You can use this guide as your starting point, then jump into our system-specific API documentation guides.

Whether you're retrieving data for analysis, building custom integrations, or automating workflows, our APIs are designed to provide a seamless experience.

How to request API access

To gain access to the VALD APIs, you will need to do the following.

Send access request email

Email support@vald.com requesting access to our external APIs. In your email please include your VALD Hub Organization ID.

If you are a third-party organization requesting access (e.g. AMS, PMS, or developing a solution on behalf of another organization):

• In the email to our support team, ensure you CC a representative of the organization for approval.
• After your original request email, we will respond requiring you to sign an API License Agreement before providing you access. Review and sign the agreement, then send it back to finalize your request.

Retrieve access keys

Once approved, our team will send you a welcome email containing your API access keys. These keys are required to make requests so keep them secure.

The link containing your API access keys will expire in seven days.

Best practices for storing API access keys

To keep your API access keys secure, avoid hard-coding them directly into your code or scripts.

Instead, use environment variables or secure credential management tools to store them. This helps prevent accidental exposure. You should always treat your access keys as sensitive information.

Getting started with our APIs

Region-specific URLs

To begin using the Swagger pages, you need to identify your region to retrieve the correct URL. The endpoint you use to interact with the API is dependent on your (i.e. the tenant's) region.

Please note:

• Tenant data is region-specific. Only data from tenants residing within the region of the API endpoint used will be accessible. For example, if a tenant's data resides in Australia (East), it will only be accessible through that region's API endpoints.
• Ensure you use the correct regional URL for both testing in Swagger and API integration to avoid errors or inaccessible data.

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

Use Swagger for exploration

Each API has a corresponding Swagger page that provides a detailed, interactive view of its endpoints. These pages allow you to:

• Explore available endpoints and their functionality.
• Test API requests directly within the Swagger interface.
• View the API schema, located at the bottom of the Swagger page, for an in-depth look at inputs and outputs, including data fields and types for each endpoint.

We recommend starting with the Swagger pages to familiarize yourself with how the APIs work and validate your requests before integrating them into your workflow. This ensures you are working with the correct data and formats from the start.

Finding Swagger URLs

You can find the Swagger URLs for each API, along with the three applicable regions, in the system-specific API documents.

Best practice steps for initial data requests

Getting familiar with our APIs through Swagger involves a few key steps to ensure a smooth and secure integration. Follow these recommended best practices for your initial data requests:

Suggested considerations

• Understand rate limits – Familiarize yourself with the API's rate-limiting behavior to avoid throttling and ensure efficient usage. If you exceed the allowed number of requests within a specified time frame, the API will return a 429 - Too Many Requests response.
• Data scope – Review the API schema to understand the data fields and endpoints relevant to your integration.
• Security – Keep your access keys confidential.

Step-by-step guide for initial requests

In this example we will use the External Tenants API to extract a list of all the tenants you have access to. Once you have retrieved the tenantId list, you can use these to query other VALD APIs.

1. Identify your region-specific URL
   1. Navigate to our External Tenants API article to find the Swagger URL for your specific region.
2. Open the region-specific Swagger page
   1. Use the identified URL to access the Swagger interface for your region.
3. Authorize your access
   1. At the top of the Swagger page, click the button.
   2. Enter the clientId and clientSecret credentials provided to you by VALD Support to authenticate your access.
4. Retrieve your Tenant ID
   1. Locate and call the GET /tenants endpoint in the Swagger interface.
   2. Click the 'Try it out' button to test executing the endpoint.
   3. This will return a copy of the tenantId you have access to, which is essential for interacting with our other APIs.
5. Access additional data
   1. With your tenantId retrieved, you can now use this to access VALD's other APIs.
   2. For example, navigate to the Profiles API and call the GET /profiles endpoint to return a list of all profiles (athletes) within your organization. You can use this information to create a reference table and easily link tests to your profile's information.

By following these steps you can securely test your authentication, retrieve foundational information, and pull data through the VALD APIs via Swagger.

Getting production-ready

Building on the content described in the section above, the following guidance will help you move from testing to a stable, production-ready integration.

Key steps for production readiness

1. Perform incremental data pulls.
   • Start with small, targeted data requests to ensure stability and verify consistent results.
   • Once you are confident you have set up your data requests correctly, start by pulling your historical data (if required), as this provides a comprehensive foundation for your integration.
   • After the initial full data pull, switch to incremental data pulls (e.g. only new or updated data since the last pull) to minimize the overall data transfer and improve efficiency.
2. Monitor and optimize your integration.
   • Use logging or monitoring tools to help track your API usage, focusing on metrics such as the number of requests made, response times, and error rates. This will help you optimize your integrations and ensure you stay within the rate limits, avoiding service interruptions by receiving a 429 - Too Many Requests response.
   • Periodically review your integration's performance and consider optimizations where necessary. This might include revisiting query parameters to reduce redundancy.
3. Ensure proper authentication.
   • When transitioning from testing in Swagger to production-ready scripts, you must ensure that your scripts remain authenticated for the duration of their execution.
   • API Bearer tokens are only valid for two hours, so you will need to periodically request a new token during runtime. To optimize usage and avoid unnecessary token requests, you should cache your token and reuse it for its valid duration.
   • Periodically check the token's expiration time and refresh only when necessary.

Below is a sample code snippet to assist you in requesting, generating, and caching a Bearer token using your clientId and clientSecret. This code simply generates your token and does not query any endpoints.

let tokenCache = {
    accessToken: null,
    expiresAt: null
};

// Function to retrieve and cache a Bearer token for authentication
async function getToken(clientId, clientSecret) {
    /**
     * Retrieves a Bearer token using clientId and clientSecret.
     * If a valid token exists in the cache, no action is taken.
     *
     * @param {string} clientId - The client ID provided by support.
     * @param {string} clientSecret - The client secret provided by support.
     * Note: Ensure these credentials are stored securely and not hard-coded in your script.
     */

    // If a valid token exists in the cache, do nothing
    if (tokenCache.accessToken && tokenCache.expiresAt && tokenCache.expiresAt > Date.now()) {
        console.log("Returning cached token:", tokenCache.accessToken);
        return tokenCache.accessToken;
    }


    // Define the grant type for the token request
    const grantType = "client_credentials";

    // URL for the authentication endpoint
    const url = "https://security.valdperformance.com/connect/token";

    try {
        // Send a POST request to the auth endpoint with client credentials
        const response = await fetch(url, {
            method: "POST",
            headers: {
                "Content-Type": "application/x-www-form-urlencoded"
            },
            body: new URLSearchParams({
                grant_type: grantType,  // Specify the grant type for token retrieval
                client_id: clientId,    // Include the client ID in the request body
                client_secret: clientSecret  // Include the client secret in the request body
            }).toString()
        });

        // Handle HTTP errors
        if (!response.ok) {
            throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
        }

        // Parse the response to extract the token and its expiration
        const data = await response.json();

        // Cache the token and calculate its expiration time
        const expiresIn = data.expires_in || 7200; // 2 hour limit
        tokenCache.accessToken = `Bearer ${data.access_token}`;
        tokenCache.expiresAt = Date.now() + expiresIn * 1000; // Convert expires_in to milliseconds

        // Logs the newly cached token and its expiration time to the console for debugging
        console.log("Caching new token:", tokenCache);
        return tokenCache.accessToken;

    } catch (err) {
        // Handle errors during the token request
        console.error("Error retrieving token:", err.message);
        throw err;
    }
}