5. Interfaces

The chapter below describes the specifications of all OSIA interfaces and related services.

5.1. Notification

See Notification for the technical details of this interface.

The subscription & notification process is managed by a middleware and is described in the following diagram:

Fig. 5.1 Subscription & Notification Process

5.1.1. Services

5.1.1.1. For the Subscriber

subscribe(topic, URL)

Subscribe a URL to receive notifications sent to one topic

Authorization: notif.sub.write

Parameters:

• topic (str) – Topic

• URL (str) – URL to be called when a notification is available

Returns:

a subscription ID

This service is synchronous.

listSubscriptions()

Get all subscriptions

Authorization: notif.sub.read

Parameters:

URL (str) – URL to be called when a notification is available

Returns:

a subscription ID

This service is synchronous.

unsubscribe(id)

Unsubscribe a URL from the list of receiver for one topic

Authorization: notif.sub.write

Parameters:

id (str) – Subscription ID

Returns:

bool

This service is synchronous.

confirm(token)

Used to confirm that the URL used during the subscription is valid

Authorization: notif.sub.write

Parameters:

token (str) – A token send through the URL.

Returns:

bool

This service is synchronous.

5.1.1.2. For the Publisher

createTopic(topic)

Create a new topic. This is required before an event can be sent to it.

Authorization: notif.topic.write

Parameters:

topic (str) – Topic

Returns:

N/A

This service is synchronous.

listTopics()

Get the list of all existing topics.

Authorization: notif.topic.read

Returns:

N/A

This service is synchronous.

deleteTopic(topic)

Delete a topic.

Authorization: notif.topic.write

Parameters:

topic (str) – Topic

Returns:

N/A

This service is synchronous.

publish(topic, subject, message)

Notify of a new event all systems that subscribed to this topic

Authorization: notif.topic.publish

Parameters:

• topic (str) – Topic

• subject (str) – The subject of the message

• message (str) – The message itself (a string buffer)

Returns:

N/A

This service is asynchronous (systems that subscribed on this topic are notified asynchronously).

5.1.1.3. For the Receiver

notify(message)

Receive an event published by a publisher. This service needs to be registered through the subscription process.

Parameters:

message (str) – The message itself (a string buffer)

Returns:

N/A

5.1.2. Dictionaries

As an example, below there is a list of events that each component might handle.

Table 5.1 Event Type

Event Type	Emitted by CR	Emitted by PR
Live birth	✔
Death	✔
Fœtal Death	✔
Marriage	✔
Divorce	✔
Annulment	✔
Separation, judicial	✔
Adoption	✔
Legitimation	✔
Recognition	✔
Change of name	✔
Change of gender	✔
New person		✔
Duplicate person	✔	✔

5.2. Data Access

See Data Access for the technical details of this interface.

5.2.1. Services

readPersonAttributes(UIN, names)

Read person attributes.

Authorization: pr.person.read or cr.person.read

Parameters:

• UIN (str) – The person’s UIN

• names (list[str]) – The names of the attributes requested

Returns:

a list of pair (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

This service is synchronous. It can be used to retrieve attributes from CR or from PR.

Fig. 5.2 readPersonAttributes Sequence Diagram

---

matchPersonAttributes(UIN, attributes)

Match person attributes. This service is used to check the value of attributes without exposing private data. The implementation can use a simple comparison or a more advanced technique (for example: phonetic comparison for names)

Authorization: pr.person.match or cr.person.match

Parameters:

• UIN (str) – The person’s UIN

• attributes (list[(str,str)]) – The attributes to match. Each attribute is described with its name and the expected value

Returns:

If all attributes match, a Yes is returned. If one attribute does not match, a No is returned along with a list of (name,reason) for each non-matching attribute.

This service is synchronous. It can be used to match attributes in CR or in PR.

Fig. 5.3 matchPersonAttributes Sequence Diagram

---

verifyPersonAttributes(UIN, expressions)

Evaluate expressions on person attributes. This service is used to evaluate simple expressions on person’s attributes without exposing private data The implementation can use a simple comparison or a more advanced technique (for example: phonetic comparison for names)

Authorization: pr.person.verify or cr.person.verify

Parameters:

• UIN (str) – The person’s UIN

• expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of <, >, =, >=, <=) and the attribute value

Returns:

A Yes if all expressions are true, a No if one expression is false.

This service is synchronous. It can be used to verify attributes in CR or in PR.

Fig. 5.4 verifyPersonAttributes Sequence Diagram

---

queryPersonUIN(attributes, offset, limit)

Query the persons by a set of attributes. This service is used when the UIN is unknown. The implementation can use a simple comparison or a more advanced technique (for example: phonetic comparison for names)

Authorization: pr.person.read or cr.person.read

Parameters:

• attributes (list[(str,str)]) – The attributes to be used to find UIN. Each attribute is described with its name and its value

• offset (int) – The offset of the query (first item of the response) (optional, default to 0)

• limit (int) – The maximum number of items to return (optional, default to 100)

Returns:

a list of matching UIN

This service is synchronous. It can be used to get the UIN of a person.

Fig. 5.5 queryPersonUIN Sequence Diagram

---

queryPersonList(attributes, names, offset, limit)

Query the persons by a list of attributes and their values. This service is proposed as an optimization of a sequence of calls to queryPersonUIN() and readPersonAttributes().

Authorization: pr.person.read or cr.person.read

Parameters:

