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 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.

  • 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 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

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 or cr.person.match

Parameters

  • uin (string) – Unique Identity Number.

Form Parameters

  • body – A set of attributes for the person.

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

Parameters

  • uin (string) – Unique Identity Number.

Form Parameters

  • body – A set of expressions on attributes of the person.

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 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 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. . Constraints: possible values are pdf, jpeg, png, TBD. (Required)

Status Codes

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:

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.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.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.2.4. Error

Table 7.5 Error Object

Attribute

Type

Description

Mandatory

code

32 bits integer

Error code

Yes

message

String

Error message

Yes