This guide is intended to provide instructions on how to interact with and use the VALD External Profiles API.
The External Profiles API can be utilised to both retrieve and write a tenant's profiles.
- Identify your region
- Notable properties
- Scenario 1: Retrieve list of tenant's profiles
- Scenario 2: Create or update a profile
- Scenario 3: Reset synchronisation status of all profiles on a tenant
- Scenario 4: Add Profile to a Group
Identify your region
The endpoint you use to interact with the External Profiles 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-externalprofile.valdperformance.com/swagger/index.html |
| United States (East) |
| https://prd-use-api-externalprofile.valdperformance.com/swagger/index.html |
| Europe (West) |
| https://prd-euw-api-externalprofile.valdperformance.com/swagger/index.html |
If you are unsure which region-specific URL you should be using, please contact support@vald.com.
Notable properties
| Property | Description |
| profileId | ID of the profile. This is unique within a VALD tenant. |
| syncId | ID supplied by API client when adding profiles via the import endpoint. This is unique within a VALD tenant. |
| externalId | Any additional miscellaneous ID supplied by a user as an external reference on a profile. There are no unique constraints on this property. |
| Email address of the profile. This is unique within a VALD tenant. | |
| groupId | ID of the group a profile is a member of. Profiles may belong to multiple groups at once. |
Scenario 1: Retrieve list of tenant's profiles
In this scenario, we will retrieve a list of profiles for a specified tenant.
HTTP Method
GET
URL
/profiles
Path Parameters
None
Query Parameters
| Query Parameter | Required | Description |
| tenantId | True | ID of the tenant from which to retrieve profiles. |
| profileIds | False | List of IDs for the profiles you wish to retrieve. |
| syncId | False | Sync ID of the profile you wish to retrieve. |
| externalId | False | External ID of the profile you wish to retrieve. |
| groupId | False | ID of a group the profile is a member of. |
Response
The response will contain a list of profiles with the following properties.
| Property | Description |
| profileId | ID of the profile. This is unique within a VALD tenant. |
| syncId | ID supplied by API client when adding profiles via the import endpoint. This is unique within a VALD tenant. |
| givenName | Profile's given name. |
| familyName | Profile's family name. |
| dateOfBirth | Profiles date of birth in format YYYY-MM-DDT00:00:00.000Z. |
| externalId | ID supplied by user as an external reference on a profile. There are no unique constraints on this property. |
Scenario 2: Create or update a profile
In this scenario, we will import a profile into a VALD tenant to create or update an existing record.
Profile matching
When importing a profile, matching occurs to ensure the correct profile is updated and duplicates are not created. There are four possible scenarios:
- Profile already exists with the provided SyncId. This profile will be updated.
- Profile already exists with the provided email and does not have a SyncId. This profile is updated and SyncId is set.
- Profile already exists with the provided Given Name, Family Name and Date of Birth and does not have a SyncId. This profile is updated and SyncId is set.
- No existing profiles that match based on the above criteria. A new profile is created and the SyncId is set.
HTTP Method
POST
URL
/profiles/import
Path Parameters
None
Query Parameters
None
Request Body Parameters
| Query Parameter | Required | Description |
| tenantId | True | ID of the tenant for which the profile will be created or updated. |
| syncId | True | ID supplied by API client when adding profiles via the import endpoint. This is unique within a VALD tenant. |
| givenName | True | Profile's given name. |
| familyName | True | Profile's family name. |
| dateOfBirth | True | Profiles date of birth in format YYYY-MM-DDT00:00:00.000Z. |
| True | Email address of the profile. This is unique within a VALD tenant. | |
| sex | True | Sex of the profile. |
| externalId | False | ID supplied by user as an external reference on a profile. There are no unique constraints on this property. |
| isCreatedByUserOver18YearsOld | False | Where a profile is under 13 years old, this indicates if the person who created the profile is over the age of 18 to adhere with the Children's Online Privacy Protection Act (COPPA). |
| isGuardianConsentGiven | False | Where a profile is under 18 years old, this indicates if their parent or guardian has consented to data collection by VALD. |
| isPhotoVideoConsentGiven | False | This indicates if the individual or their parent/guardian has consented to photo and video data collection by VALD. |
Response
None.
Scenario 3: Reset synchronisation status of all profiles on a tenant
In this scenario, we will reset the SyncId of all existing profiles to ensure any previous integrations the client has applied will not cause issues with your integration when importing profiles.
HTTP Method
DELETE
URL
/tenants/{tenantId}/syncids
Path Parameters
| Query Parameter | Required | Description |
| tenantId | True | ID of the tenant for which the syncIds should be reset for all profiles. |
Query Parameters
None
Request Body Parameters
None
Response
None
Scenario 4: Add Profile to Group
In this scenario, we will add a profile to an existing group.
See our guide on the External Tenants API for more information about retrieving group data.
HTTP Method
PUT
URL
/profiles/groups
Path Parameters
None
Query Parameters
None
Request Body Parameters
| Query Parameter | Required | Description |
| tenantId | True | ID of the tenant the profile belongs to. |
| profileId | True | ID of the profile you wish to add to a group. |
| groupIds | True |
List of Ids for the groups the profile is assigned. Profiles that currently exist in the group but have not been included in this list will be removed from the group. |
Response
None
Comments
0 comments
Please sign in to leave a comment.