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.
The proposed URL space could use review.
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.
SOR is optional, and so is part of the body rather than the URL.
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 With Additional Identifiers
Implementations may return additional identifiers in a successful (200 or 201) response.
200 OK
{
"responseType":"referenceId",
"version":"1.0",
"referenceId":"M225127891",
"identifiers":
{
"netid":"pl388",
"universityid":"905003148"
}
}
Response: Potential Match Found
This response allows an SOR to interactively select from potential matches. (See also Forced Reconciliation Request, below.) This response may include as few as one candidate.
confidence is an integer from 0 through 100, where 100 indicates maximum confidence.
To indicate a new person, the Identity Match engine may create a provisional record returned in the 300 Multiple Choices response, with a suitable referenceId assigned. Alternately, the referenceId may be set to new. Either way, the original data submitted is provided as a candidate with confidence omitted.
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"
}
},
{
"referenceId":"new",
"attributes":
{
"sor":"SIS",
"sorId":"971194843",
"givenName":"Pat",
"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). The engine is responsible for maintaining enough state to be able to handle a manual reconciliation at a later (but not too much later) time.
See also Console Support Operations, below.
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. Only candidates listed in the 300 response may be included in the forced reconciliation 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"
},
"referenceId":"M523441767"
}
Update Match Attributes
The Identity Match engine must be kept up to date if attributes used for matching are updated. (For example, if a person's name changes, the SOR must update the name attributes in case the person subsequently shows up via a different SOR.) This can also be handled out of band, eg by sync'ing the match database with a registry database, or by the two databases being the same. As such, implementation of this method is optional.
Only the updated attributes are provided. To "delete" or unset an attribute, send an empty value.
Request
PUT /people/M523441767
{
"requestType":"updateAttributes",
"version":"1.0",
"sor":"SIS",
"sorAttributes":
{
"givenName":"Patricia",
}
}
Console Support Operations
In order to support an Identity Console, certain additional operations are needed. These operations are mandatory, in order to support decoupling of services (in this case the Identity Match engine from the Identity Console).
Note that resolving a pending reconciliation request is handled via the Forced Reconciliation Request, described above.
Request Pending Matches
GET /pending
200 OK
{
"responseType":"pendingMatches",
"version":"1.0",
"matchRequests":
[
"1009",
"1014"
]
}
Request Pending Match
It may be desirable for the response to include all known SOR data, if the match engine has access to it. This would facilitate the reconciliation administrator in determining how to resolve a pending match. Such functionality is optional, and could also be provided by having the Identity Console query the Identity Registry.
GET /pending/1009
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"
}
}
]
}