searchNotifications

  • Web Services
  • API Documentation
  • Patient Journey

The searchNotifications web service is used to retrieve notification messages from Universal Identity within a specified time range. Notification messages are continually queued in Universal Identity, and you can choose how frequently they want to use the searchNotifications web service to retrieve notifications.

Note
Notification messages are not expected to be posted in real time and may result after a short delay.
  • Notification messages are generated for several different types of events. 
  • Notification messages are not deleted. You can retrieve the same notification messages again by calling the searchNotifications web service again with the same time range.
Note
Verato strongly recommends that all implementations include a searchNotifications integration. This ensures that all identity updates from Verato Universal Identity instance stay synchronized with your source systems and positions you to take advantage of feature product enhancements.

Pagination

The searchNotifications web service response uses pagination so you can control the amount of information retrieved in each web service response.

The request includes an input for pageSize, which can be any integer between 1 and 100. The request also includes an input for pageNumber, which can be any integer equal to or greater than 0. The pageNumber is a zero-based index, so the first page is pageNumber=0, the second page is pageNumber=1, and so on.

Tip
Pagination can help your manage notifications. For example, if the searchNotifications web service is called frequently (for example, every 30 minutes), each individual web service response would typically include a small number of notifications. However, if searchNotifications service is called infrequently (once per week, for example), then he number of notifications could grow very large.

Sample URL

The URL for this request is of the format https://custXXXX.verato-connect.com/link-ws/svc/searchNotifications, where XXXX is a 4-digit number.

searchNotifications JSON request

  • The request includes:

    • A tracking ID (an optional identifier that the client can supply to track the response)
    • The startDate and endDate, inclusive, that define the time range for which to retrieve notifications. The startDate and endDate format is ISO datetime format: YYYY-MM-DDThh:mm:ss. The default time zone is UTC, but the time zone can be adjusted with a modifier at the end of the datetime. The modifier is in the form of +/-hh:mm.
      For example, a request with startDate=2019-12- 06T13:44:21-05:00 is indicating that the start date is 5 hours behind UTC (5 hours behind UTC is US Eastern time zone). The searchNotifications request will fail if the start date is greater than the end date.
    • The pageSize to use for pagination. Page size value must be an integer greater than 0 and less than or equal to 100, otherwise the searchNotifications request will fail.
    • The pageNumber to use for pagination. The pageNumber is a zero-based index, so pageNumber=0 indicates the request is for the first page of notifications. The web service response indicates if there are subsequent pages, in which case you can make a subsequent searchNotifications request with pageNumber=1, and so on.
  • {
      "content": { 
        "pageNumber": integer,
        "endDate": "YYYY-MM-DDThh:mm:ss", 
        "pageSize": integer,
        "startDate": "YYYY-MM-DDThh:mm:ss"
      },
      "trackingId": "string"
    }
    

searchNotifications JSON response

  • The response includes:

    • An ‘echo’ of the same tracking ID from the request
    • Several Boolean and string values with more information about the success/failure of the service (see section 3.1 above for more information)
    • The ‘customerId’ identifier for the Universal Identity instance from which the notifications were retrieved. Clients typically have a production Universal Identity instance and one or more non- production Universal Identity instances. The ‘customerId’ is useful to confirm that you retrieved notifications from the Universal Identity instance you intended.
    • A ‘hasNext’ Boolean value to indicate whether there is a subsequent page of notification messages. When ‘hasNext’ is false, there are no additional pages of notification messages to retrieve; when ‘hasNext’ is true, there are still additional pages of notification messages to retrieve, and you should invoke searchNotifications again to retrieve the additional pages (with an incremented pageNumber).
    • A ‘totalElements’ integer which is the count of total notification messages that exist for the time range specified in the request. The ‘totalElements’ count can be higher than the ‘pageSize’ input parameter, which indicates that the notification messages will be distributed across multiple pages/responses.
    • An array of zero-to-many notification messages.
  • {
       "trackingId": "string", 
       "auditId": UUID, 
       "success": boolean, 
       "retryableError": boolean, 
       "message": "string", 
       "errors": [
         "string"
       ],
       "content": {
         "hasNext": boolean,
         "totalElements": integer, 
         "customerId": "string", 
         "notifications": [
    { "ts": integer, "service": "string", "notificationType": "string", "body": "string", "username": "string" } ] } }

