About the ID Match API
This API is used to determine if a Person is already known to the IdMS. It is exposed by the ID Match component. The Registry component may also expose this API, either because it implements ID Match natively or because it brokers requests to the ID Match component.
This draft is based on the ID Match Strawman.
Methods
Reference Identifier Request
Obtain a unique reference identifier from the ID Match component in order to canonically identify the person presented by the SOR.
Note: The reference identifier returned to an SOR may match an identifier previously known to the SOR. For example, if an employee returns after an absence of several years, the IdMS may have the original reference identifier whereas the HRMS may have purged its copy.
Request
POST /people
{
"requestType":"referenceId",
"version":"1.0",
"sor":"SIS",
"sorAttributes":
{
"sorId":"971194843",
"givenName":"Pat",
"sn":"Lee",
"dateOfBirth":"1983-03-18",
"hashedSSN":"3B902AE12DF55196",
"mobile":"8185551234"
}
}
Response: Unique Match Found
200 OK
{
"responseType":"referenceId",
"version":"1.0",
"referenceId":"M225127891"
}
Response: New Identifier Assigned
This and Unique Match Found are effectively equivalent from the perspective of the client.
201 Created
{
"responseType":"referenceId",
"version":"1.0",
"referenceId":"M225127891"
}
Response: Potential Match Found
This response allows an SOR to interactively select from potential matches. See also Forced Reconciliation Request.
300 Multiple Choices
{
"responseType":"candidates",
"version":"1.0",
"candidates":
[
{
"confidence":"85",
"referenceId":"M219488003",
"attributes":
{
"sor":"HRMS",
"sorId":"089010023",
"netId":"pl292",
"givenName":"Patricia",
"sn":"Lee",
"ou":"Biomedical Informatics"
}
},
{
"confidence":"71",
"referenceId":"M523441767",
"attributes":
{
"sor":"guest",
"sorId":"pl388",
"netId":"pl388",
"givenName":"Patrick",
"sn":"Lee"
"mobile":"8185551234"
}
}
]
}
Response: Potential Match Found (Externally Handled)
Some configurations may not support an interactive transaction over the API to resolve a conflict. In this sort of scenario, the ID Match engine will submit a reconciliation request to a Reconciliation Manager (probably via email with a URL for resolution).
202 Accepted
Response: Error With Request
400 Bad Request
Forced Reconciliation Request
After a 300 Multiple Choices response, the client must submit a modified request with an ID Match Reference Identifier to link to an existing record, or an indication that a new person should be created. This will generally result in 200 OK.
POST /people
{
"requestType":"referenceId",
"version":"1.0",
"sor":"SIS",
"sorAttributes":
{
"sorId":"971194843",
"givenName":"Pat",
"sn":"Lee",
"dateOfBirth":"1983-03-18",
"hashedSSN":"3B902AE12DF55196",
"mobile":"8185551234"
},
"referenceId":"M523441767"
}