• attributes (list[(str,str)]) – The attributes to be used to find the persons. Each attribute is described with its name and its value

• names (list[str]) – The names of the attributes requested

• offset (int) – The offset of the query (first item of the response) (optional, default to 0)

• limit (int) – The maximum number of items to return (optional, default to 100)

Returns:

a list of lists of pairs (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

This service is synchronous. It can be used to retrieve attributes from CR or from PR.

Fig. 5.6 queryPersonList Sequence Diagram

---

readDocument(UINs, documentType, format)

Read in a selected format (PDF, image, …) a document such as a marriage certificate.

Authorization: pr.document.read or cr.document.read

Parameters:

• UIN (list[str]) – The list of UINs for the persons concerned by the document

• documentType (str) – The type of document (birth certificate, etc.)

• format (str) – The format of the returned/requested document

Returns:

The list of the requested documents

This service is synchronous. It can be used to get the documents for a person.

Fig. 5.7 readDocument Sequence Diagram

5.2.2. Dictionaries

As an example, below there is a list of attributes/documents that each component might handle.

Table 5.2 Person Attributes

Attribute Name	In CR	In PR
UIN	✔	✔
first name	✔	✔
last name	✔	✔
spouse name	✔	✔
date of birth	✔	✔
place of birth	✔	✔
gender	✔	✔
date of death	✔	✔
place of death	✔
reason of death	✔
status		✔

Table 5.3 Certificate Attributes

Attribute Name	In CR	In PR
officer name	✔
number	✔
date	✔
place	✔
type	✔

Table 5.4 Union Attributes

Attribute Name	In CR	In PR
date of union	✔
place of union	✔
conjoint1 UIN	✔
conjoint2 UIN	✔
date of divorce	✔

Table 5.5 Filiation Attributes

Attribute Name	In CR	In PR
parent1 UIN	✔
parent2 UIN	✔

Table 5.6 Document Type

Document Type
birth certificate
death certificate
marriage certificate

5.3. UIN Management

See UIN Management for the technical details of this interface.

5.3.1. Services

generateUIN(attributes, transactionID)

Generate a new UIN.

Authorization: uin.generate

Parameters:

• attributes (list[(str,str)]) – A list of pair (attribute name, value) that can be used to allocate a new UIN

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a new UIN or an error if the generation is not possible

This service is synchronous.

Fig. 5.8 generateUIN Sequence Diagram

5.4. Enrollment Services

This interface describes enrollment services in the context of an identity system. It is based on the following principles:

• When enrollment is done in one step, the CreateEnrollment can contain all the data and an additional flag (finalize) to indicate all data was collected.

• During the process, enrollment structure can be updated. Only the data that changed need to be transferred. Data not included is left unchanged on the server. In the following example, the biographic data is not changed.

• Images can be passed by value or reference. When passed by value, they are base64-encoded.

• Existing standards are used whenever possible, for instance preferred image format for biometric data is ISO-19794.

About documents

Adding one document or deleting one document implies that:

• The full document list is read (ReadEnrollment)

• The document list is altered locally to the enrollment client (add or delete)

• The full document list is sent back using the UpdateEnrollment service

5.4.1. Services

createEnrollment(enrollmentID, enrollmentTypeId, enrollmentFlags, requestData, contextualData, biometricData, biographicData, documentData, finalize, transactionID)

Insert a new enrollment.

Authorization: enroll.write

Parameters:

• enrollmentID (str) – The ID of the enrollment. If the enrollment already exists for the ID an error is returned.

• enrollmentTypeId (str) – The enrollment type ID of the enrollment.

• enrollmentFlags (dict) – The enrollment custom flags.

• requestData (dict) – The enrollment data related to the enrollment itself.

• contextualData (dict) – Information about the context of the enrollment

• biometricData (list) – The enrollment biometric data.

• biographicData (dict) – The enrollment biographic data.

• documentData (list) – The enrollment biometric data.

• finalize (str) – Flag to indicate that data was collected.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

readEnrollment(enrollmentID, attributes, transactionID)

Retrieve the attributes of an enrollment.

Authorization: enroll.read

Parameters:

• enrollmentID (str) – The ID of the enrollment.

• attributes (set) – The (optional) set of required attributes to retrieve.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error and in case of success the enrollment data.

updateEnrollment(enrollmentID, enrollmentTypeId, enrollmentFlags, requestData, contextualData, biometricData, biographicData, documentData, finalize, transactionID)

Update an enrollment.

Authorization: enroll.write

Parameters:

• enrollmentID (str) – The ID of the enrollment. If the enrollment already exists for the ID an error is returned.

• enrollmentTypeId (str) – The enrollment type ID of the enrollment.

• enrollmentFlags (dict) – The enrollment custom flags.

• requestData (dict) – The enrollment data related to the enrollment itself.

• contextualData (dict) – Information about the context of the enrollment

• biometricData (list) – The enrollment biometric data, this can be partial data.

• biographicData (dict) – The enrollment biographic data.

• documentData (list) – The enrollment biometric data, this can be partial data.

• finalize (str) – Flag to indicate that data was collected.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

partialupdateEnrollment(enrollmentID, enrollmentTypeId, enrollmentFlags, requestData, contextualData, biometricData, biographicData, documentData, finalize, transactionID)

Update part of an enrollment. Not all attributes are mandatory. The payload is defined as per RFC 7396.

Authorization: enroll.write

Parameters:

• enrollmentID (str) – The ID of the enrollment. If the enrollment already exists for the ID an error is returned.

• enrollmentTypeId (str) – The enrollment type ID of the enrollment.

• enrollmentFlags (dict) – The enrollment custom flags.

• requestData (dict) – The enrollment data related to the enrollment itself.

• contextualData (dict) – Information about the context of the enrollment

• biometricData (list) – The enrollment biometric data, this can be partial data.

• biographicData (dict) – The enrollment biographic data.

• documentData (list) – The enrollment biometric data, this can be partial data.

• finalize (str) – Flag to indicate that data was collected.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

finalizeEnrollment(enrollmentID, transactionID)

When all the enrollment steps are done, the enrollment client indicates to the enrollment server that all data has been collected and that any further processing can be triggered.

Authorization: enroll.write

Parameters:

• enrollmentID (str) – The ID of the enrollment.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

deleteEnrollment(enrollmentID, transactionID)

Deletes the enrollment

Authorization: enroll.write

Parameters:

• enrollmentID (str) – The ID of the enrollment.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

findEnrollments(expressions, offset, limit, transactionID)

Retrieve a list of enrollments which match passed in search criteria.

Authorization: enroll.read

Parameters:

• expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of <, >, =, >=, <=) and the attribute value