Notification array entries

Each entry in the notification array includes the following information

  • TS – The timestamp of the notification message in Unix ‘epoch’ format (the number of milliseconds since 12AM, Jan. 1, 1970). For example, the “ts” value of 1574462976506 equates to Friday, November 22, 2019 10:49:36.506 PM
  • Service – The internal Universal Identity service that generated the notification message. See below for the possible values of service.
  • notificationType - this is helpful to identify the event that triggered the notification. See table below for possible values.
  • username - the username of the user whose actions triggered the event causing the notification.
  • Body – the body that contains the details of the notification message – the contents of the body will vary depending on the type of notification message. The contents of the body are JSON-within-JSON – because the contents of the “body” are part of a JSON web service response, any instances of the double-quote character within the “body” are escaped with the \ character.

Possible values and indications for service are as follows:

  • ingestionService – The overlay rejection, initial Link ID assignment, or LinkID change occurred during the ingestion of a postIdentity web service
  • linkIdentitiesService – The LinkID change occurred because the linkIdentities web service was invoked. The linkIdentities web service can be called directly, but it is also used by the Universal Identity User Interface (UI) when a user manually links identities through the UI.
  • unlinkIdentitiesService – The LinkID change occurred because the unlinkIdentities web service was invoked. The unlinkIdentities web service can be called directly, but it is also used by the UI when a user manually unlinks records through the UI.
  • mergeIdentitiesService – The LinkID change occurred because the mergeIdentities web service was invoked. The mergeIdentities web service can be called directly, but it is also used by the UI when a user manually merges records through the UI.
  • unmergeIdentitiesService – The LinkID change occurred because the unmergeIdentities web service was invoked. The unmergeIdentities web service can be called directly, but it is also used by the UI when a user manually unmerges records through the UI.
  • deleteSourceService – The LinkID change occurred because the deleteSourceIdentity web service was invoked
  • deactivateSource – The LinkID change occurred because the deactivateSourceWS web service was invoked
  • reactivateSource – The LinkID change occurred because the reactiveSourceWS web service was invoked

Service / Body values table

The following table describes the various scenarios and possible “service” and “body” values you can expect to find in the notification messages.

Scenario Service Notification Type Body

A postIdentity request is rejected because an overlay was detected. The existing attribute values for JOHN SMITH were completely updated to different values for RONALD BRAT, but the update was rejected because the updated attributes scored only 0.09 when compared to the existing values.

Note that the “body” of the notification message includes the Source + Native ID of the postedIdentity, the incoming attribute values, the existing attribute values, and the score of the match comparison between incoming and existing values.

