About the ID Match API
This API is used to obtain a unique reference to a Person known to the IdMS based on data known to an SOR. The Person may or may not be known to the IdMS at the time of the query, but generally the Person will be new to the SOR.
This API 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.
Operations
All operations are mandatory unless otherwise stated.
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 indicates the system submitting the request.
The following sorAttributes are defined for matching purposes, with an intent to align with SOR-Registry Core Schema Strawman definitions:
- sorId
- address (home, official; broken out into st, l, etc)
- affiliation
- dateOfBirth
- gender
- givenName
- nationalId (may be hashed)
- institutionId (eg: University ID)
- mail (ie: personal email)
- mobile
- name:official, name:preferred
- netId
- sn
- telephoneNumber:home, telephoneNumber:official
The specific sorAttributes that are required may vary by instance.
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",
"nationalId":"3B902AE12DF55196",
"mobile":"8185551234"
}
}
Response: Unique Match Found
An existing identity was found matching the specified attributes.
200 OK
{
"responseType":"referenceId",
"version":"1.0",
"referenceId":"M225127891"
}
Response: New Identifier Assigned
A new identity was created, since no existing identity matched the specified attributes. New Identifier Assigned 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.
The identifier attribute names are not specified, and may vary by local implementation.
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. Implementation of this response is optional if the Externally Handled response is implemented.
confidence is an integer from 0 through 100, where 100 indicates maximum confidence.
Attributes may be returned to facilitate the selection of a candidate. The attributes may include any attribute specified in the SOR-Registry Core Schema Strawman, even attributes that the matching engine does not use to perform matching. The specific set of attributes returned may vary by local implementation.
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
Errors could include failing to submit required attributes, submitting invalid values for attributes, etc.
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",
"nationalId":"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":
[
{
"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"
}
}
],
"1014":
[
{
"confidence":"78",
"referenceId":"M660187457",
"attributes":
{
"sor":"HRMS",
"sorId":"914890374",
"netId":"p5478",
"givenName":"Richard",
"sn":"Hertz",
"ou":"Biology"
}
},
{
"confidence":"64",
"referenceId":"M287898924",
"attributes":
{
"sor":"HRMS",
"sorId":"881095626",
"netId":"p8314",
"givenName":"Ricardo",
"sn":"Hertzfeld"
"ou":"Neuroscience"
}
}
]
]
}
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"
}
}
]
}