• offset (int) – The offset of the query (first item of the response) (optional, default to 0)

• limit (int) – The maximum number of items to return (optional, default to 100)

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error and in case of success the matching enrollment list.

createBuffer(enrollmentId, data, digest)

This service is used to send separately the buffers of the images. Buffers can be sent any time from the enrollment client prior to the create or update.

Authorization: enroll.buf.write

Parameters:

• enrollmentID (str) – The ID of the enrollment.

• data (image) – The buffer data.

• transactionID (string) – The client generated transactionID.

• digest (string) – The digest (hash) of the buffer used by the server to check the integrity of the data received.

Returns:

a status indicating success or error and in case of success the buffer ID.

readBuffer(enrollmentId, bufferId)

This service is used to get the data of a buffer.

Authorization: enroll.buf.read

Parameters:

• enrollmentID (str) – The ID of the enrollment.

• bufferID (str) – The ID of the buffer.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error and in case of success the data of the buffer and a digest.

5.4.2. Attributes

The “attributes” parameter used in “read” calls is used to provide a set of identifiers that limit the amount of data that is returned. It is often the case that the whole data set is not required, but instead, a subset of that data. Where possible, existing standards based identifiers should be used for the attributes to retrieve.

E.g. For surname/familyname, use OID 2.5.4.4 or id-at-surname.

Some calls may require new attributes to be defined. E.g. when retrieving biometric data, the caller may only want the meta data about that biometric, rather than the actual biometric data.

5.4.3. Transaction ID

The transactionID is a string provided by the client application to identity the request being submitted. It can be used for tracing and debugging.

5.4.4. Data Model

Table 5.7 Enrollment Data Model

Type	Description	Example(s)
Enrollment	The full set of data which are captured for one purpose.	N/A
Document Data	The documents used as an element of proof for part of the enrollment data.	Birth certificate, invoice.
Biometric Data	Digital representation of biometric characteristics. All images can be passed by value (image buffer is in the request) or by reference (the address of the image is in the request). All images are compliant with ISO 19794. ISO 19794 allows multiple encoding and supports additional metadata specific to fingerprint, palmprint, portrait, iris or signature. A biometric data can be associated to no image or a partial image if it includes information about the missing items (example: one finger may be amputated on a 4 finger image)	fingerprint, portrait, iris, signature
Biographic Data	A dictionary (list of names and values) giving the biographic data of the identity	firstName, lastName, dateOfBirth, etc.
Enrollment Flags	a dictionary (list of names and values) for custom flags controlling the enrollment process.	maximum time allowed to finish the enrollment, etc.
Request Data	a dictionary (list of names and values) for data related to the process initiated by the enrollment.	type of request, priority of execution, type of credential to produce, etc.
Contextual Data	A dictionary (list of names and values) for data related to the enrollment itself	operatorName, enrollmentDate, etc.
Attributes	Generic name for any information collected during an enrollment. Attributes can apply on biographic data, document data, request data, or enrollment flag data.	firstName, lastName, enrollmentDate, etc.
Expressions	An expression combines an attribute’s name, an operator (one of <, >, =, >=, <=, !=) and a value. It is used in search services.	firstName=John

Fig. 5.9 Enrollment Data Model

5.5. Population Registry Services

This interface describes services to manage a registry of the population in the context of an identity system. It is based on the following principles:

• It supports a history of identities, meaning that a person has one identity and this identity has a history.

• Images can be passed by value or reference. When passed by value, they are base64-encoded.

• Existing standards are used whenever possible.

• This interface is complementary to the data access interface. The data access interface is used to query the persons and uses the reference identity to return attributes.

• The population registry can store the biometric data or can rely on the ABIS subsystem to do it. The preferred solution, for a clean separation of data of different nature and by application of GDPR principles, is to put the biometric data only in the ABIS. Yet many existing systems store biometric data with the biographic data and this specification gives the flexibility to do it.

See Population Registry Management for the technical details of this interface.

5.5.1. Services

findPersons(expressions, group, reference, gallery, offset, limit, transactionID)

Retrieve a list of persons which match passed in search criteria.

Authorization: pr.person.read

Parameters:

• expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of <, >, =, >=, <=) and the attribute value

• group (bool) – Group the results per person and return only personID