Ingestion Service rejectedOverlay "{\"score\":0.09647058823529411,\"source\ ":\"test\",\"nativeID\":\"0001\",\"incoming\":{\"nativeId\":\"0001\",\"source\":\" test\",\"personName\":[{\"first\":\"RONALD\",\"last\":\"BRAT\"}],\"credentials\":[ {\"ssn\":\"991110011\"}],\"birthDetails\" :[{\"date\":\"1975-11- 02\"}],\"deathDetails\":[],\"physicalDescription\":[{}],\"detailedAddress\":{\"houseNumber\":\"521\",\"streetName\":\"BOARD\",\"streetType\":\"ST\",\"city\":\"REST  ON\",\"state\":\"VA\",\"zipCode\":\"22100 \"}],\"simpleAddress\":[],\"contactPhone\ ":[{}],\"contactEmail\":[{}],\"employment \":[],\"ipData\":[],\"socialNetworkingId\ ":[]}, \"existing\":{\"nativeId\":\"0001\",\"source\":\"test\",\"personName\":[{\"first\" :\"JOHN\",\"last\":\"SMITH\"}],\"credenti als\":[{\"ssn\":\"999112222\"}],\"birthDe tails\":[{\"date\":\"1980-12- 04\"}],\"deathDetails\":[],\"physicalDescription\":[],\"detailedAddress\":[{\"houseNumber\":\"123\",\"streetName\":\"MAIN\" ,\"streetType\":\"ST\",\"city\":\"MCLEAN\ ",\"state\":\"VA\",\"zipCode\":\"22102\"} ],\"simpleAddress\":[],\"contactPhone\":[ ],\"contactEmail\":[],\"employment\":[],\ "ipData\":[],\"socialNetworkingId\":[]}}"
Native id 0006, from source ‘test’, was posted for the first time and received an initial Link ID assignment. Ingestion Service

identityIngested

Note: This value will be updated soon. 

"{\"source\":\"test\",\"nativeId\":\"0006\",\"newLinkId\":\"5cf196cf59f4fc25a684c3e1\"}"
Native id 0006, from source ‘test’, has a change in assigned Link ID due to a postIdentity update – the postIdentity update included new attribute values that allowed Universal Identity to recognize a better match, resulting in a new Link ID assignment. Ingestion Service

mergeIdentities

Note: This value will be updated soon. 

"{\"source\":\"test\",\"nativeId\":\"0006\",\"previousLinkId\":\"5cf196cf59f4fc25a684c3e1\",\"newLinkId\":\"5cf198fc59f4fc25a684c3e2\"}"

An overlay associated with Native Id 0006, from source 'test' was accepted from the 'Rejected Overlays' task queue. 

 

The body of the notification contains a `resultingIdentity`  key which shows the current state of record test:0006

Ingestion Service appliedOverlay "{\"source\":\"cerner.demo\",\"nativeID\":\"0006\",\"appliedOverlay\":{\"id\":\"6378110c2491b53fe1827041\",\"nativeId\":\"0006\",\"source\":\"cerner.demo\",\"personName\":[{\"first\":\"JASON\",\"last\":\"ROGERS\"}],\"credentials\":[{\"ssn\":\"789886545\"}],\"birthDetails\":[{\"date\":\"1995-10-17\"}],\"deathDetails\":[],\"physicalDescription\":[{\"gender\":\"M\"}],\"detailedAddress\":[{\"houseNumber\":\"8380\",\"streetName\":\"GREENSBORO\",\"streetType\":\"DR\",\"city\":\"MCLEAN\",\"state\":\"VA\",\"zipCode\":\"22102\"}],\"simpleAddress\":[],\"contactEmail\":[{\"email\":\"JROGERS@GMAIL.COM\"}],\"contactPhone\":[{\"phoneCountryCode\":\"1\",\"phoneAreaCode\":\"202\",\"phoneBaseNumber\":\"2280022\"}],\"employment\":[],\"ipData\":[],\"socialNetworkingId\":[]},\"resultingIdentity\":{\"id\":\"637810bf2491b53fe1827040\",\"nativeId\":\"0006\",\"source\":\"cerner.demo\",\"personName\":[{\"first\":\"JASON\",\"last\":\"ROGERS\"},{\"first\":\"JOHN\",\"last\":\"DOE\"}],\"credentials\":[{\"ssn\":\"789886545\"}],\"birthDetails\":[{\"date\":\"1995-10-17\"}],\"deathDetails\":[],\"physicalDescription\":[{\"gender\":\"M\"}],\"detailedAddress\":[{\"houseNumber\":\"8380\",\"streetName\":\"GREENSBORO\",\"streetType\":\"DR\",\"city\":\"MCLEAN\",\"state\":\"VA\",\"zipCode\":\"22102\"}],\"simpleAddress\":[],\"contactEmail\":[{\"email\":\"JROGERS@GMAIL.COM\"}],\"contactPhone\":[{\"phoneCountryCode\":\"1\",\"phoneAreaCode\":\"202\",\"phoneBaseNumber\":\"2280022\"}],\"employment\":[],\"ipData\":[],\"socialNetworkingId\":[]}}"

