Address API usage (inbound)

A Watson™ Care Manager record and an Electronic Medical Record (EMR) on an external system must reflect the same details about a client. When a change occurs in a client's address in the external system, this API synchronizes the client's data in Watson Care Manager with the latest update that is recorded for the client in the external system.

The following business scenario is for illustrative purposes only. You can apply many additional use cases to suit your specific needs, for example, in a healthcare space or specialty court environment.

Business problem

Let’s suppose that Joe Lopez is already registered in Watson Care Manager (via the Client Registration API) for reasons that are described here. At the time of his registration, no address was recorded for Joe because he had no fixed abode after having been evicted from his apartment.

During a recent visit with his Primary Care Physician (PCP) in One Step Medical Center, Joe mentioned that he moved in with his parents to help him get back on track. This news prompted his PCP to enter Joe's new address in his EMR on the external system, which triggers an address update to be sent to Watson Care Manager via the Address API.

Why integrate Watson Care Manager with an external system?

The external system interfaces with Watson Care Manager so that a multidisciplinary team in TrustHealth ACO can access Joe’s latest demographic details and contact him when needed (and you can presume that the necessary administrator configuration is already complete in Watson Care Manager to facilitate the integration). Being able to update a client's demographic details using an API means that someone in TrustHealth ACO does not have to manually record the data that already exists on the external system. The process is automated so that the client's address details in Watson Care Manager and the record update in the external system are in sync, which for the care team, saves them considerable time and assures them of accurate and reliable data.

In this scenario, Joe's PCP initiated an action to update Joe's address record on their system and his address details in Watson Care Manager synchronized with the update via this API.

The following diagram shows the end-to-end work flow and you can see that in the API call, the Address resource contains all of the demographic data relating to the client.
Figure 1. Address API (inbound) Example: Joe Lopez address update
An integration diagram that shows how Joe Lopez's address update in an external system is reflected in Watson Care Manager via the Address API.
  1. A team member in the One Step Medical Center clicks the action to update Joe's address and send the address record to Watson Care Manager.
  2. The Integration Platform layer receives the data and builds a message to send to Watson Care Manager.
  3. The message is sent to the Address API.
  4. The address details for Joe is received in Watson Care Manager and displayed on the client's Summary page when accepted in the application.

How is the client, Joe Lopez, identified in Watson Care Manager?

For more information about the API attributes that enable the correct client to be identified, see Client matching and identification.

Inputs to the Address API: mandatory and optional attributes

To send an address record from an external system to Watson Care Manager, the Address API must receive certain attributes and associated values. Other API attribute values are optional. The following table hightlights the mandatory attributes (*) and the optional attributes that are passed in the Address POST call to create the new address record for Joe Lopez.
API attributes Description 
{
   "resourceType": "Address",
Resource type * - Address. Note there is no Address resource type in FHIR - this represents a sub-resource. 
"identifier": [
   {
     "value": "103399884",
     "type": {
       "text": "TRUSTCOID"
     }
   }
  ],
 Identifier - An External record identifier for this record can be shared as described in Record identifiers. In this example, the ID of this record on the Trust Co system is 103399884 . 
 "source": {
       "coding": [{
           "system": "http://wcm/source",
           "code": "TRUSTCO"
       }],
       "text": "TrustCo"
  },
 Source - The source for this Address is TRUSTCO. See Source and Original Source System identifiers. 
 "originalSource": {
       "coding": [
         {
           "system": "http://wcm/originalsource",
           "code": "ALLSCRIPT"
         }
       ],
       "text": "AllScripts EMR"
  },
Original Source System - The Address record was originally recorded in the AllScripts system before being aggregated by TrustCo. See Source and Original Source System identifiers. 
 "use": "work",
 "state": "NJ",
 "country": "US",    
 "city": "Trenton",
 "line1": "Apt 1234",
 "line2": "Greenfields Rise",
 "line3": "Esker Road",
 "postalCode": "NJ8899",
 
 "period": {
   "start": "",
   "end": ""
 },
Address - A single address record for Joe Lopez. The Address fields are defined as per the FHIR datatype. 
"subject": {
   "reference": "Patient/identifier=ONESTEPID, identifiervalue=220398B4"
 }
}
Subject * - Joe Lopez can be identified as the subject for this Address by using the Identifier that is recorded for him during registration. For more information, see Client matching and identification.
Tip: In the REST API catalog that is referenced below, go to the Address API (Swagger output). Try out the API calls and see the detail of this topic in action!

Error Handling

For more information about the HTTP status codes that indicate success or failure in API calls, see Error codes.