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:

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:

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:

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:

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:

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:

Table 7.2 Person Attributes
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:

Table 7.3 Matching Error Object
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

Table 7.4 Expression Object
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

7.3.3.2.4. Error

Table 7.5 Error Object
Attribute Type Description Mandatory
code 32 bits integer Error code Yes
message String Error message Yes