API Method DirectAddressValidate
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 trusted, non-revoked 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.
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
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
|
|---|