A record with dummy patient data was updated with real patient data without triggering any overlay.

 

Note: See Customizing overlay detection actions section under Identity Overlay Detection and Prevention for details.

Ingestion Service dummyDataOverwritten "{\"source\":\"cerner.demo\",\"nativeID\":\"0006\",\"appliedOverlay\":{\"id\":\"6378110c2491b53fe1827041\",\"nativeId\":\"0006\",\"source\":\"cerner.demo\",\"personName\":[{\"first\":\"JASON\",\"last\":\"ROGERS\"}],\"credentials\":[{\"ssn\":\"789886545\"}],\"birthDetails\":[{\"date\":\"1995-10-17\"}],\"deathDetails\":[],\"physicalDescription\":[{\"gender\":\"M\"}],\"detailedAddress\":[{\"houseNumber\":\"8380\",\"streetName\":\"GREENSBORO\",\"streetType\":\"DR\",\"city\":\"MCLEAN\",\"state\":\"VA\",\"zipCode\":\"22102\"}],\"simpleAddress\":[],\"contactEmail\":[{\"email\":\"JROGERS@GMAIL.COM\"}],\"contactPhone\":[{\"phoneCountryCode\":\"1\",\"phoneAreaCode\":\"202\",\"phoneBaseNumber\":\"2280022\"}],\"employment\":[],\"ipData\":[],\"socialNetworkingId\":[]},\"resultingIdentity\":{\"id\":\"637810bf2491b53fe1827040\",\"nativeId\":\"0006\",\"source\":\"cerner.demo\",\"personName\":[{\"first\":\"JASON\",\"last\":\"ROGERS\"},{\"first\":\"JOHN\",\"last\":\"DOE\"}],\"credentials\":[{\"ssn\":\"789886545\"}],\"birthDetails\":[{\"date\":\"1995-10-17\"}],\"deathDetails\":[],\"physicalDescription\":[{\"gender\":\"M\"}],\"detailedAddress\":[{\"houseNumber\":\"8380\",\"streetName\":\"GREENSBORO\",\"streetType\":\"DR\",\"city\":\"MCLEAN\",\"state\":\"VA\",\"zipCode\":\"22102\"}],\"simpleAddress\":[],\"contactEmail\":[{\"email\":\"JROGERS@GMAIL.COM\"}],\"contactPhone\":[{\"phoneCountryCode\":\"1\",\"phoneAreaCode\":\"202\",\"phoneBaseNumber\":\"2280022\"}],\"employment\":[],\"ipData\":[],\"socialNetworkingId\":[]}}"
The linkIdentities web service was invoked to link native ID 0002, from source ‘test’, into a different Link ID. linkIdentitiesService linkIdentities "{\"source\":\"test\",\"nativeId\":\"0002\",\"previousLinkId\":\"5cf14a2d59f4fc25a684c3dc\",\"newLinkId\":\"5cf1484a59f4fc25a684c3db\"}"
The unlinkIdentities web service was invoked to unlink native ID 0002, from source ‘test’, out of its current Link ID into a brand new Link ID. unlinkIdentitiesService unlinkIdentities "{\"source\":\"test\",\"nativeId\":\"0002\",\"previousLinkId\":\"5cf1484a59f4fc25a684c3db\",\"newLinkId\":\"5cf1509459f4fc25a684c3df\"}"
The mergeIdentities web service was invoked to merge native ID 1003, from source ‘test’, into a different Link ID (native ID 1004). mergeIdentitiesService sourceRetired "{\"source\":\"test\",\"nativeId\":\"1003\",\"previousLinkId\":\"5dc1ed4eded58f000ec9322a\",\"newLinkId\":\"5dc1ed4dded58f000ec93229\",\"survivingSource\":\"test\",\"survivingNativeId\":\"1004\",\"retiredSource\":\"test\",\"retiredNativeId\":\"1003\"}"
The unmergeIdentities web service was invoked to unmerge native ID 1003, from source ‘test’, out of its current Link ID into a brand new Link ID. unmergeIdentitiesService sourceUnRetired "{\"source\":\"test\",\"nativeId\":\"1003\",\"previousLinkId\":\"5dc1ed4dded58f000ec93229\",\"newLinkId\":\"5dc1ed4fded58f000ec9322b\"}"
The deleteSourceIdentity web service was invoked to delete native ID 0003 from source ‘test’. Note that in this case, the “newLinkId” is reported as the same value as “previousLinkId” – the Link ID did not truly change, rather the source record was deleted out of Universal Identity (while other source records still exist in that Link ID). deleteSourceService sourceDeleted ”{\”source\”:\”test\”,\”nativeId\”:\”0003\”,\”previousLinkId\”:\”5cf14aef59f4fc25a684c3dd\”,\”newLinkId\”:\”5cf14aef59f4fc25a684c3dd\”}”
The deleteSourceIdentity web service was invoked to delete native ID 0009 from source ‘test’, when test:0009 is the very last record associated with the Link Id. deleteSourceService hardDeleted ”{\”source\”:\”test\”,\”nativeId\”:\”0009\”,\”previousLinkId\”:\”5cf14aef59f4fc25a684c3dd\”,\”newLinkId\”:\”5cf14aef59f4fc25a684c3dd\”}”