• reference (bool) – Limit the query to the reference identities

• gallery (string) – A gallery ID used to limit the search

• offset (int) – The offset of the query (first item of the response) (optional, default to 0)

• limit (int) – The maximum number of items to return (optional, default to 100)

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error and in case of success the matching person list.

createPerson(personID, personData, transactionID)

Create a new person.

Authorization: pr.person.write

Parameters:

• personID (str) – The ID of the person. If the person already exists for the ID an error is returned.

• personData – The person attributes.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

readPerson(personID, transactionID)

Read the attributes of a person.

Authorization: pr.person.read

Parameters:

• personID (str) – The ID of the person.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error and in case of success the person data.

updatePerson(personID, personData, transactionID)

Update a person.

Authorization: pr.person.write

Parameters:

• personID (str) – The ID of the person.

• personData (dict) – The person data.

Returns:

a status indicating success or error.

deletePerson(personID, transactionID)

Delete a person and all its identities.

Authorization: pr.person.write

Parameters:

• personID (str) – The ID of the person.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

mergePerson(personID1, personID2, transactionID)

Merge two person records into a single one. Identity ID are preserved and in case of duplicates an error is returned and no changes are done. The reference identity is not changed.

Authorization: pr.person.write

Parameters:

• personID1 (str) – The ID of the person that will receive new identities

• personID2 (str) – The ID of the person that will give its identities. It will be deleted if the move of all identities is successful.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

---

createIdentity(personID, identityID, identity, transactionID)

Create a new identity in a person. If no identityID is provided, a new one is generated. If identityID is provided, it is checked for uniqueness and used for the identity if unique. An error is returned if the provided identityID is not unique.

Authorization: pr.identity.write

Parameters:

• personID (str) – The ID of the person.

• identityID (str) – The ID of the identity.

• identity – The new identity data.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

readIdentity(personID, identityID, transactionID)

Read one or all the identities of one person.

Authorization: pr.identity.read

Parameters:

• personID (str) – The ID of the person.

• identityID (str) – The ID of the identity. If not provided, all identities are returned.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error, and in case of success a list of identities.

updateIdentity(personID, identityID, identity, transactionID)

Update an identity. An identity can be updated only in the status claimed.

Authorization: pr.identity.write

Parameters:

• personID (str) – The ID of the person.

• identityID (str) – The ID of the identity.

• identity – The identity data.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

partialUpdateIdentity(personID, identityID, identity, transactionID)

Update part of an identity. Not all attributes are mandatory. The payload is defined as per RFC 7396. An identity can be updated only in the status claimed.

Authorization: pr.identity.write

Parameters:

• personID (str) – The ID of the person.

• identityID (str) – The ID of the identity.

• identity – Part of the identity data.

Returns:

a status indicating success or error.

deleteIdentity(personID, identityID, transactionID)

Delete an identity.

Authorization: pr.identity.write

Parameters:

• personID (str) – The ID of the person.

• identityID (str) – The ID of the identity.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

setIdentityStatus(personID, identityID, status, transactionID)

Set an identity status.

Authorization: pr.identity.write

Parameters:

• personID (str) – The ID of the person.

• identityID (str) – The ID of the identity.

• status (str) – The new status of the identity.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

---

defineReference(personID, identityID, transactionID)

Define the reference identity of one person.

Authorization: pr.reference.write

Parameters:

• personID (str) – The ID of the person.

• identityID (str) – The ID of the identity being now the reference.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

readReference(personID, transactionID)

Read the reference identity of one person.

Authorization: pr.reference.read

Parameters:

• personID (str) – The ID of the person.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error and in case of success the reference identity.

---

readGalleries(transactionID)

Read the ID of all the galleries.

Authorization: pr.gallery.read

Parameters:

transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error, and in case of success a list of gallery ID.

readGalleryContent(galleryID, transactionID, offset, limit)

Read the content of one gallery, i.e. the IDs of all the records linked to this gallery.

Authorization: pr.gallery.read

Parameters:

• galleryID (str) – Gallery whose content will be returned.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• offset (int) – The offset of the query (first item of the response) (optional, default to 0)

• limit (int) – The maximum number of items to return (optional, default to 1000)

Returns:

a status indicating success or error. In case of success a list of person/identity IDs.

5.5.2. Data Model

Table 5.8 Population Registry Data Model

Type	Description	Example
Gallery	A group of persons related by a common purpose, designation, or status. A person can belong to multiple galleries.	VIP, Wanted, etc.
Person	Person who is known to an identity assurance system. A person record has: a status, such as active or inactive, defining the status of the record (the record can be excluded from queries based on this status), a physical status, such as alive or dead, defining the status of the person, a set of identities, keeping track of all identity data submitted by the person during the life of the system, a reference identity, i.e. a consolidated view of all the identities defining the current correct identity of the person. It corresponds usually to the last valid identity but it can also include data from previous identities.	N/A
Identity	The attributes describing an identity of a person. An identity has a status such as: claimed (identity not yet validated), valid (the identity is valid), invalid (the identity is confirmed as not valid), revoked (the identity cannot be used any longer). An identity can be updated only in the status claimed. The proposed transitions for the status are represented below. It can be adapted if needed. The attributes are separated into two categories: the biographic data and the contextual data.	N/A
Biographic Data	A dictionary (list of names and values) giving the biographic data of the identity	firstName, lastName, dateOfBirth, etc.
Contextual Data	A dictionary (list of names and values) attached to the context of establishing the identity	operatorName, enrollmentDate, etc.
Biometric Data	Digital representation of biometric characteristics. All images can be passed by value (image buffer is in the request) or by reference (the address of the image is in the request). All images are compliant with ISO 19794. ISO 19794 allows multiple encoding and supports additional metadata specific to fingerprint, palmprint, portrait, iris or signature. A biometric data can be associated to no image or a partial image if it includes information about the missing items (example: one finger may be amputated on a 4 finger image)	fingerprint, portrait, iris, signature
Document	The document data (images) attached to the identity and used to validate it.	Birth certificate, invoice

