API Method DirectAddressValidate

From Updox API
Revision as of 08:02, 26 June 2014 by Thenate (Talk | contribs)

Jump to: navigation, search


Contents

Description

The following code samples describe the processes involved in "validating" a Direct address and discuss what happens behind the scenes with domain-level address validation and address-level validation.


Behind the Scenes

When a call is made to /DirectAddressValidate, a search is performed for a current, non-revoked certificate for the target Direct address. There two types of certificate searches performed:

Address-level Certificates

The first certificate search looks for a certificate issued for the full recipient address: DrTom@DrTomsPractice.MyEHRDirect.com. If all of the following are true, then /DirectAddressValidate will return "validDirectAddress": true:

  • a certificate is found (either via DNS or LDAP)
  • the found certificate has not been revoked
  • the found certificate is trusted itself or is signed by a trusted TrustAnchor
  • the found certificate is either:
    • not signed by DirectTrust or
    • signed by DirectTrust and the inquiring user's practice has been "vetted"1


Domain-level Certificates

If no valid certificate can be found for the address, the next certificate search will be performed on the domain of the intended recipient: DrBobsPractice.OtherEHRDirect.com. A Domain-level certificate is used for all users in a given domain. The same certificate will be used to sign messages from DrBob@DrBobsPractice.OtherEHRDirect.com and messages from NurseRatchett@DrBobsPractice.OtherEHRDirect.com. Since there aren't any user-specific (aka Address-specific) certificates available to be searched, the most precise anyone can be about determining if the recipient Direct address exists is to confirm the existence of a trusted, non-revoked certificate for the domain. The same requirements apply to a domain-level certificate for it to be valid as apply to an address-level certificate:

  • a certificate is found (either via DNS or LDAP)
  • the found certificate has not been revoked
  • the found certificate is trusted itself or is signed by a trusted TrustAnchor
  • the found certificate is either:
    • not signed by DirectTrust or
    • signed by DirectTrust and the inquiring user's practice has been "vetted"1


IMPORTANT NOTE: A response from /DirectAddressValidate of true does not mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked, trusted certificate can be found for the requested address or domain. For information about delivery confirmation, read about MDN processing.

Prerequisites

1 This API call requires Vendor-level credentials. The credentials should be populated into the applicationId and applicationPassword fields of the auth block: 

 {
   ...
   "auth": {
     "applicationId": "vendorId",
     "applicationPassword": "vendorPassword",
     "accountId": "",
     "userId": ""
   }
 }

Code Samples

Language Source Code Examples
C# 
 public void TalkToUpdox() {
   string json = new JavaScriptSerializer().Serialize(new {
     recipient = "DrTom@DrTomsPractice.MyEHRDirect.com",  // required
     auth = new {
       applicationId = "vendorId",
       applicationPassword = "vendorPassword",
       accountId : "accountId",
       userId: "userId"
     }
   });
   string url = "https://updoxqa.com/io/directAddressValidate";
   SendReceiveJSON(json, url);
 }
 
 private void SendReceiveJSON(string json, string url)
 {
   var httpWebRequest = WebRequest.Create(url);
   httpWebRequest.ContentType = "application/json";
   httpWebRequest.Method = "POST";
   using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
   {
     streamWriter.Write(json);
     streamWriter.Flush();
     streamWriter.Close();
     var httpResponse = (HttpWebResponse) httpWebRequest.GetResponse();
     using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
     {
       var result = streamReader.ReadToEnd();
     }
   }
 }
Java 


   import com.fasterxml.jackson.databind.JsonNode;
   import com.fasterxml.jackson.databind.ObjectMapper;
   import org.apache.http.HttpEntity;
   import org.apache.http.HttpResponse;
   import org.apache.http.client.HttpClient;
   import org.apache.http.client.methods.HttpPost;
   import org.apache.http.entity.StringEntity;
   import org.apache.http.impl.client.DefaultHttpClient;
   import org.apache.http.util.EntityUtils;
   import java.util.HashMap;
   import java.util.Map;
 
 
   public class UpdoxTest {
 
 
   public void TalkToUpdox() throws Exception {
       String uri = "https://updoxqa.com/io/directAddressValidate";
       ObjectMapper mapper = new ObjectMapper();
       Map<String,Object> messageData = BuildMessage();
       String jsonData = mapper.writeValueAsString(messageData);
       HttpResponse httpResponse = SendReceiveJSON(jsonData, uri);
       HttpEntity responseEntity = httpResponse.getEntity();
       String response = EntityUtils.toString(responseEntity);
       JsonNode actualObj = mapper.readTree(response);
 
       System.out.println(actualObj.get("responseCode"));
       System.out.println(actualObj.get("responseMessage"));
   }
 
   private Map<String,Object> BuildMessage() throws Exception
   {
       Map<String,Object> messageData = new HashMap();
       Map<String,String> authData = new HashMap();
       messageData.put("recipient", "DrTom@DrTomsPractice.MyEHRDirect.com");
       Map<String,Object> authData = new HashMap();
       authData.put("applicationId", "vendorId");
       authData.put("applicationPassword", "vendorPassword");
       authData.put("accountId", "accountId");
       authData.put("userId", "userId");
       messageData.put("auth", authData);
       messageData.put("auth", authData);
       return messageData;
   }
 
   private HttpResponse SendReceiveJSON(String jsonData, String uri) throws Exception {
       HttpClient httpClient = new DefaultHttpClient();
       HttpResponse response = null;
       StringEntity params = new StringEntity(jsonData);
       try {
           HttpPost request = new HttpPost(uri);
           request.addHeader("content-type", "application/json");
           request.setEntity(params);
           response = httpClient.execute(request);
       } catch (Exception ex) {
           // handle exception here
       } finally {
           httpClient.getConnectionManager().shutdown();
       }
       return response;
   }
 
 
   }

Messages

Destination Address 

 https://updoxqa.com/io/directAddressValidate

Request JSON 

 {
   "recipient": "DrTom@DrTomsPractice.MyEHRDirect.com",
   "auth": {
      "applicationId": "vendorId",
      "applicationPassword": "vendorPassword",
      "accountId": "",
      "userId": ""
   }
 }

HTTP Response Status 

 200 OK

Response JSON 

 {
   "successful": true,
   "responseMessage": "OK",
   "responseCode": 2000,
   "recipient": "contact:171099",
   "name": "DrTom@DrTomsPractice.MyEHRDirect.com",
   "directAddress": "DrTom@DrTomsPractice.MyEHRDirect.com",
   "validDirectAddress": true,
   "vettingRequired": false,
   "reason": null
 }



Relevant Response Codes

In addition to the General Error Set, this method may return the following values in the responseCode and responseMessage fields:

responseCode responseMessage
Retrieved from "http://updoxqa.com/wiki/index.php?title=API_Method_DirectAddressValidate&oldid=2894"