...
If the SOR ID is sensitive (such as being an SSN), placing it in the URL may not be ideal. In such a case, use of a salted-hashed identifier is recommended.
| Code Block |
|---|
PUT /v1/people/sis/971194843 { "sorAttributes": { "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "dateOfBirth":"1983-03-18", "identifiers":[ { "type":"national", "identifier":"3B902AE12DF55196" } ], "telephoneNumbers":[ { "type":"mobile", "number":"8185551234" } ] } } |
...
A search only request is similar to a regular request, except that a new identity will never be created as a result of the request. Note that a search only request does not imply that the requesting SOR intends to add a role record for an identity, and so is not an instruction for the match engine to change any state (ie: it is read-only from the match engine perspective).
| Code Block |
|---|
GET /v1/people/sis/971194843?names.0.type=official&names.0.given=Pat&names.0.family=Lee&dateOfBirth=1983-03-18&identifiers.0.type=national&identifiers.0.identifier=3B902AE12DF55196&telephoneNumbers.0.type=mobile&telephoneNumbers.0.number=8185551234
|
The same search only request may be submitted via POST to avoid embedding sensitive information in GET URLs.
| Code Block |
|---|
POST /v1/people/sis/971194843
{
"sorAttributes":
{
"names":[
{
"given":"Patricia",
"family":"Lee",
"type":"official"
}
],
"dateOfBirth":"1983-03-18",
"identifiers":[
{
"type":"national",
"identifier":"3B902AE12DF55196"
}
],
"telephoneNumbers":[
{
"type":"mobile",
"identifier":"8185551234"
}
]
}
}
|
...
An existing identity was found matching the specified attributes.
| Code Block |
|---|
200 OK { "referenceId":"M225127891" } |
...
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. This response will never be returned from a search only request.
| Code Block |
|---|
201 Created { "referenceId":"M225127891" } |
...
This response is only valid as a result of a search only request.
| Code Block |
|---|
404 Not Found
|
Response: With Additional Identifiers
Implementations may return additional identifiers in a successful (200 or 201) response.
| Code Block |
|---|
200 OK { "referenceId":"M225127891", "identifiers":[ { "type":"network", "identifier":"pl388" }, { "type":"enterprise", "identifier":"905003148" } ] } |
...
Coordinated implementations may return golden record attributes in a successful (200 or 201) response.
| Code Block |
|---|
200 OK { "referenceId":"M225127891", "identifiers":[ { "type":"network", "identifier":"pl388" }, { "type":"enterprise", "identifier":"905003148" } ], "golden":{ "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "dateOfBirth":"1983-03-18", } } |
...
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.
...
The Identity Match engine may elect to assign a match request ID to the transaction that generated the 300 Multiple Choices response. The match request ID is optional. If assigned, it is the same identifier as used to retrieve Pending Matches, and may be used in that context. If assigned, the match request ID must be provided when making a Forced Reconciliation Request to resolve the 300 Multiple Choices response.
| Code Block |
|---|
300 Multiple Choices { "matchRequest":"1009", "candidates": [ { "confidence":"85", "referenceId":"M219488003", "attributes": [ { "sor":"HRMS", "identifiers":[ { "type":"sor", "identifier":"089010023" }, { "type":"network", "identifier":"pl292" } ], "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "ou":"Biomedical Informatics" }, { "sor":"Alumni", "identifiers":[ { "type":"sor", "identifier":"A330-200" }, { "type":"network", "identifier":"pl292" } ], "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "ou":"Class of 1997" } ], "identifiers":[ { "type":"network", "identifier":"pl292" }, { "type":"enterprise", "identifier":"905008772" } ] }, { "confidence":"71", "referenceId":"M523441767", "attributes": [ { "sor":"guest", "identifiers":[ { "type":"sor", "identifier":"pl388" }, { "type":"network", "identifier":"pl388" } ], "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "telephoneNumbers":[ { "type":"mobile", "number":"8185551234" } ] } ], "identifiers":[ { "type":"network", "identifier":"pl388" }, { "type":"enterprise", "identifier":"905003148" } ] }, { "referenceId":"new", "attributes": [ { "sor":"SIS", "identifiers":[ { "type":"sor", "identifier":"971194843" } ] "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "telephoneNumbers":[ { "type":"mobile", "number":"8185551234" } ] } ] } ] } |
In a coordinated implementation, golden record attributes may be included for each candidate:
| Code Block |
|---|
300 Multiple Choices { "matchRequest":"1009", "candidates": [ { "confidence":"85", "referenceId":"M219488003", "golden":{ "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "dateOfBirth":"1983-03-18", }, "attributes": [ ... ] } ] } |
The ID Match engine may include a human readable explanation as to why a candidate was returned. This explanation is intended to provide guidance when an administrator is trying to resolve a potential match situation.
| Code Block |
|---|
300 Multiple Choices { "matchRequest":"1009", "candidates": [ { "confidence":"85", "referenceId":"M219488003", "explanation":"Family name exact match, given name initial match", "attributes": [ ... ] } ] } |
...
See also Console Support Operations, below.
| Code Block |
|---|
202 Accepted
|
An optional match request identifier may be returned as part of this response.
| Code Block |
|---|
202 Accepted { "matchRequest":"1009" } |
...
Errors could include failing to submit required attributes, submitting invalid values for attributes, etc.
| Code Block |
|---|
400 Bad Request
|
An optional human readable error message may be included in the response body.
| Code Block |
|---|
400 Bad Request { "error":"Required field not provided" } |
...
The Identity Match Engine may indicate a forced reconciliation request is being attempted using out of date information by returning 409 Conflict.
| Code Block |
|---|
PUT /v1/people/sis/971194843 { "sorAttributes": { "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "dateOfBirth":"1983-03-18", "identifiers":[ { "type":"national", "identifier":"3B902AE12DF55196" } ], "telephoneNumbers":[ { "type":"mobile", "number":"8185551234" } ] }, "referenceId":"M523441767" } |
If a Match Request Identifier was returned in a 202 or 300 response, it must be included in the Forced Reconciliation Request.
| Code Block |
|---|
PUT /v1/people/sis/971194843 { "matchRequest":"1009", "sorAttributes": { ... }, "referenceId":"M523441767" } |
...
Operation | Out of Band Sync | Coordinated | Independent |
|---|---|---|---|
Update Match Request | Do Not Implement | Required, including reference identifier | Required (reference identifier optional) |
Request Inventory of Requests | Optional | Required | Required |
Request Current Values | Optional | Required, including reference identifier | Required (reference identifier optional) |
Delete Current Values | Do Not Implement | Do Not Implement | Required |
Request
Typically, there is a Reference Identifier associated with the SOR and SORID. This request is therefore a request to update the System of Record attributes for use in future match requests, and the match engine may simply update its internal state and reply appropriately. Requesting a rematch of an already matched record is not supported via this mechanism.
If the requested SOR and SORID represents a pending match request (ie: there is no Reference ID associated with the request), the match engine should treat the request as a standard match request, but using the updated attributes. The request is most likely a SOR submitting updated attributes to fix a prior request that resulted in a pending match.
| Code Block |
|---|
| Code Block |
PUT /v1/people/sis/971194843 { "sorAttributes": { "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "dateOfBirth":"1983-03-18", "identifiers":[ { "type":"national", "identifier":"3B902AE12DF55196" }, { "type":"referenceId", "identifier":"M523441767" } ], "telephoneNumbers":[ { "type":"mobile", "number":"8185551234" } ] } } 200 OK |
...
The list of all requests made within an SOR may be obtained. The response is a list of SORIDs.
| Code Block |
|---|
GET /v1/people/sis 200 OK { "sorids": [ "971194843", "980121418", "937762041", "915233810" ] } |
...
The current values of match attributes as known to the match engine may be retrieved by the SOR. Note that if a match has previously been made, the referenceId will be included in the response. (If the request is pending manual resolution, the referenceId attribute will be omitted.) The match engine may elect to return former values for attributes, so long as they are suitably typed (eg: fka for a name).
| Code Block |
|---|
GET /v1/people/sis/971194843 200 OK { "sorAttributes": { "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "dateOfBirth":"1983-03-18", "identifiers":[ { "type":"national", "identifier":"3B902AE12DF55196" } ], "telephoneNumbers":[ { "type":"mobile", "number":"8185551234" } ] }, "requestTime":"2013-06-08T11:23:37Z", "referenceId":"M523441767"} |
...
The match attributes for the SOR can be deleted. Typically, this should only be done when a record was added erroneously, as the match engine will perform better if it has access to historical records.
| Code Block |
|---|
DELETE /v1/people/sis/971194843
200 OK
|
...
Request Pending Matches
| Code Block |
|---|
GET /v1/matchRequests?status=pending 200 OK { "matchRequests": { "1009": { "attributes": { "sor":"SIS", "identifiers":[ { "type":"sor", "identifier":"971194843" } ] "names":[ { "type":"official", "given":"Pat", "family":"Lee" } ], "telephoneNumbers":[ { "type":"mobile", "number":"8185551234" } ] }, "requestTime":"2013-06-08T11:23:37Z" }, "1014": { "attributes": { "sor":"HRMS", "sorId":"914890374", "identifiers":[ { "type":"sor", "identifier":"089010023" }, { "type":"network", "identifier":"p5478" } ], "names":[ { "type":"official", "given":"Richard", "family":"Hess" } ], "ou":"Biology" }, "requestTime":"2013-06-08T11:23:37Z" } } } |
...
It may also sometimes be useful to retrieve the set of resolved match requests.
| Code Block |
|---|
GET /v1/matchRequests?status=resolved
200 OK
{
"matchRequests":
{
"1009":
{
"attributes":
{
"sor":"SIS",
"identifiers":[
{
"type":"sor",
"identifier":"971194843"
}
]
"names":[
{
"type":"official",
"given":"Pat",
"family":"Lee"
}
],
"telephoneNumbers":[
{
"type":"mobile",
"number":"8185551234"
}
]
},
"requestTime":"2013-06-08T11:23:37Z",
"resolutionTime":"2013-06-10T11:23:37Z",
"referenceId":"M523441767"
},
"1014":
{
"attributes":
{
"sor":"HRMS",
"sorId":"914890374",
"identifiers":[
{
"type":"sor",
"identifier":"089010023"
},
{
"type":"network",
"identifier":"p5478"
}
],
"names":[
{
"type":"official",
"given":"Richard",
"family":"Hess"
}
],
"ou":"Biology"
},
"requestTime":"2013-06-08T11:23:37Z",
"resolutionTime":"2013-06-10T11:23:37Z"'
"referenceId":"M523441995"
}
}
}
|
...
The explanation field returned as part of a Potential Match Found response may also be returned here.
| Code Block |
|---|
GET /v1/matchRequests/1009
300 Multiple Choices
{
"candidates":
[
{
"confidence":"85",
"referenceId":"M219488003",
"attributes":
[
{
"sor":"HRMS",
"identifiers":[
{
"type":"sor",
"identifier":"089010023"
},
{
"type":"network",
"identifier":"pl292"
}
],
"names":[
{
"type":"official",
"given":"Patricia",
"family":"Lee"
}
],
"ou":"Biomedical Informatics"
}
]
},
{
"confidence":"71",
"referenceId":"M523441767",
"attributes":
[
{
"sor":"guest",
"identifiers":[
{
"type":"sor",
"identifier":"pl388"
},
{
"type":"network",
"identifier":"pl388"
}
],
"names":[
{
"type":"official",
"given":"Patrick",
"family":"Lee"
}
],
"telephoneNumbers":[
{
"type":"mobile",
"number":"8185551234"
}
]
}
]
},
{
"referenceId":"new",
"attributes":
[
{
"sor":"SIS",
"sorId":"971194843",
"identifiers":[
{
"type":"sor",
"identifier":"971194843"
}
],
"names":[
{
"type":"official",
"given":"Pat",
"family":"Lee"
}
],
"telephoneNumbers":[
{
"type":"mobile",
"number":"8185551234"
}
]
}
]
}
],
"requestTime":"2013-06-08T11:23:37Z"
}
|
A match request that has already been resolved might not return the available candidates, but instead an indication that the match was successfully resolved.
| Code Block |
|---|
GET /v1/matchRequests/1014
200 OK
{
"requestTime":"2013-06-08T11:23:37Z",
"resolutionTime":"2013-06-10T11:23:37Z"'
"referenceId":"M523441995"
}
|
...
To obtain the set of SOR records attached to a reference identifier, submit the reference identifier in the following GET request.
| Code Block |
|---|
GET /v1/matchRequests?referenceId=M523441767
|
...
If the Identity Match engine maintains additional identifiers, these may be returned as well.
| Code Block |
|---|
GET /v1/matchRequests?referenceId=M523441767 200 OK { "matchRequests":{ ... }, "identifiers":[ { "type":"network", "identifier":"pl388" }, { "type":"enterprise", "identifier":"905003148" } ] } |
In a coordinated implementation, current "golden" attributes may also be returned:
| Code Block |
|---|
GET /v1/matchRequests?referenceId=M523441767 200 OK { "matchRequests":{ ... }, "golden":{ "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "dateOfBirth":"1983-03-18", } } |
...
Under certain circumstances, the Identity Match engine may not have enough information to link a new record with an existing reference identifier, resulting in a person having two (or more) reference identifiers. The reference identifiers can later be joined together using this request. The active reference identifier is provided in the resource URL and the deprecated reference identifiers in the request body.
| Code Block |
|---|
PUT /v1/referenceIds/M523441767 { "referenceIds":[ "M787800232", "M350100023" ] } |
If supported by the engine, the identifiers to maintain as primary may also be specified:
| Code Block |
|---|
PUT /v1/referenceIds/M523441767 { "referenceIds":[ "M787800232", "M350100023" ], "identifiers":[ { "type":"network", "identifier":"pl388" }, { "type":"enterprise", "identifier":"905003148" } ] } |
In a coordinated implementation, if supported by the engine the attributes to keep in the golden record may also be specified:
| Code Block |
|---|
PUT /v1/referenceIds/M523441767 { "referenceIds":[ "M787800232", "M350100023" ], "identifiers":[ { "type":"network", "identifier":"pl388" }, { "type":"enterprise", "identifier":"905003148" } ], "golden":{ "names":[ { "type":"official", "given":"Patricia", "family":"Lee" } ], "dateOfBirth":"1983-03-18", } } |
...
If the Match Engine incorrectly assigned a reference identifier to a record, it is possible for an administrator to specify a replacement reference identifier for that record. This is very similar to a Forced Reconciliation Request, except that sorAttributes are not specified.
| Code Block |
|---|
PUT /v1/people/sis/971194843 { "referenceId":"M523441767" } |
...