Fig. 5.10 Population Registry Data Model

5.6. Biometrics

This interface describes biometric services in the context of an identity system. It is based on the following principles:

• It supports only multi-encounter model, meaning that an identity can have multiple set of biometric data, one for each encounter.

• It does not expose templates (only images) for CRUD services, with one exception to support the use case of credentials with biometrics.

• Images can be passed by value or reference. When passed by value, they are base64-encoded.

• Existing standards are used whenever possible, for instance preferred image format for biometric data is ISO-19794.

About synchronous and asynchronous processing

Some services can be very slow depending on the algorithm used, the system workload, etc. Services are described so that:

• If possible, the answer is provided synchronously in the response of the service.

• If not possible for some reason, a status PENDING is returned and the answer, when available, is pushed to a callback provided by the client.

If no callback is provided, this indicates that the client wants a synchronous answer, whatever the time it takes.

If a callback is provided, this indicates that the client wants an asynchronous answer, even if the result is immediately available.

See Biometrics for the technical details of this interface.

5.6.1. Services

createEncounter(personID, encounterID, galleryID, biographicData, contextualData, biometricData, clientData, callback, transactionID, options)

Create a new encounter. No identify is performed.

Authorization: abis.encounter.write

Parameters:

• personID (str) – The person ID. This is optional and will be generated if not provided

• encounterID (str) – The encounter ID. This is optional and will be generated if not provided

• galleryID (list(str)) – the gallery ID to which this encounter belongs. A minimum of one gallery must be provided

• biographicData (dict) – The biographic data (ex: name, date of birth, gender, etc.)

• contextualData (dict) – The contextual data (ex: encounter date, location, etc.)

• biometricData (list) – the biometric data (images)

• clientData (bytes) – additional data not interpreted by the server but stored as is and returned when encounter data is requested.

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority, algorithm.

Returns:

a status indicating success, error, or pending operation. In case of success, the person ID and the encounter ID are returned. In case of pending operation, the result will be sent later.

readEncounter(personID, encounterID, callback, transactionID, options)

Read the data of an encounter.

Authorization: abis.encounter.read

Parameters:

• personID (str) – The person ID

• encounterID (str) – The encounter ID. This is optional. If not provided, all the encounters of the person are returned.

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. In case of success, the encounter data is returned. In case of pending operation, the result will be sent later.

updateEncounter(personID, encounterID, galleryID, biographicData, contextualData, biometricData, callback, transactionID, options)

Update an encounter.

Authorization: abis.encounter.write

Parameters:

• personID (str) – The person ID

• encounterID (str) – The encounter ID

• galleryID (list(str)) – the gallery ID to which this encounter belongs. A minimum of one gallery must be provided

• biographicData (dict) – The biographic data (ex: name, date of birth, gender, etc.)

• contextualData (dict) – The contextual data (ex: encounter date, location, etc.)

• biometricData (list) – the biometric data (images)

• clientData (bytes) – additional data not interpreted by the server but stored as is and returned when encounter data is requested.

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority, algorithm.

Returns:

a status indicating success, error, or pending operation. In case of success, the person ID and the encounter ID are returned. In case of pending operation, the result will be sent later.

deleteEncounter(personID, encounterID, callback, transactionID, options)

Delete an encounter.

Authorization: abis.encounter.write

Parameters:

• personID (str) – The person ID

• encounterID (str) – The encounter ID. This is optional. If not provided, all the encounters of the person are deleted.

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. In case of pending operation, the operation status will be sent later.

mergeEncounter(personID1, personID2, callback, transactionID, options)

Merge two sets of encounters into a single set. Merging a set of N encounters with a set of M encounters will result in a single set of N+M encounters. Encounter ID are preserved and in case of duplicates an error is returned and no changes are done.

Authorization: abis.encounter.write

Parameters:

• personID1 (str) – The ID of the person that will receive new encounters

• personID2 (str) – The ID of the person that will give its encounters

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. In case of pending operation, the result will be sent later.

moveEncounter(personID1, personID2, encounterID, callback, transactionID, options)

Move one single encounter from one person to another person. Encounter ID is preserved and in case of duplicates an error is returned and no changes are done.

Authorization: abis.encounter.write

Parameters:

• personID1 (str) – The ID of the person that will receive the encounter

• personID2 (str) – The ID of the person that will give one encounter

• encounterID (str) – the ID of the encounter in personID2 that will be moved in personID1.

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. In case of pending operation, the result will be sent later.

readTemplate(personID, encounterID, biometricType, biometricSubType, templateFormat, qualityFormat, callback, transactionID, options)

Read the generated template.

Authorization: abis.encounter.read

Parameters:

• personID (str) – The person ID

• encounterID (str) – The encounter ID.

• biometricType (str) – The type of biometrics to consider (optional)

• biometricSubType (str) – The subtype of biometrics to consider (optional)

