7.3.3. Data Access¶
Download the OpenAPI file for this interface dataaccess.yaml.
7.3.3.1. Services¶
-
GET
/v1/persons
¶ Retrieve a UIN based on a set of attributes. This service is used when the UIN is unknown.
Query Parameters: - attributes (object) – The attributes used to retrieve the UIN (Required)
Status Codes: - 200 OK – All UIN found (a list of at least one UIN)
- 400 Bad Request – Invalid parameter
- 401 Unauthorized – Client must be authenticated
- 403 Forbidden – Service forbidden
- 404 Not Found – No UIN found
- 500 Internal Server Error – Unexpected error (See Error)
Example request:
GET /v1/persons?firstName=John&lastName=Do HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ "1235567890" ]
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "code": 1, "message": "string" }
-
GET
/v1/persons/{uin}
¶ Retrieve attributes for a person.
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.
- 401 Unauthorized – Client must be authenticated
- 403 Forbidden – Service forbidden
- 404 Not Found – Unknown uin
- 500 Internal Server Error – Unexpected error (See Error)
Example request:
GET /v1/persons/{uin}?attributeNames=firstName&attributeNames=lastName&attributeNames=dob 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 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.
Parameters: - uin (string) – Unique Identity Number
Status Codes: - 200 OK – Information about non matching attributes. Returns a list of matching result (See Matching Error) An empty list indicates all attributes were matching.
- 401 Unauthorized – Client must be authenticated
- 403 Forbidden – Service forbidden
- 404 Not Found – Unknown uin
- 500 Internal Server Error – Unexpected error (See 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 500 Internal Server Error Content-Type: application/json { "code": 1, "message": "string" }
-
POST
/v1/persons/{uin}/verify
¶ Evaluate expressions (See Expression) 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 Expression.
Parameters: - uin (string) – Unique Identity Number
Status Codes: - 200 OK – The expressions are all true (true is returned) or one is false (false is returned)
- 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 (See 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 500 Internal Server Error Content-Type: application/json { "code": 1, "message": "string" }
-
GET
/v1/persons/{uin}/document
¶ Retrieve in an unstructured format (PDF, image) a document such as a marriage certificate.
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. (Required)
Status Codes: - 200 OK – The document(s) is/are found and returned, as binary data in a MIME multipart structure.
- 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 (See Error)
Example request:
GET /v1/persons/{uin}/document?doctype=marriage&secondaryUin=234567890&format=pdf HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "code": 1, "message": "string" }
7.3.3.2. Data Model¶
7.3.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 |
---|---|---|
uin |
Unique Identity Number | Text |
firstName |
First name | Text |
lastName |
Last name | Text |
spouseName |
Spouse name | Text |
dateOfBirth |
Date of birth | Date (iso8601). Example: 1987-11-17 |
placeOfBirth |
Place of birth | Text |
gender |
Gender | Number (iso5218). One of 0 (Not known), 1 (Male), 2 (Female), 9 (Not applicable) |
dateOfDeath |
Date of death | Date (iso8601). Example: 2018-11-17 |
placeOfDeath |
Place of death | Text |
reasonOfDeath |
Reason of death | Text |
status |
Status. Example: missing, wanted, dead, etc. | Text |
7.3.3.2.2. Matching Error¶
A list of:
Attribute | Type | Description | Mandatory |
---|---|---|---|
attributeName |
String | Attribute name (See Person Attributes) | Yes |
errorCode |
32 bits integer | Error code. Possible values: 0 (attribute does not exist); 1 (attribute exists but does not match) |
Yes |
7.3.3.2.3. Expression¶
Attribute | Type | Description | Mandatory |
---|---|---|---|
attributeName |
String | Attribute name (See Person Attributes) | Yes |
operator |
String | Operator to apply. Possible values: < , > , = , >= , <= |
Yes |
value |
string, or integer, or boolean | The value to be evaluated | Yes |