7.3. Data Access¶
This is version 1.3.0 of this interface.
Get the OpenAPI file: dataaccess.yaml
7.3.1. Services¶
7.3.1.1. Person¶
- GET /v1/persons¶
Query for persons using a set of attributes. Retrieve the UIN or the person attributes. This service is used when the UIN is unknown. Example: http://registry.com/v1/persons?firstName=John&lastName=Do&names=firstName
Scope required:
pr.person.read
orcr.person.read
- Query Parameters
attributes (object) – The attributes (names and values) used to query. (Required)
names (array) – The names of the attributes to return. If not provided, only the UIN is returned.
offset (integer) – The offset of the query (first item of the response). Default:
0
.limit (integer) – The maximum number of items to return. Default:
100
.
- Status Codes
200 OK – The requested attributes for all found persons (a list of at least one entry). If no names are given, a flat list of UIN is returned. If at least one name is given, a list of dictionaries (one dictionary per record) is returned. .
400 Bad Request – Invalid parameter.
401 Unauthorized – Client must be authenticated.
403 Forbidden – Service forbidden.
404 Not Found – No record found.
500 Internal Server Error – Unexpected error.
Example request:
GET /v1/persons?firstName=John&lastName=Do&names=firstName&names=lastName&offset=1&limit=1 HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ "string" ]
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "code": 1, "message": "string" }
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "code": 1, "message": "string" }
- GET /v1/persons/{uin}¶
Read attributes for a person. Example: http://registry.com/v1/persons/123456789?attributeNames=firstName&attributeNames=lastName&attributeNames=dob
Scope required:
pr.person.read
orcr.person.read
- Parameters
uin (string) – Unique Identity Number.
- Query Parameters
attributeNames (array) – The names of the attributes requested for this person. (Required)
- Status Codes
200 OK – Requested attributes values or error description.
400 Bad Request – Invalid parameter.
401 Unauthorized – Client must be authenticated.
403 Forbidden – Service forbidden.
404 Not Found – Unknown uin.
500 Internal Server Error – Unexpected error.
Example request:
GET /v1/persons/{uin}?attributeNames=%5B%27string%27%5D HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "firstName": "John", "lastName": "Doo", "dob": { "code": 1023, "message": "Unknown attribute name" } }
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "code": 1, "message": "string" }
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "code": 1, "message": "string" }
- POST /v1/persons/{uin}/match¶
Match person attributes. This service is used to check the value of attributes without exposing private data.
The request body should contain a list of attributes and their value, formatted as a json dictionary.
Scope required:
pr.person.match
orcr.person.match
- Parameters
uin (string) – Unique Identity Number.
- Form Parameters
body – A set of attributes for the person.
- Status Codes
200 OK – Information about non matching attributes. Returns a list of matching result. An empty list indicates all attributes were matching. .
400 Bad Request – Invalid parameter.
401 Unauthorized – Client must be authenticated.
403 Forbidden – Service forbidden.
404 Not Found – Unknown uin.
500 Internal Server Error – Unexpected error.
Example request:
POST /v1/persons/{uin}/match HTTP/1.1 Host: example.com Content-Type: application/json { "firstName": "John", "lastName": "Doo", "dateOfBirth": "1984-11-19" }
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "attributeName": "firstName", "errorCode": 1 } ]
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "code": 1, "message": "string" }
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "code": 1, "message": "string" }
- POST /v1/persons/{uin}/verify¶
Evaluate expressions on person attributes. This service is used to evaluate simple expressions on person’s attributes without exposing private data
The request body should contain a list of expressions.
Scope required:
pr.person.verify
orcr.person.verify
- Parameters
uin (string) – Unique Identity Number.
- Form Parameters
body – A set of expressions on attributes of the person.
- Status Codes
200 OK – The expressions are all true (true is returned) or one is false (false is returned).
400 Bad Request – Invalid parameter.
401 Unauthorized – Client must be authenticated.
403 Forbidden – Forbidden access. The service is forbidden or one of the attributes is forbidden.
404 Not Found – Unknown uin.
500 Internal Server Error – Unexpected error.
Example request:
POST /v1/persons/{uin}/verify HTTP/1.1 Host: example.com Content-Type: application/json [ { "attributeName": "firstName", "operator": "=", "value": "John" }, { "attributeName": "dateOfBirth", "operator": "<", "value": "1990-12-31" } ]
Example response:
HTTP/1.1 200 OK Content-Type: application/json true
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "code": 1, "message": "string" }
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "code": 1, "message": "string" }
7.3.1.2. Document¶
- GET /v1/persons/{uin}/document¶
Read in an unstructured format (PDF, image) a document such as a marriage certificate. Example:
http://registry.com/v1/persons/123456789/document?doctype=marriage&secondaryUin=234567890&format=pdf
Scope required:
pr.document.read
orcr.document.read
- Parameters
uin (string) – Unique Identity Number.
- Query Parameters
secondaryUin (string) – Unique Identity Number of a second person linked to the requested document. Example: wife, husband .
doctype (string) – The type of document. (Required)
format (string) – The expected format of the document. If the document is not available at this format, it must be converted. TBD: one format for certificate data. . Constraints: possible values are
pdf
,jpeg
,png
,TBD
. (Required)
- Status Codes
200 OK – The document(s) is/are found and returned, as binary data in a MIME multipart structure.
400 Bad Request – Invalid parameter.
401 Unauthorized – Client must be authenticated.
403 Forbidden – Service forbidden.
404 Not Found – Unknown uin.
415 Unsupported Media Type – Unsupported format.
500 Internal Server Error – Unexpected error.
Example request:
GET /v1/persons/{uin}/document?secondaryUin=string&doctype=string&format=pdf HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "code": 1, "message": "string" }
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "code": 1, "message": "string" }
7.3.2. Data Model¶
7.3.2.1. Person Attributes¶
When exchanged in the services described in this document, the persons attributes will apply the following rules:
Attribute Name |
Description |
Format |
---|---|---|
|
Unique Identity Number |
Text |
|
First name |
Text |
|
Last name |
Text |
|
Spouse name |
Text |
|
Date of birth |
Date (iso8601). Example: |
|
Place of birth |
Text |
|
Gender |
Number (iso5218). One of 0 (Not known), 1 (Male), 2 (Female), 9 (Not applicable) |
|
Date of death |
Date (iso8601). Example: |
|
Place of death |
Text |
|
Reason of death |
Text |
|
Status. Example: missing, wanted, dead, etc. |
Text |
7.3.2.2. Matching Error¶
A list of:
Attribute |
Type |
Description |
Mandatory |
---|---|---|---|
|
String |
Attribute name (See Person Attributes) |
Yes |
|
32 bits integer |
Error code. Possible values: |
Yes |
7.3.2.3. Expression¶
Attribute |
Type |
Description |
Mandatory |
---|---|---|---|
|
String |
Attribute name (See Person Attributes) |
Yes |
|
String |
Operator to apply. Possible values: |
Yes |
|
string, or integer, or boolean |
The value to be evaluated |
Yes |
7.3.2.4. Error¶
Attribute |
Type |
Description |
Mandatory |
---|---|---|---|
|
32 bits integer |
Error code |
Yes |
|
String |
Error message |
Yes |