This guide is intended to provide instructions on how to interact with and use the VALD External Tenants API.
The External Tenants API can be utilised to access tenant, category and group information for your available tenants.
- Identify your region
- Scenario 1: Retrieve list of all tenants
- Scenario 2: Retrieve details of a single tenant
- Scenario 3: Retrieve list of tenant's categories and groups
- Scenario 4: Create or update a category
- Scenario 5: Create or update a group
- Scenario 6: Replace the profiles in a group
- Scenario 7: Remove profiles from a group
- Scenario 8: Delete a group on a tenant
- Scenario 9: Reset synchronization status of all categories, groups and profiles on a tenant
Identify your region
The endpoint you use to interact with the External Tenants 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-externaltenants.valdperformance.com/swagger/index.html |
| United States (East) |
| https://prd-use-api-externaltenants.valdperformance.com/swagger/index.html |
| Europe (West) |
| https://prd-euw-api-externaltenants.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 list of all tenants
In this scenario, we will retrieve all tenants that your API Client has access to.
Instructions
- Retrieve data using
/tenantsfor your region. - Store tenants list locally taking note of the retrieved data region.
- Iterate through all remaining VALD data regions.
HTTP Method
GET
URL
/tenants
Path Parameters
None
Query Parameters
None
Response
The response will contain a list of tenants with the following properties.
| Property | Description |
| id | VALD's unique ID for the tenant. |
| name | VALD's friendly name for the tenant. |
Scenario 2: Retrieve details of a single tenant
In this scenario, we will retrieve details about a specified tenant.
HTTP Method
GET
URL
/tenants/{tenantId}
Path Parameters
None
Query Parameters
| Query Parameter | Description |
| tenantId | VALD's unique ID for the tenant. |
Response
The response will contain the following details about a tenant.
| Property | Description |
| id | VALD's unique ID for the tenant. |
| name | VALD's friendly name for the tenant. |
| sport | Primary sport or industry the tenant operates within. |
| league | Primary sporting league or industry category the tenant operates within. |
| logoUri | Logo uploaded by the client to represent their tenant. |
Scenario 3: Retrieve list of tenant's categories and groups
Tenants can segment their profiles in VALD using a combination of Categories and Groups. Groups have a many-to-one relationship with Categories.
In this scenario, we will retrieve a list of Categories and Groups for a specified tenant.
Retrieve categories
HTTP Method
GET
URL
/categories
Path Parameters
None
Query Parameters
| Query Parameter | Description |
| tenantId | VALD's unique ID for the tenant. |
Response
The response will contain the following details about a tenant.
| Property | Description |
| id | Tenant's unique ID for the category. |
| name | Tenant's friendly name for the category. |
| syncId | ID supplied by the API client when adding categories via the import endpoint. This is unique within a VALD tenant. |
Retrieve groups
HTTP Method
GET
URL
/groups
Path Parameters
None
Query Parameters
| Query Parameter | Description |
| tenantId | VALD's unique ID for the tenant. |
Groups response
The response will contain the following details about a tenant.
| Property | Description |
| id | Tenant's unique ID for the group. |
| name | Tenant's friendly name for the group. |
| categoryId | ID of the groups parent category. |
| syncId | ID supplied by the API client when adding groups via the import endpoint. This is unique within a VALD tenant. |
Scenario 4: Create or update a category
In this scenario, we will import a category into a VALD tenant to create or update an existing record.
HTTP Method
POST
URL
/categories/import
Path Parameters
None
Query Parameters
None
Request Body Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant for which the category will be created or updated. |
| syncId | True | ID supplied by the API client when adding categories via the import endpoint. This is unique within a VALD tenant. |
| name | True | Name of the category. |
Scenario 5: Create or update a group
In this scenario, we will import a group into a VALD tenant to create or update an existing record.
HTTP Method
POST
URL
/groups/import
Path Parameters
None
Query Parameters
None
Request Body Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant for which the group will be created or updated. |
| syncId | True | ID supplied by the API client when adding groups via the import endpoint. This is unique within a VALD tenant. |
| categoryId | True | ID of the category for which the group will be created or updated. |
| name | True | Name of the group. |
Scenario 6: Replace the profiles in a group
In this scenario, we will import a list of profile ids that belong to a group into a VALD tenant.
HTTP Method
PUT
URL
/groups/profiles
Path Parameters
None
Query Parameters
None
Request Body Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant for which the group and profiles belong. |
| groupId | True | ID of the group for which the profiles will be added or removed. |
| profileIds | True |
List of IDs for the profiles in the group. Profiles that currently exist in the group but have not been included in this list will be removed from the group. |
Scenario 7: Remove profiles from a group
In this scenario, we will remove profiles from a group.
See our guide on the External Profiles API for more information about retrieving profile data.
HTTP Method
DELETE
URL
/groups/profiles
Path Parameters
None.
Query Parameters
None.
Request Body Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant the group and profiles belong to. |
| groupId | True | ID of the group the profiles will be removed from. |
| profileIds | False |
List of profile IDs to be removed from the group. If not supplied, all profiles will be removed from the group. |
Response
None
Scenario 8: Delete a group on a tenant
In this scenario, we will remove all profile membership from a group and then delete the group.
HTTP Method
DELETE
URL
/groups/{groupId}
Path Parameters
| Parameter | Required | Description |
| groupId | True |
ID of the group that you are wanting to remove all profiles and then delete the group. Profile group membership will be updated, however, the profiles will not be deleted from the tenant. |
Query Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant for which the group belongs. |
Request Body Parameters
None
Scenario 9: Reset synchronization status of all categories, groups and profiles on a tenant
In this scenario, we will reset the SyncId on all existing categories, groups, and profiles to ensure any previous integrations the client has applied will not cause issues with your integration when importing new categories, groups, and profiles.
HTTP Method
DELETE
URL
/tenants/{tenantId}/syncids
Path Parameters
| Parameter | Required | Description |
| tenantId | True |
ID of the tenant for which the syncIds should be reset for all categories, groups, and profiles. |
Query Parameters
None
Request Body Parameters
None
Comments
0 comments
Please sign in to leave a comment.