Technical Specifications¶

Services¶

UIN Management¶

POST /v1/uin¶

Request the generation of a new UIN.

The request body should contain a list of attributes and their value, formatted as a json dictionary.

Status Codes:	200 OK – UIN is generated 401 Unauthorized – Client must be authenticated 403 Forbidden – Service forbidden 500 Internal Server Error – Unexpected error (See Error)

Example request:

POST http://server.com/v1/uin HTTP/1.1
Host: server.com
Content-Type: application/json

{
      "firstName": "John",
      "lastName": "Doo",
      "dateOfBirth": "1984-11-19"
}

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

Data Access¶

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.

Query Parameters:
Parameters:	uin (string) – Unique Identity Number
	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.

Query Parameters:
Parameters:	uin (string) – Unique Identity Number
	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"
}

Notifications¶

Attention

The interface to subscribe, receive, and notify events is not described here. It has not been decided if it is worth defining a neutral interface abstracting the broker and making the CR & CI provider independent from the broker selected by the integrator, or if it is better to use the native interface of the broker.

The first solution means an abstraction of the broker must be implemented, adding possible source of bugs or failures.

The second solution means the CR or CI cannot be simply replaced by a CR or CI from another vendor without some adaptation to use the interface of the broker.

To all reviewers: please comment and propose on this topic.

Data Model¶

Person Attributes¶

When exchanged in the services described in this document, the persons attributes will apply the following rules:

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

Notification Message¶

This section describes the messages exchanged through notification. All messages are encoded in json. They are generated by the emitter (the source of the event) and received by zero, one, or many receivers that have subscribed to the type of event.

Event Type & Message¶
Event Type	Message
`liveBirth`	`source`: identification of the system emitting the event `uin` of the new born `uin1` of the first parent (optional if parent is unknown) `uin2` of the second parent (optional if parent is unknown) Example: { "source": "systemX", "uin": "123456789", "uin1": "123456789", "uin2": "234567890" }
`death`	`source`: identification of the system emitting the event `uin` of the dead person Example: { "source": "systemX", "uin": "123456789" }
`birthCancellation`	`source`: identification of the system emitting the event `uin` of the person whose birth declaration is being cancelled Example: { "source": "systemX", "uin": "123456789", }
`foetalDeath`	`source`: identification of the system emitting the event `uin` of the new born Example: { "source": "systemX", "uin": "123456789" }
`marriage`	`source`: identification of the system emitting the event `uin1` of the first conjoint `uin2` of the second conjoint Example: { "source": "systemX", "uin1": "123456789", "uin2": "234567890" }
`divorce`	`source`: identification of the system emitting the event `uin1` of the first conjoint `uin2` of the second conjoint Example: { "source": "systemX", "uin1": "123456789", "uin2": "234567890" }
`annulment`	`source`: identification of the system emitting the event `uin1` of the first conjoint `uin2` of the second conjoint Example: { "source": "systemX", "uin1": "123456789", "uin2": "234567890" }
`separation`	`source`: identification of the system emitting the event `uin1` of the first conjoint `uin2` of the second conjoint Example: { "source": "systemX", "uin1": "123456789", "uin2": "234567890" }
`adoption`	`source`: identification of the system emitting the event `uin` of the child `uin1` of the first parent `uin2` of the second parent (optional) Example: { "source": "systemX", "uin": "123456789", "uin1": "234567890" }
`legitimation`	`source`: identification of the system emitting the event `uin` of the child `uin1` of the first parent `uin2` of the second parent (optional) Example: { "source": "systemX", "uin": "987654321", "uin1": "123456789", "uin2": "234567890" }
`recognition`	`source`: identification of the system emitting the event `uin` of the child `uin1` of the first parent `uin2` of the second parent (optional) Example: { "source": "systemX", "uin": "123456789", "uin2": "234567890" }
`changeOfName`	`source`: identification of the system emitting the event `uin` of the person Example: { "source": "systemX", "uin": "123456789" }
`changeOfGender`	`source`: identification of the system emitting the event `uin` of the person Example: { "source": "systemX", "uin": "123456789" }
`updatePerson`	`source`: identification of the system emitting the event `uin` of the person Example: { "source": "systemX", "uin": "123456789" }
`newPerson`	`source`: identification of the system emitting the event `uin` of the person Example: { "source": "systemX", "uin": "123456789" }
`duplicatePerson`	`source`: identification of the system emitting the event `uin` of the person to be kept `duplicates`: list of uin for records identified as duplicates Example: { "source": "systemX", "uin": "123456789", "duplicates": [ "234567890", "345678901" ] }

Note

Anonymized notification of events will be treated separately.

Attention

Should the UIN be mandatory? What happens when a person has no UIN?

Matching Error¶

A list of:

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

Expression¶

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

Error¶

Error Object¶
Attribute	Type	Description	Mandatory
`code`	32 bits integer	Error code	Yes
`message`	String	Error message	Yes