This guide is intended as a resource to provide contextual instructions on how to interact with and use the VALD External Tenants API.
For details on specific endpoints and schemas, please refer to the Swagger UI documentation (see link specific to your region below).
The External Tenants API can be utilized to access tenant, category and group information for your available tenants.
Jump to:
- 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 dependent 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 |
| United States (East) |
| https://prd-use-api-externaltenants.valdperformance.com/swagger |
| Europe (West) |
| https://prd-euw-api-externaltenants.valdperformance.com/swagger |
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
| Parameter | Description |
| tenantId | VALD's unique ID for the tenant. |
Query Parameters
None
Response
The response will contain the following details.
| 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
| Parameter | Description |
| tenantId | VALD's unique ID for the category. |
Response
The response will contain the following details.
| Property | Description |
| id | VALD's unique ID for the category. |
| name | VALD's friendly name for the category. |
| syncId | Your primary key, an ID supplied by you 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
| Parameter | Required | Description |
| tenantId | True | VALD's unique ID for the tenant. |
| syncId | False | Sync ID of the group you wish to retrieve. |
Response
The response will contain the following details.
| Property | Description |
| id | VALD's unique ID for the group. |
| name | VALD's friendly name for the group. |
| categoryId | ID of this group's parent category. |
| syncId | Your primary key, an ID supplied by you 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
Body Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant for which the category will be created or updated. |
| syncId | True | Your primary key, an ID supplied by you 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
Body Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant for which the group will be created or updated. |
| syncId | True | Your primary key, an ID supplied by you 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 (add and remove) 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
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.
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 in 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 from which to remove all profiles and then delete the group. Profile group membership will be updated, but the profiles will not be deleted from the tenant. |
Query Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant to which the group belongs. |
Body Parameters
None
Scenario 9: Reset synchronization status of all categories, groups and profiles in a tenant
In this scenario, we will reset the SyncIds on all existing categories, groups and profiles. This ensures 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 in which the syncIds should be reset on all categories, groups and profiles. |
Query Parameters
None
Body Parameters
None
Comments
0 comments
Please sign in to leave a comment.