API

Version Update

22R2

The Network API is updated to v27.0.

The Network API version is updated for every major release. Any additional changes are documented in this section of the Release Notes.

As with all version updates, Integration Users should continue to use v26.0 until there is a change for v27.0 that they want to apply.

For more information about the Network API, see the Veeva Network API Reference at http://developer.veevanetwork.com.

API updates for hashtags

22R2

The following updates are supported for Network API v25 and later.

Search and Retrieve API

A new value is added to the following parameter to display hashtags that are specific to Veeva CRM.

Parameter

Parameter Name Value
returnHashtagsForType CRM

Response

Hashtags that meet the following conditions are returned:

  • Record meets hashtag rule criteria

  • Hashtag is active

  • Hashtag is available in Veeva CRM.

Supplemental results

The returnHashtagsForType parameter supports hashtags for the supplemental parameter. The supplemental parameter returns related parent HCOs of the entities found in the supplemental results. If you use the supplemental parameter with the ALL or ONE value, the hashtags automatically display in the entity block.

Example response

"supplementalResults": [
    {
      "specialty_1__v": "PD",
      "specialty_1__v_value__u": "Pediatrics",
      "hco_type__v": "4:4",
      "hco_type__v_value__u": "Organization, Group Practice",
      "340B_eligible__v": "N",
      "340B_eligible__v_value__u": "No/False",
      "master_vid__v": "242977361002234881",
      "record_owner_type__v": "VOD",
      "record_owner_type__v_value__u": "OpenData",
      "lab_services__v": "U",
      "lab_services__v_value__u": "Unknown/No response",
      "hco_status__v": "A",
      "hco_status__v_value__u": "Active",
      "accept_medicare__v": "U",
      "accept_medicare__v_value__u": "Unknown/No response",
      "specialty_3__v": "PM",
      "specialty_3__v_value__u": "Physical Medicine & Rehabilitation",
      "count_all_locn_medstaff__v": 0,
 .....
      ],
      "hashtags": [
        {
          "name": "#groupPractice",
          "color": "gray",
          "tooltip": "HCO is a group practice",
          "tooltipLabel": null,
          "tooltipValue": null,
          "tooltipHasOtherValue": false
        },
        {
          "name": "#pediatrics",
          "color": "gray",
          "tooltip": "Record specializes in pediatrics",
          "tooltipLabel": null,
          "tooltipValue": null,
          "tooltipHasOtherValue": false
        }
      ],
      "account_link_set__v": [],
      "licenses__v": [],
      "parent_hcos__v": []
    }
  ]
}

Match rule collections

22R1.1

Administrators can create match rule collections to use in the Match API. The Network Match API was introduced in version 21R3.0 to enable you to match data immediately for a single record. This is helpful when you need to verify data in real-time, for example, when you are registering HCPs in a portal. You can match the data using an API call instead of trying to verify the data using Network Search which requires multiple searches, filtering, and field queries.

By default, the Match API uses the country default match rules for your Network instance. Now you can create and use match rule collections that contain country groups that share custom match rules and data groups. Match rule collections are independent of subscriptions and other Network processes, so you can customize them for specific purposes.

This feature is enabled by default for your Network instance.

Match API

A new parameter enables Integration users to use custom match rules in the Match API to match data immediately for a single record.

Parameter

  • matchRuleCollection - The name of the match rule collection to be used for matching.

    This is an optional parameter. If it is not specified, the country default match rules are used.

Response

The response includes the following:

  • matchSetup - Information about the match configuration used.

Example response

{
  "status": "SUCCESS",
  "matchSetup": {
    "country": "US",
    "entity": "HCP",
    "dataGroups": [
        {
            "instance" : 20301
            "first_name__v=james & is_externally_mastered__v!=true & primary_country__v=us": 1000,
            "first_name__v=james & is_externally_mastered__v!=true & last_name__v=johnson & primary_country__v=us": 345,
            "addresses__v.locality__v=new york & is_externally_mastered__v!=true & last_name__v=johnson & primary_country__v=us": 235,
            "addresses__v.locality__v=new york & is_externally_mastered__v!=true & primary_country__v=us": 1000,
            "addresses__v.locality__v=new york & addresses__v.postal_code_primary__v=10027 & is_externally_mastered__v!=true & primary_country__v=us": 1000,
            "is_externally_mastered__v!=true & npi_num__v=1962593913 & primary_country__v=us": 1
        },
        {
            "instance" : 301
            "first_name__v=james & is_externally_mastered__v!=true & primary_country__v=us": 1000,
            "first_name__v=james & is_externally_mastered__v!=true & last_name__v=johnson & primary_country__v=us": 1000,
            "addresses__v.locality__v=new york & is_externally_mastered__v!=true & last_name__v=johnson & primary_country__v=us": 1000,
            "addresses__v.locality__v=new york & is_externally_mastered__v!=true & primary_country__v=us": 1000,
            "addresses__v.locality__v=new york & addresses__v.postal_code_primary__v=10027 & is_externally_mastered__v!=true & primary_country__v=us": 1000,
            "is_externally_mastered__v!=true & npi_num__v=1962593913 & primary_country__v=us": 1
        }
    ]
    "includeMasterResults": true,
    "addressCleansing": true,
    "matchRuleCollection": "verteoMatch"
  },
  ...
}

