This guide is intended as a resource to provide contextual instructions on how to interact with and use the VALD External Profiles API.
For details on specific endpoints and schemas, please refer to the Swagger UI documentation (see link specific to your region below).
The External Profiles API can be utilized to both retrieve and write a tenant's profiles.
Jump to:
- Identify your region
- Notable properties
- Scenario 1: Retrieve list of tenant's profiles
- Scenario 2: Create or update a profile
- Scenario 3: Reset synchronization status of all profiles on a tenant
- Scenario 4: Merge profiles
- Scenario 5: Add profile to group/s – POST method
- Scenario 6: Replace (add and remove) groups on a profile – PUT method
- Scenario 7: Remove groups from a profile
Identify your region
The endpoint you use to interact with the External Profiles 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-externalprofile.valdperformance.com/swagger |
| United States (East) |
| https://prd-use-api-externalprofile.valdperformance.com/swagger |
| Europe (West) |
| https://prd-euw-api-externalprofile.valdperformance.com/swagger |
If you are unsure which region-specific URL you should be using, please contact support@vald.com.
Notable properties
| Property | Description |
| profileId | VALD's primary key for the profile. This is unique within a VALD tenant. |
| syncId | Your organization's primary key for the profile, supplied by you when adding profiles via the import endpoint. This is unique within a VALD tenant. |
| externalId | Any additional miscellaneous ID supplied by you as an external reference on a profile. There are no unique constraints on this property. |
| Email address of the profile. This is not 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
| 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 | VALD's primary key for the profile. This is unique within a VALD tenant. |
| syncId | Your organization's primary key for the profile, supplied by you 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 | Profile's date of birth with ISO 8601 date/time format in UTC (i.e. YYYY-MM-DDT00:00:00.000Z). |
| externalId | Any additional miscellaneous ID supplied by you as an external reference on a profile. There are no unique constraints on this property. |
| beingMergedWithProfileId |
ID of the other profile, this profile (profileId), is being merged into. This parameter is only relevant to identify profiles undergoing a merge: refer to Scenario 4 below. It will be null if there is no merge currently taking place for this profile. |
| beingMergedWithProfileExpiryDateUtc |
Date/time at which the merge event for the profile will expire, with ISO 8601 date/time format in UTC (i.e. YYYY-MM-DDT00:00:00.000Z). Indicates that the profile will be deleted after this date/time. This parameter is only relevant to identify profiles undergoing a merge: refer to Scenario 4 below. It will be null if there is no merge currently taking place for this profile. |
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. The following matching rules will be applied in order:
-
SyncId matches
- An active profile already exists with the provided SyncId. This profile is updated.
- A previously deleted profile exists with the provided SyncId. This profile is undeleted and updated.
-
Given Name, Family Name, Date of Birth, and Email matches (no SyncId)
- An active profile already exists with the provided Given Name, Family Name, Date of Birth, and Email and does not have a SyncId. This profile is updated and SyncId is set.
- A previously deleted profile exists with the provided Given Name, Family Name, Date of Birth, and Email and does not have a SyncId. This profile is undeleted, updated and SyncId is set
-
Given Name, Family Name, and Date of Birth matches (no SyncId)
- An active 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.
- A previously deleted profile exists with the provided Given Name, Family Name and Date of Birth and does not have a SyncId. This profile is undeleted, updated and SyncId is set.
-
No matches based on SyncId or Given Name, Family Name, Date of Birth, and/or Email
- No existing or previously deleted profiles match based on the above criteria. A new profile is created and the SyncId is set.
Read me: More on profile matching
→ Matches with SyncId (regardless of the status of the profile – active or deleted) always take priority over matches with Given Name, Family Name, Date of Birth, and Email of an active profile.
→ VALD profiles can be merged (i.e., Profile A merged into Profile B) either manually in VALD Hub, or via API: see Scenario 4 below. In this instance, the profile being merged (A) remains active in the VALD database for three days; the profile it is being merged to (B) is recorded as metadata. Within this timeframe and in the absence of SyncId, if a match is found to the profile which is being merged (A), then the match will be transferred to the profile it is being merged to (B). This will result in Profile B being updated and the SyncId being set. After this timeframe, Profile A is considered to be 'deleted' and all other matching rules apply normally.
→ An email is not unique within a tenant, so profile matching based on email only will not occur. In such cases, a new profile will be created.
→ When a profile match is identified, the information provided in the request will overwrite the existing information for that profile. Specifically, if you do not wish for the email and ExternalId to be overwritten during the process of profile matching, make those parameters null in the request body.
HTTP Method
POST
URL
/profiles/import
Path Parameters
None
Query Parameters
None
Body Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant for which the profile will be created or updated. |
| syncId | True | Your organization's primary key for the profile, supplied by you 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 | Profile's date of birth with ISO 8601 date/time format in UTC (i.e. YYYY-MM-DDT00:00:00.000Z). |
| False | Email address of the profile. This is not unique within a VALD tenant. | |
| sex | True | Sex of the profile. |
| externalId | False | Any additional miscellaneous ID supplied by you 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 whether the creator of the profile is over the age of 18 to comply with the Children's Online Privacy Protection Act (COPPA). |
| isGuardianConsentGiven | False | Where a profile is under 18 years old, this indicates whether the parent or guardian has consented to data collection by VALD. |
| isPhotoVideoConsentGiven | False | This indicates whether the individual or their parent/guardian has consented to photo and video data collection by VALD. |
Response
None.
Scenario 3: Reset synchronization status of all profiles in a tenant
In this scenario, we will reset the SyncIds on all existing profiles to ensure any previous integrations the client has applied will not cause issues with the current integration when importing profiles.
Note: It is recommended to use the DELETE /tenants/{tenantId}/syncids endpoint on our External Tenants API. This resets SyncIds for all existing categories, groups and profiles.
HTTP Method
DELETE
URL
/profiles/syncids
Path Parameters
None
Query Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant in which the syncIds should be reset for all profiles. |
Body Parameters
None
Response
None
Scenario 4: Merge profiles
In this scenario, we will merge two profiles (i.e., Profile A into Profile B, where A is the 'from' profile and B is the 'to' profile). Once a merge is triggered, the profile being merged (A) remains active in the VALD database for three days; the profile it is being merged to (B) is recorded as metadata.
See Scenario 1 above to identify profiles currently undergoing a merge.
HTTP Method
POST
URL
/profiles/merge
Path Parameters
None
Query Parameters
None
Body Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant the profiles belong to. |
| fromProfileId | True | ID of the profile to be merged. |
| toProfileId | True | ID of the profile being merged into. |
Response
None
Scenario 5: Add profile to group/s – POST method
In this scenario, we will add a profile to one or more existing groups. The existing group assignments will be maintained.
See the External Tenants API guide for more information on retrieving group data.
HTTP Method
POST
URL
/profiles/groups
Path Parameters
None
Query Parameters
None
Body Parameters
| 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 to. If the profile is already assigned to existing groupIds not included in the list, these will not be affected. |
Response
None
Scenario 6: Replace (add and remove) groups on a profile – PUT method
In this scenario, we will replace – add and remove – the groups on a profile.
Note: This endpoint will completely replace any existing group assignments for the profile. If you only wish to add a profile to an existing group while maintaining existing assignments, the POST endpoint is more suitable: see the instructions detailed in Scenario 5. Alternatively, make sure to also list existing groups in the request body.
See the External Tenants API guide for more information on retrieving group data.
HTTP Method
PUT
URL
/profiles/groups
Path Parameters
None
Query Parameters
None
Body Parameters
| 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 | False |
List of IDs for the groups the profile is assigned to. Groups that the profile is currently assigned to which are not included in this list will be removed from the profile. |
Response
None
Scenario 7: Remove groups from a profile
In this scenario, we will remove groups from a profile.
See the External Tenants API guide for more information on retrieving group data.
HTTP Method
DELETE
URL
/profiles/groups
Path Parameters
None
Query Parameters
None
Body Parameters
| Parameter | Required | Description |
| tenantId | True | ID of the tenant the profile and groups belong to. |
| profileId | True | ID of the profile the groups will be removed from. |
| groupIds | False |
List of group IDs to be removed from the profile. If not supplied, all groups will be removed from the profile. |
Response
None
Comments
0 comments
Please sign in to leave a comment.