7.3.3. Data Access

Get the OpenAPI file for this interface: dataaccess.yaml

Data Access Services

7.3.3.1. Services

7.3.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 or cr.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
  • max (number) – The maximum number of records to return. Default is 10
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 HTTP/1.1
Host: example.com
Authorization: Bearer cn389ncoiwuencr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "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 or cr.person.read

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=%5B%27string%27%5D HTTP/1.1
Host: example.com
Authorization: Bearer cn389ncoiwuencr

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.

Scope required: pr.person.match or cr.person.match

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
Authorization: Bearer cn389ncoiwuencr

{
    "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 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 or cr.person.verify

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
Authorization: Bearer cn389ncoiwuencr

[
    {
        "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"
}

7.3.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 or cr.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. (Required)
Status Codes:

Example request:

GET /v1/persons/{uin}/document?doctype=string&format=pdf HTTP/1.1
Host: example.com
Authorization: Bearer cn389ncoiwuencr

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