Errors

The responseStatus returns a FAILURE message if the Match API request is submitted with an invalid matchRuleCollection.

Creating match rule collections

Administrators can create custom match rules to use in the Match API.

In the Admin console, a new tab called Match Rule Collections displays in the System Interfaces menu.

This page displays the match rule collections that you have created in your Network instance.

Each row contains the following details:

  • Collection Name - The name and description.

  • Countries - The countries in all of the country groups defined in the collection.

  • Entities with Custom Rules - The objects that have custom rules defined. Objects in the collection that use the default match rules do not display in this column.

Each collection contains custom match rules and data groups for country groups.

To create a match rule collection:

  1. In the Admin console, click System Interfaces > Match Rule Collections.

  2. On the Match Rule Collections page, click Add Collection.

  3. In the Details section, define a Name and Description.

    The name must be unique. Letters, numbers, and underscore (_) characters are supported for the name.

  4. Click Create Collection to save it. The collection must be saved before you can add country groups.

  5. Click Add Country Group . Match collection rules are specific to country groups. Country groups are countries that use the same match rules and data groups.

  6. On the New Country Group page, define the following:

    • Country Group Name - The name of the group.

    • Countries - Add the countries that apply to this group. A country can belong in one country group for each match rule collection.

  7. In the Match Rules and Data Groups section, select the entity that will use custom match rules and data groups. For example, click Health Care Professional.

  8. Beside Match Configuration, the option Use country default rules is defined by default. Click View Rules to see a read-only preview of the current default rules.

    If the country group contains multiple countries, use the Country list to see each country's default rules.

    These are the rules that are currently the default for your Network instance for the country (the rules in the Match Default Configuration). They are not necessarily the default rules that Network provided when you received your Network instance. If you have made any changes to those rules, those changes are considered the default rules for your Network instance now.

  9. Choose Customize rules to start defining the custom match rules.

  10. On the Load Country Template pop-up, select a country from the list. The default rules for the selected country will be used as a starting point for the custom match rules. The countries that are defined for the country group are available in the list.

    The template (country default match rules) that you choose will be applied to each object in the country group if you customize rules for other objects.

    Note: After you save the country group, the template cannot be changed and the country cannot be removed from the country group.

    Click Preview to open and review a read-only version of the default match rules and data groups for that country. Close the pop-up and click Continue.

  11. The Match Rules and Data Groups tabs display. Customize the match rules and data groups for the selected object. For example, if you want the match collection to match by IDs only, you might disable all of the match rules that are not for IDs.

    By default, Basic mode is selected for HCPs and HCOs. You can edit the rules in Basic or Advanced mode. Only Advanced mode is supported for custom objects.

    Notice that the Custom Rules label displays below the selected object. Also, the country group is updated to display country that the Base Template uses.

  12. Save the country group.

    Note: If you have customized rules for an object, after the match rule collection is saved, the entities cannot be set back to use Default Rules.

    Considerations

    • To save the country group, at least one object must have custom rules defined. If all of the objects in the match rule collection are set to use default rules, a message displays: No changes in match rules detected. Please customize an entity's match rules before saving a country group.

    • If the country group contains multiple countries and you customize a rule for an object but there isn't a rule for that object in one of the countries, a message displays: At least one field is not available or not enabled in this country. For example, if you use the default match rules for Mexico as your template and there isn't a rule for that object for Brazil, the message displays. The rule must be removed before the country group can be saved.

  13. Optional Add more country groups to the match rule collection.

  14. Save the match rule collection.

Edit country groups

Country groups can be edited or deleted.

  • Add or remove countries to the country group.

    When you save the country group, a pop-up displays. Click Change to confirm that you want to update the country group. Network validates the features, feature sets, and data groups to update the fields used in the rules.

Delete country groups

You can delete a country group from the match group selection. If you delete a country group, the default match rules for the countries in the group will apply. A message displays to confirm that you want to delete the group.