• templateFormat (str) – the format of the template to return (optional)

• qualityFormat (str) – the format of the quality to return (optional)

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. In case of success, a list of template data is returned. In case of pending operation, the result will be sent later.

updateEncounterStatus(personID, encounterID, status, transactionID)

Set an encounter status.

Authorization: abis.encounter.write

Parameters:

• personID (str) – The ID of the person.

• encounterID (str) – The encounter ID.

• status (str) – The new status of the encounter.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

updateEncounterGalleries(personID, encounterID, galleries, transactionID)

Update the galleries of an encounter. This service is used to move one encounter from one gallery to another one without updating the full encounter, which maybe resource consuming in a biometric system.

Authorization: abis.encounter.write

Parameters:

• personID (str) – The ID of the person.

• encounterID (str) – The encounter ID.

• galleries (list[str]) – The new list of galleries for this encounter.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

Returns:

a status indicating success or error.

---

readGalleries(callback, transactionID, options)

Read the ID of all the galleries.

Authorization: abis.gallery.read

Parameters:

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. A list of gallery ID is returned, either synchronously or using the callback.

readGalleryContent(galleryID, callback, transactionID, offset, limit, options)

Read the content of one gallery, i.e. the IDs of all the records linked to this gallery.

Authorization: abis.gallery.read

Parameters:

• galleryID (str) – Gallery whose content will be returned.

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• offset (int) – The offset of the query (first item of the response) (optional, default to 0)

• limit (int) – The maximum number of items to return (optional, default to 1000)

• options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. A list of persons/encounters is returned, either synchronously or using the callback.

---

identify(galleryID, filter, biometricData, callback, transactionID, options)

Identify a person using biometrics data and filters on biographic or contextual data. This may include multiple operations, including manual operations.

Authorization: abis.identify

Parameters:

• galleryID (str) – Search only in this gallery.

• filter (dict) – The input data (filters and biometric data)

• biometricData – the biometric data.

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority, maxNbCand, threshold, accuracyLevel.

Returns:

a status indicating success, error, or pending operation. A list of candidates is returned, either synchronously or using the callback.

identify(galleryID, filter, personID, callback, transactionID, options)

Identify a person using biometrics data of a person existing in the system and filters on biographic or contextual data. This may include multiple operations, including manual operations.

Authorization: abis.verify

Parameters:

• galleryID (str) – Search only in this gallery.

• filter (dict) – The input data (filters and biometric data)

• personID – the person ID

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority, maxNbCand, threshold, accuracyLevel.

Returns:

a status indicating success, error, or pending operation. A list of candidates is returned, either synchronously or using the callback.

identify(galleryID, filter, personID, encounterID, callback, transactionID, options)

Identify a person using biometrics data of an encounter existing in the system and filters on biographic or contextual data. This may include multiple operations, including manual operations.

Authorization: abis.verify

Parameters:

• galleryID (str) – Search only in this gallery.

• filter (dict) – The input data (filters and biometric data)

• personID – the person ID

• encounterID – the encounter ID

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority, maxNbCand, threshold, accuracyLevel.

Returns:

a status indicating success, error, or pending operation. A list of candidates is returned, either synchronously or using the callback.

verify(galleryID, personID, biometricData, callback, transactionID, options)

Verify an identity using biometrics data.

Authorization: abis.verify

Parameters:

• galleryID (str) – Search only in this gallery. If the person does not belong to this gallery, an error is returned.

• personID (str) – The person ID

• biometricData – The biometric data

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority, threshold, accuracyLevel.

Returns:

a status indicating success, error, or pending operation. A status (boolean) is returned, either synchronously or using the callback. Optionally, details about the matching result can be provided like the score per biometric and per encounter.

verify(biometricData1, biometricData2, callback, transactionID, options)

Verify that two sets of biometrics data correspond to the same person.

Authorization: abis.verify

Parameters:

• biometricData1 – The first set of biometric data

• biometricData2 – The second set of biometric data

• callback – The address of a service to be called when the result is available.

• transactionID (str) – A free text used to track the system activities related to the same transaction.

• options (dict) – the processing options. Supported options are priority, threshold, accuracyLevel.

Returns:

a status indicating success, error, or pending operation. A status (boolean) is returned, either synchronously or using the callback. Optionally, details about the matching result can be provided like the score per the biometric.

5.6.2. Options

Table 5.9 Biometric Services Options

Name	Description
priority	Priority of the request. Values range from 0 to 9. 0 indicates the lowest priority, 9 indicates the highest priority.
maxNbCand	The maximum number of candidates to return.
threshold	The threshold to apply on the score to filter the candidates during an identification, authentication or verification.
algorithm	Specify the type of algorithm to be used.
accuracyLevel	Specify the accuracy expected of the request. This is to support different use cases, when different behavior of the ABIS is expected (response time, accuracy, consolidation/fusion, etc.).

5.6.3. Data Model

Table 5.10 Biometric Data Model

