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.

Looking for a beginner-friendly way to integrate with our external APIs? Check out our guide on using the valdr R package.

Requesting API access

Send access request email

Email support@vald.com requesting access to our external APIs. In your email, include your organization ID acquired via VALD Hub.

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.

Obtain API credentials

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

The link containing your API credentials will expire in seven days.

Best practices for storing API credentials

You should always treat your API credentials as sensitive information.

To keep your API credentials 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.

Getting started with VALD 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.

Find 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 VALD 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 API credentials confidential.

Step-by-step guide for initial requests

In this example we will use the External Tenants API via Swagger 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 under the Auth0 section to authenticate your access.
      Note: See API Updates – March 2026 for details on changes to API authentication.
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.

1. Ensure proper authentication.
   To send and/or retrieve data from VALD, you must request an access token which is valid for several hours. This is done through a server-side API call to VALD's Identity Server – the exact token expiry will be provided in the response.
   • When transitioning from testing in Swagger to production-ready scripts, you must ensure that your scripts remain authenticated for the duration of their execution.
   • Rate limits apply on authentication requests, meaning you must cache and reuse your access token until it expires before requesting a new one.

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.

 Example code

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;
    }

    // URL for the authentication endpoint
    const url = "https://auth.prd.vald.com/oauth/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: "client_credentials",
                client_id: clientId,    // Include the client ID in the request body
                client_secret: clientSecret  // Include the client secret in the request body
                audience: "vald-api-external"
            }).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
        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;
    }
}

2. 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.
3. 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.