Suspect match API call

Using an API call, suspect match tasks can be created through customer web portals. Some customers have web portals that enable HCPs to log in to find information about products, events, and so on. If HCPs find duplicate records of themselves, they can now request that the records be merged by submitting a suspect match task using the Network entity IDs of the records. Customer web portals do not recognize ownership of records, so Network ensures that the suspect match requests are routed to the appropriate data stewards (local or Veeva OpenData).

Integration users have access to the Network API.

Creating a suspect match API call

Customer web portals submit suspect match API calls using the Network integration user credentials. Users can only create suspect match tasks on records that they have visibility to through their data visibility profiles. When the API is created, only the surviving and merged entity IDs of records can be defined. The API call contains the following fields:

creator - The name of the user who is generating the request
vid_key - The entity ID of the record to be merged; the losing record.
matching_vid_key - The entity ID of the surviving record.
note - (optional) Details about the request.
source - (optional) Additional information about the request.

For more information about the API call, see the "Batch Create Suspect Match" section below.

Suspect match request routing

Customer web portals do not recognize ownership of records. Network automatically routes suspect match tasks to the appropriate data stewards. If any of the records in the request are customer-owned, the suspect match request is routed to local data stewards.

Original Entity	Matched Entity	Suspect Match Task Routing
Customer	Customer	Customer data stewards
Customer	Veeva OpenData	Customer data stewards
Customer	Third party master	Customer data stewards
Veeva OpenData	Customer	Customer data stewards OpenData record always wins.
Third party master	Customer	Customer data stewards Mastered record always wins.
Veeva OpenData	Veeva OpenData	Veeva OpenData data stewards
Third party master	Third party master	Suspect match task is not supported. The request is automatically rejected.
Third party master	Veeva OpenData	Suspect match task is not supported. The request is automatically rejected.

Note: If the task contains a master record (Veeva OpenData or third party master) as the matched entity and a customer-owned record as the original entity, Network automatically flips the records so the master record always survives.

Suspect match tasks are auto-rejected when the API call includes the following records:

Two third party records - Third party mastered entities cannot be merged.
Third party record and a Veeva OpenData record - Records from different mastered sources cannot be merged.
Records with different entity types (for example, HCO - HCP).
A record that is already a merged_into record
A record that the user does not have visibility to through their data visibility profile permissions. For example, if the integration user does not have visibility to the HCP type nurse, a record of that type cannot be included in the suspect match request.

Stewarding suspect match tasks from the API

Suspect match tasks that are requested from the API look the same as suspect match tasks that are created in the Network UI. Data stewards and data managers will only notice that the Creator of the task, in the Task Details section, is the customer's integration user.

Batch Create Suspect Match

The Batch Create Suspect Match API enables users to create multiple suspect matches through the API. It is supported in v15 of the Network API.

This API uses the POST HTTP method.

Syntax

https://{dns}/api/{version}/entity/createSuspectMatch/batch

where:

{dns} = The URL for the customer's API service.
{version} = The API version.

Parameters

None.

POST data

vid_key (required) - The Network entity ID (VID) of the entity to be merged; the losing record.

matching_vid_key (required) - The Network entity ID (VID) of the entity to match; the surviving record.

metadata (required) - Details about the request.

creator (required) - The name of the user that generated the request.
note (optional) - Extra details about the change request.
source (optional) - Extra information about the source of the change request.

Sample request

POST https://my.veevanetwork.com/api/v15.0/entity/createSuspectMatch/batch

Response

responseStatus - The status of the automatic response generated by Network upon receiving the request.

suspect_matches - An array of suspect matches that correspond to the same objects in the request. Each suspect match has the following properties:

suspect_match_id - The ID of a created suspect match.

Sample response

{
"suspect_matches": [{
"metadata": {
"note": "Duplicate HCO - Orange to Grey",
"creator": "API.user@sample.com"
},
"vid_key": "Network:Entity:260904728014095360",
"matching_vid_key": "Network:Entity:615369811198841858"
}
]
}

Notes

responseStatus returns a failure if any standard errors occur or in the following situations:

{vid_key} does not represent an existing entity.
The entity represented by {vid_key} is not in "VALID" state.
The type of the entity (for example, HCP) doesn't match with the type of the request (for example, HCO).
Two third party records are provided in the request.
One third party and one Veeva OpenData record is provided in the request.
The integration user does not have visibility to the provided records.

Batch Retrieve Suspect Match

The Batch Retrieve Suspect Match API enables users to obtain information about multiple suspect matches through the API. It is supported in v15 of the Network API.

This API uses the POST HTTP method.

Syntax

https://{dns}/api/{version}/suspect_match/batch

where:

{dns} = The URL for customer's API service.
{version} = The API version.

Parameters

None.

POST data

vid_key (required) - The Network entity ID (VID) of the entity to be merged.

matching_vid_key (required) - The Network entity ID (VID) of the entity to match.

metadata (required) - Details about the request.

creator (required) - The name of the user that generated the request.
note (optional) - Extra details about the change request.
source (optional) - Extra information about the source of the change request.

Sample request

POST https://my.veevanetwork.com/api/v15.0/suspectmatch/batch

Response

responseStatus - The status of the automatic response generated by Network upon receiving the request.

suspect_matches - An array of suspect matches that correspond to the same objects in the request. Each suspect match has the following properties:

id - The ID of the retrieved suspect match task.
resolution_note - The notes added for the suspect match task.
created_date - The date the task was created.
completed_date - The date the task was completed.
resolution - The resolution of the task.
state - The state of the task.
suspect_match_results - The result of the suspect match showing the entity that was merged into the surviving entity.
- merge_into_vid - The Network entity ID (VID) of the entity that was merged into the surviving entity.
- surviving_entity_vid - The Network entity ID (VID) of the surviving entity.

Sample response

{
    "responseStatus": "PARTIAL_SUCCESS",
    "errors": [
        {
            "type": "INVALID_DATA",
            "message": "Suspect Match Task 931697085670096927 not found"
        },
        {
            "type": "INVALID_DATA",
            "message": "Suspect Match Task 931697013151105055 not found"
        }
    ],
    "suspect_matches": [
        {
            "id": 932218057214525503,
            "resolution": "NOT_MATCHED",
            "state": "PROCESSED",
            "created_date": "2018-04-10T11:25:43.000-07:00",
            "completed_date": "2018-04-10T11:27:31.000-07:00",
            "suspect_match_results": [
                {
                    "merge_into_vid": 847332072463795200,
                    "surviving_entity_vid": null
                }
            ]
        }
    ]
}

Notes

responseStatus returns a failure if any standard errors occur.

Suspect match API call

Creating a suspect match API call

Suspect match request routing

Stewarding suspect match tasks from the API

Batch Create Suspect Match

Syntax

Parameters

POST data

Sample request

Response

Sample response

Notes

Batch Retrieve Suspect Match

Syntax

Parameters

POST data

Sample request

Response

Sample response

Notes

Was this topic helpful?

Tell us more

Additional feedback?

Thanks, we appreciate your feedback!

Thanks, we appreciate your feedback!