Type	Description	Example
Gallery	A group of persons related by a common purpose, designation, or status. A person can belong to multiple galleries.	VIP, Wanted, etc.
Person	Person who is known to an identity assurance system.	N/A
Encounter	Event in which the client application interacts with a person resulting in data being collected during or about the encounter. An encounter is characterized by an identifier and a type (also called purpose in some context). An encounter has a status indicating if this encounter is used in the biometric searches. Allowed values are active or inactive.	N/A
Biographic Data	A dictionary (list of names and values) giving the biographic data of interest for the biometric services. This should be as limited as possible.	gender, region, yearOfBirth
Filters	A dictionary (list of names and values or range of values) describing the filters during a search. Filters can apply on biographic data, contextual data or encounter type.	gender, yearOfBirthMin, yearOfBirthMax
Biometric Data	Digital representation of biometric characteristics. All images can be passed by value (image buffer is in the request) or by reference (the address of the image is in the request). All images are compliant with ISO 19794. ISO 19794 allows multiple encoding and supports additional metadata specific to fingerprint, palmprint, portrait, iris or signature. A biometric data can be associated to no image or a partial image if it includes information about the missing items (example: one finger may be amputated on a 4 finger image)	fingerprint, portrait, iris, signature
Candidate	Information about a candidate found during an identification	personId
CandidateScore	Detailed information about a candidate found during an identification. It includes the score for the biometrics used. It can also be extended with proprietary information to better describe the matching result (for instance: rotation needed to align the probe and the candidate)	3000
Template	A computed buffer corresponding to a biometric and allowing the comparison of biometrics. A template has a format that can be a standard format or a vendor-specific format.	N/A

Fig. 5.11 Biometric Data Model

5.7. Credential Services

This interface describes services to manage credentials and credential requests in the context of an identity system.

5.7.1. Services

createCredentialRequest(personID, credentialProfileID, additionalData, transactionID)

Request issuance of a secure credential.

Authorization: cms.request.write

Parameters:

• personID (str) – The ID of the person.

• credentialProfileID (str) – The ID of the credential profile to issue to the person.

• additionalData (dict) – Additional data relating to the requested credential profile, e.g. credential lifetime if overriding default, delivery addresses, etc.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error. In the case of success, a credential request identifier.

readCredentialRequest(credentialRequestID, attributes, transactionID)

Retrieve the data/status of a credential request.

Authorization: cms.request.read

Parameters:

• credentialRequestID (str) – The ID of the credential request.

• attributes (set) – The (optional) set of required attributes to retrieve.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error, and in case of success the issuance data/status.

updateCredentialRequest(credentialRequestID, additionalData, transactionID)

Update the requested issuance of a secure credential.

Authorization: cms.request.write

Parameters:

• credentialRequestID (str) – The ID of the credential request.

• transactionID (string) – The client generated transactionID.

• additionalData (dict) – Additional data relating to the requested credential profile, e.g. credential lifetime if overriding default, delivery addresses, etc.

Returns:

a status indicating success or error.

cancelCredentialRequest(credentialRequestID, transactionID)

Cancel the requested issuance of a secure credential.

Authorization: cms.request.write

Parameters:

• credentialRequestID (str) – The ID of the credential request.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

---

findCredentials(expressions, transactionID)

Retrieve a list of credentials that match the passed in search criteria.

Authorization: cms.credential.read

Parameters:

• expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of <, >, =, >=, <=) and the attribute value.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error, in the case of success the list of matching credentials.

readCredential(credentialID, attributes, transactionID)

Retrieve the attributes/status of an issued credential. A wide range of information may be returned, dependant on the type of credential that was issued, smart card, mobile, passport, etc.

Authorization: cms.credential.read

Parameters:

• credentialID (str) – The ID of the credential.

• attributes (set) – The (optional) set of required attributes to retrieve.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error, in the case of success the requested data will be returned.

suspendCredential(credentialID, additionalData, transactionID)

Suspend an issued credential. For electronic credentials this will suspend any PKI certificates that are present.

Authorization: cms.credential.write

Parameters:

• credentialID (str) – The ID of the credential.

• additionalData (dict) – Additional data relating to the request, e.g. reason for suspension.

• transactionID (string) – The (optional) client generated transactionID.

Returns:

a status indicating success or error.

unsuspendCredential(credentialID, additionalData, transactionID)

Unsuspend an issued credential. For electronic credentials this will unsuspend any PKI certificates that are present.

Authorization: cms.credential.write

Parameters:

• credentialID (str) – The ID of the credential.

• additionalData (dict) – Additional data relating to the request, e.g. reason for unsuspension.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

revokeCredential(credentialID, additionalData, transactionID)

Revoke an issued credential. For electronic credentials this will revoke any PKI certificates that are present.

Authorization: cms.credential.write

Parameters:

• credentialID (str) – The ID of the credential.

• additionalData (dict) – Additional data relating to the request, e.g. reason for revocation.

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

setCredentialStatus(credentialID, status, reason, requester, comment, transactionID)

Change the status of a credential. This is an extension of the revoke/suspend services, supporting more statuses and transitions.

Authorization: cms.credential.write

Parameters:

• credentialID (str) – The ID of the credential.

• status (string) – The new status of the credential

• reason (string) – A text describing the cause of the change of status

• requester (string) – The client generated transactionID.

• comment (string) – A free text comment

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

---

findCredentialProfiles(expressions, transactionID)

Retrieve a list of credential profils that match the passed in search criteria

Authorization: cms.profile.read

Parameters:

• expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of <, >, =, >=, <=, !=) and the attribute value

• transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error, and in case of success the matching credential profile list.

5.7.2. Attributes

The “attributes” parameter used in “read” calls is used to provide a set of identifiers that limit the amount of data that is returned. It is often the case that the whole data set is not required, but instead, a subset of that data.

Some calls may require new attributes to be defined. E.g. when retrieving biometric data, the caller may only want the meta data about that biometric, rather than the actual biometric data.