The deactivateSourceWS web service was invoked to deactivate native ID 0009 from source ‘test`.

Note that in this case, the “newLinkId” is reported as the same value as “previousLinkId” – the Link ID did not truly change.

deactivateSource
sourceDeactivated
"{\"source\":\"test\",\"nativeId\":\"0009\",\"previousLinkId\":\"64d18670225d8b4b72fc9bb0\",\"newLinkId\":\"64d18670225d8b4b72fc9bb0\"}"
The reactivateSourceWS web service was invoked to reactivate native ID 0009 from source 'test'. The record test:0009 was originally under Link ID 64d18670225d8b4b72fc9bb0 and was assigned a new Link ID 64d1890fd483fd332c9d84f0.
reactivateSource
sourceReactivated
"{\"source\":\"test\",\"nativeId\":\"0009\",\"previousLinkId\":\"64d18670225d8b4b72fc9bb0\",\"newLinkId\":\"64d1890fd483fd332c9d84f0\"}"

A record in a postIdentity request gets matched with a Verato for Enrich Identity.


Note: Requires access to both Verato Universal Identity and Verato Enrich.

Ingestion Service
identityEnriched
{"success":true,"content":{"hasNext":false,"totalElements":1,"notifications":[{"ts":1728073469303,"service":"ingestionService","notificationType":"identityEnriched","body":"{\"source\":\"test\",\"nativeId\":\"99012:E\",\"linkId\":\"67004ef9bc6bdc387a5c4071\"}"}],"customerId":"verato"},"trackingId":"string","auditId":"2699214e-a682-4771-bcd5-6c8c6c0dee0b","retryableError":false}

A record in a postIdentity request gets matched with a Verato for Enrich Identity, and enriched data is requested in the notification.


Note: Requires access to both Verato Universal Identity and Verato Enrich.

Ingestion Service
identityEnriched

{"success":true,"content":{"hasNext":false,"totalElements":1,"notifications":[{"ts":1728073469303,"service":"ingestionService","notificationType":"identityEnriched","body":"{\"source\":\"test\",\"nativeId\":\"99012:E\",\"linkId\":\"67004ef9bc6bdc387a5c4071\",\"enrichedDetails\":\"{\\\"enrichSDOH\\\":{\\\"names\\\":[{\\\"first\\\":\\\"PAMELA\\\",\\\"middle\\\":\\\"W\\\",\\\"last\\\":\\\"WILLIAMS\\\"}]},\\\"enrichOutreach\\\":{}}\"}"}],"customerId":"verato"},"trackingId":"string","auditId":"2699214e-a682-4771-bcd5-6c8c6c0dee0b","retryableError":false}

 

searchNotifications example 1

  • This example shows how the searchNotifications web service behaves with pagination.

    With this request, the client is asking for all notification messages generated between 17:00 and 18:00 (inclusive) on November 21, 2019. In addition, the client is requesting the first page of notification messages (pageNumber=0) with a page size of 2 messages. Suppose that 3 notification messages exist in Universal Identity for that time range. Suppose that that a client sends the following request to the searchNotifications web service:

    {
      "content": { 
        "pageNumber": 0,
        "pageSize": 2,
        "startDate": "2019-11-21T17:00:00", 
        "endDate": "2019-11-21T18:00:00"
      },
    "trackingId": "Test20191125"
    }
    
  • The hasNext Boolean indicates there is at least one more page of notifications remaining.

    The totalElements integer indicates there are three total notification messages for this time period. If the client submitted a second searchNotifications request to retrieve the next page, they should expect to receive one additional notification message.

    {
      "success":true,
      "content": {
        "hasNext":true,
        "totalElements":3,
        "notifications": [
          { 
            "ts":1574462976506,
            "service": "linkIdentitiesService",
            "notificationType": "linkIdentities",
            "username": "demo-user1",
            "body": "{\"source\":\"test\",\"nativeId\":\"13843\",\"previousLinkId\":
    \"5dd865ed8b0f0e14c5487dfb\",\"newLinkId\":\"5dd865ef8b0f0e14c5487e0d\"}",
          },
          {
            "ts":1574462976792,
            "service":"linkIdentitiesService",
            "notificationType": "linkIdentities",
            "username": "demo-user1",      
            "body":"{\"source\":\"test\",\"nativeId\":\"13839\",\"previousLinkId\":
    \"5dd865f48b0f0e14c5487e20\",\"newLinkId\":\"5dd865f78b0f0e14c5487e2a\"}"
          }
        ],
        "customerId":"cust9999-test"
        },
          "trackingId":"Test20191125",
          "auditId":"43f08c66-bfab-4eca-b51a-e24701d5140e", 
          "retryableError":false
    }
    

searchNotifications example 2

  • To retrieve the next page, the client increments the pageNumber and submits this request:

    {
      "content": { 
        "pageNumber": 1,
        "pageSize": 2,
        "startDate": "2019-11-21T17:00:00", 
        "endDate": "2019-11-21T18:00:00"
      },
    "trackingId": "Test20191125"
    }
    
  • The ‘hasNext’ Boolean indicates there are no additional pages, and as expected, there is only one notification message for this page number, because the first 2 messages were retrieved in the previous page.

    
    {
      "success":true,
      "content":
        {
          "hasNext":false,
          "totalElements":3,
          "notifications": [
            {
              "ts":1574462976987,
              "service":"linkIdentitiesService",
              "notificationType": "linkIdentities",
              "username": "demo-user1",      
              "body":"{\"source\":\"test\",\"nativeId\":\"13832\",\"previousLinkId\":
    \"5dd865f28b0f0e14c5487e10\",\"newLinkId\":\"5dd865f78b0f0e14c5487e2a\"
            }"
        }
        ],
          "customerId":"cust9999-test"
        },
          "trackingId":"Test20191125",
          "auditId":"1dfcdf25-065c-4d3b-9616-22784ccc457c", 
          "retryableError":false
    }