5.7.3. Data Model

Table 5.11 Credential Data Model

Type	Description	Example
Credential	The attributes of the credential itself The proposed transitions for the status are represented below. It can be adapted if needed.	ID, status, dates, serial number
Biometric Data	Digital representation of biometric characteristics. All images can be passed by value (image buffer is in the request) or by reference (the address of the image is in the request). All images are compliant with ISO 19794. ISO 19794 allows multiple encoding and supports additional metadata specific to fingerprint, palmprint, portrait, iris or signature. A biometric data can be associated to no image or a partial image if it includes information about the missing items (example: one finger may be amputated on a 4 finger image)	fingerprint, portrait, iris, signature
Biographic Data	a dictionary (list of names and values) giving the biographic data of interest for the biometric services.	first name, last name, date of birth, etc.
Request Data	a dictionary (list of names and values) for data related to the request itself.	Type of credential, action to execute, priority

Fig. 5.12 Credential Data Model

5.8. ID Usage

ID Usage consists of a set of services implemented on top of identity systems to favour third parties consumption of identity data. The services can be classified in three sets:

• Relying Party API: submitting citizen ID attributes for validation

  The purpose of the Relying Party (RP) API is to extend the use of government-issued identity to registered third party services. The individual will submit their ID attributes to the relying party in order to enroll for, or access, a particular service. The relying party will leverage the RP API to access the identity management system and verify the individual’s identity. In this way, external relying parties can quickly and easily verify individuals based on their government issued ID attributes.

  Use case applications: telco enrollment

  The RP API enables a telco operator to check an individual’s identity when applying for a service contract. The telco relies on the government to confirm that the attributes submitted by the individual match against the data held in the database therefore being able to confidently identify the new subscriber. This scenario can be replicated across multiple sectors including banking and finance.

• Digital Credential Management API: delegating digital issuance to third parties (out of scope for the specification v6.1.0)

  The purpose of the Digital Credential Management (DCM) API is to enable external wallet providers to manage government issued digital credentials distribution, storage and usage.

  Use case applications: digital driver license

  The DCM API enables individuals to request a digital driver license as a digital credential in their selected wallet to use for online and offline identification. The user initiates a request for digital driver license using the Digital Credential Distribution System (DCDS) frontend, which sends the request to the identity management system. The Credential Management System (CMS) then issues the digital credential by dedicated API endpoint of the DCDS.

• Federation API: user-initiated attributes sharing

  The purpose of the federation API is to enable the user to share their attributes with a chosen relying party using well-known internet protocol: OpenID Connect. The relying party benefits from the government’s verified attributes.

  Use case applications: on-line registration to gambling website

  The Federation API enables individuals to log-in with their government credential (log-in/password) and share verified attributes ex. age (above 18) with the relying party.

5.8.1. Relying Party API

verifyIdentity(Identifier, attributeSet)

Verify an Identity based on an identifier (UIN, token…) and a set of Identity Attributes. Verification is strictly matching all provided identity attributes to compute the global Boolean matching result.

Authorization: id.verify

Parameters:

• Identifier (str) – The person’s Identifier

• attributeSet (list[str]) – A set of identity attributes associated to the identifier and to be verified by the system

Returns:

Y or N

In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

identify(attributeSet, outputAttributeSet)

Identify possibly matching identities against an input set of attributes. Returns an array of predefined datasets as described by outputAttributeSet.

Note: This service may be limited to some specific government RPs

Authorization: id.identify

Parameters:

• attributeSet (list[str]) – A list of pair (name,value) requested

• outputAttributeSet (list[str]) – An array of attributes requested

Returns:

Y or N

In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

readAttributes(Identifier, outputAttributeSet)

Get a list of identity attributes attached to a given identifier.

Authorization: id.read

Parameters:

• Identifier (str) – The person’s Identifier

• outputAttributeSet (list[str]) – defining the identity attributes to be provided back to the caller

Returns:

An array of the requested attributes

In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

readAttributeSet(Identifier, AttributeSetName)

Get a set of identity attributes as defined by attributeSet, attached to a given identifier.

Authorization: id.set.read

Parameters:

• Identifier (str) – The person’s Identifier

• attributeSetName (str) – The name of predefined attributes set name

Returns:

An array of the requested attributes

In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

5.8.2. Attribute set

When identity attributes are exchanged, they are included in an attribute set, possibly containing groups like biographic data, biometric data, document data, contact data… This structure is extensible and may be complemented with other data groups, and each group may contain any number of attribute name / attribute value pairs.

5.8.3. Attribute set name

Attribute sets are by definition structures with variable and optional content, hence it may be useful to pre-agree on a given attribute set content and name between two or more systems in a given project scope.

Any string may be used to define an attribute set name, but in the scope of this specification following names are reserved and predefined:

Name	Description	Data Included
“DEFAULT_SET_01”	Minimum demographic data	First name Last name DoB Place of birth
“DEFAULT_SET_02”	Minimum demographic and portrait	Minimum demographic data + portrait
“DEFAULT_SET_EIDAS”	Set expected to comply with eIDAS pivotal attributes [1].	Mandatory attributes: First name Last name DoB Identifier Optional attributes: Birth name Place of birth Gender Current address

5.8.4. Output Attribute set

To specify what identity attributes are expected in return when performing e.g. an identify request or a read attributes.

[1]

eIDAS SAML Attribute Profile