7.8. ID Usage Services¶
7.8.1. Relying Party Services¶
This is version 1.1.1 of this interface.
Get the OpenAPI file: rp.yaml
7.8.1.1. Services¶
- POST /v1/verify/{identifier}¶
Verify a set of attributes of a person.
Verify an Identity based on an identity identifier (UIN, token…) and a set of Identity Attributes. Verification is strictly matching all provided identity attributes to compute the global Boolean matching result.
Scope required:
id.verify
- Parameters:
identifier (string) – person identifier. Object of type string.
- Query Parameters:
identifierType (string) – Type of identifier (default “uin”, “token”, “credentialNumber”, …). Object of type string.
verificationProofRequired (boolean) – verification proof required on successful verification (default true). Object of type boolean.
transactionId (string) – The client specified id of the transaction. Object of type string. (Required)
- Form Parameters:
body – A set of identity attributes associated to the identity identifier and to be verified by the system. Object of type AttributeSet.
- Status Codes:
200 OK – Verification execution successful. Object of type VerifyResult.
400 Bad Request – Bad Request, Validation Errors, … Object of type Error.
401 Unauthorized – Unauthorized.
403 Forbidden – Operation not allowed.
404 Not Found – Identifier not Found.
500 Internal Server Error – Internal server error. Object of type Error.
Example request:
POST /v1/verify/1235567890?identifierType=token&verificationProofRequired=true&transactionId=string HTTP/1.1 Host: example.com Content-Type: application/json { "biographicData": { "firstName": "John", "lastName": "Doo", "dateOfBirth": "1985-11-30", "gender": "M", "nationality": "FRA", "...": "..." }, "biometricData": [ { "biometricType": "FINGER", "biometricSubType": "RIGHT_INDEX", "instance": "string", "image": "c3RyaW5n", "imageRef": "http://imageserver.com/image?id=00003", "captureDate": "2019-05-21T12:00:00Z", "captureDevice": "string", "impressionType": "LIVE_SCAN_PLAIN", "width": 1, "height": 1, "bitdepth": 1, "mimeType": "string", "resolution": 1, "compression": "WSQ", "missing": [ { "biometricSubType": "RIGHT_INDEX", "presence": "BANDAGED" } ], "metadata": "string", "comment": "string", "template": "c3RyaW5n", "templateRef": "http://dataserver.com/template?id=00014", "templateFormat": "string", "quality": 1, "qualityFormat": "string", "algorithm": "string", "vendor": "string" } ], "credentialData": [ { "credentialNumber": "string", "personId": "string", "credentialType": "ID_CARD", "issuedDate": "2024-03-05T10:43:26.549244", "expiryDate": "2024-03-05T10:43:26.549244", "serialNumber": "string", "issuingAuthority": "string", "issuingPlace": "string", "others": { "...": "..." } } ], "contactData": { "email": "John.Doo@osia.com", "phone1": "555666777", "phone2": "555888999", "...": "..." } }
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "verificationCode": 1, "verificationMessage": "string", "verificationProof": "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/attributes/{attributeSetName}/{identifier}¶
Read a predefined set of a person’s attributes.
Note security role must map the requested attributeSetName, e.g. id.DEFAULT_SET_01.read
Scope required:
id.ATTRIBUTESETNAME.read
- Parameters:
attributeSetName (string) – Predefined attribute set name describing what attributes are to be read. e.g. “DEFAULT_SET_01”, “SET_BIOM_01”, “EIDAS”, … Object of type string.
identifier (string) – person identifier. Object of type string.
- Query Parameters:
identifierType (string) – Type of identifier (default “uin”, “token”, “credentialNumber”, …). Object of type string.
transactionId (string) – The client specified id of the transaction. Object of type string. (Required)
- Status Codes:
200 OK – Operation successful, AttributeSet will contain fields as predefined by the attributeSetName and when value is available. Object of type AttributeSet.
400 Bad Request – Bad Request, Validation Errors, … Object of type Error.
401 Unauthorized – Unauthorized.
403 Forbidden – Operation not allowed.
404 Not Found – Not Found.
500 Internal Server Error – Internal server error. Object of type Error.
Example request:
GET /v1/attributes/DEFAULT_SET_01/1235567890?identifierType=token&transactionId=string HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "biographicData": { "firstName": "John", "lastName": "Doo", "dateOfBirth": "1985-11-30", "gender": "M", "nationality": "FRA", "...": "..." }, "biometricData": [ { "biometricType": "FINGER", "biometricSubType": "RIGHT_INDEX", "instance": "string", "encounterId": "string", "image": "c3RyaW5n", "imageRef": "http://imageserver.com/image?id=00003", "captureDate": "2019-05-21T12:00:00Z", "captureDevice": "string", "impressionType": "LIVE_SCAN_PLAIN", "width": 1, "height": 1, "bitdepth": 1, "mimeType": "string", "resolution": 1, "compression": "WSQ", "missing": [ { "biometricSubType": "RIGHT_INDEX", "presence": "BANDAGED" } ], "metadata": "string", "comment": "string", "template": "c3RyaW5n", "templateRef": "http://dataserver.com/template?id=00014", "templateFormat": "string", "quality": 1, "qualityFormat": "string", "algorithm": "string", "vendor": "string" } ], "credentialData": [ { "credentialId": "string", "status": "NEW", "statusOther": "string", "credentialNumber": "string", "personId": "string", "credentialType": "ID_CARD", "issuedDate": "2024-03-05T10:43:26.549244", "expiryDate": "2024-03-05T10:43:26.549244", "serialNumber": "string", "issuingAuthority": "string", "issuingPlace": "string", "others": { "...": "..." } } ], "contactData": { "email": "John.Doo@osia.com", "phone1": "555666777", "phone2": "555888999", "...": "..." } }
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/attributes/{identifier}¶
Read a variable set of a person’s attributes.
Returns value of attributes listed in the request parameter ‘OutputAttributeSet’
Scope required:
id.read
- Parameters:
identifier (string) – person identifier. Object of type string.
- Query Parameters:
identifierType (string) – Type of identifier (default “uin”, “token”, “credentialNumber”, …). Object of type string.
transactionId (string) – The client specified id of the transaction. Object of type string. (Required)
- Form Parameters:
body – A description of expected identity attributes. Object of type OutputAttributeSet.
- Status Codes:
200 OK – Operation successful, AttributeSet will contain fields as defined by parameter outputAttributeSet and when value is available. Object of type AttributeSet.
400 Bad Request – Bad Request, Validation Errors, … Object of type Error.
401 Unauthorized – Unauthorized.
403 Forbidden – Operation not allowed.
404 Not Found – Not Found.
500 Internal Server Error – Internal server error. Object of type Error.
Example request:
POST /v1/attributes/1235567890?identifierType=token&transactionId=string HTTP/1.1 Host: example.com Content-Type: application/json { "outputBiographicData": [ "string" ], "outputBiometricData": [ { "biometricType": "FINGER", "biometricSubType": "RIGHT_INDEX", "biometricDataFields": [ "string" ] } ], "outputCredentialData": [ { "credentialType": "ID_CARD", "credentialDataFields": [ "string" ] } ], "outputContactData": [ "string" ] }
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "biographicData": { "firstName": "John", "lastName": "Doo", "dateOfBirth": "1985-11-30", "gender": "M", "nationality": "FRA", "...": "..." }, "biometricData": [ { "biometricType": "FINGER", "biometricSubType": "RIGHT_INDEX", "instance": "string", "encounterId": "string", "image": "c3RyaW5n", "imageRef": "http://imageserver.com/image?id=00003", "captureDate": "2019-05-21T12:00:00Z", "captureDevice": "string", "impressionType": "LIVE_SCAN_PLAIN", "width": 1, "height": 1, "bitdepth": 1, "mimeType": "string", "resolution": 1, "compression": "WSQ", "missing": [ { "biometricSubType": "RIGHT_INDEX", "presence": "BANDAGED" } ], "metadata": "string", "comment": "string", "template": "c3RyaW5n", "templateRef": "http://dataserver.com/template?id=00014", "templateFormat": "string", "quality": 1, "qualityFormat": "string", "algorithm": "string", "vendor": "string" } ], "credentialData": [ { "credentialId": "string", "status": "NEW", "statusOther": "string", "credentialNumber": "string", "personId": "string", "credentialType": "ID_CARD", "issuedDate": "2024-03-05T10:43:26.549244", "expiryDate": "2024-03-05T10:43:26.549244", "serialNumber": "string", "issuingAuthority": "string", "issuingPlace": "string", "others": { "...": "..." } } ], "contactData": { "email": "John.Doo@osia.com", "phone1": "555666777", "phone2": "555888999", "...": "..." } }
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/identify¶
Identify a set of persons matching provided partial attributes
Identify possibly matching identities against an input set of attributes. Returns an array of predefined datasets as described by outputDataSetName. Note this request may be asynchronous or synchronous.
Scope required:
id.identify
- Query Parameters:
transactionId (string) – The client specified id of the transaction. Object of type string. (Required)
- Form Parameters:
body – A set of identity attributes to match and an attributeSetName to use as template for returned matching identities. Object of type IdentifyRequest.
- Status Codes:
200 OK – Identification request execution successful. Array of AttributeSet.
202 Accepted – Request received successfully and correct, result will be available later using the task ID returned. Object of type TaskId.
400 Bad Request – Bad Request, Validation Errors, … Object of type Error.
401 Unauthorized – Unauthorized.
403 Forbidden – Operation not allowed.
404 Not Found – Identifier not Found.
500 Internal Server Error – Internal server error. Object of type Error.
Example request:
POST /v1/identify?transactionId=string HTTP/1.1 Host: example.com Content-Type: application/json { "attributeSet": { "biographicData": { "firstName": "John", "lastName": "Doo", "dateOfBirth": "1985-11-30", "gender": "M", "nationality": "FRA", "...": "..." }, "biometricData": [ { "biometricType": "FINGER", "biometricSubType": "RIGHT_INDEX", "instance": "string", "image": "c3RyaW5n", "imageRef": "http://imageserver.com/image?id=00003", "captureDate": "2019-05-21T12:00:00Z", "captureDevice": "string", "impressionType": "LIVE_SCAN_PLAIN", "width": 1, "height": 1, "bitdepth": 1, "mimeType": "string", "resolution": 1, "compression": "WSQ", "missing": [ { "biometricSubType": "RIGHT_INDEX", "presence": "BANDAGED" } ], "metadata": "string", "comment": "string", "template": "c3RyaW5n", "templateRef": "http://dataserver.com/template?id=00014", "templateFormat": "string", "quality": 1, "qualityFormat": "string", "algorithm": "string", "vendor": "string" } ], "credentialData": [ { "credentialNumber": "string", "personId": "string", "credentialType": "ID_CARD", "issuedDate": "2024-03-05T10:43:26.549244", "expiryDate": "2024-03-05T10:43:26.549244", "serialNumber": "string", "issuingAuthority": "string", "issuingPlace": "string", "others": { "...": "..." } } ], "contactData": { "email": "John.Doo@osia.com", "phone1": "555666777", "phone2": "555888999", "...": "..." } }, "outputAttributeSetName": "DEFAULT_SET_01" }
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "biographicData": { "firstName": "John", "lastName": "Doo", "dateOfBirth": "1985-11-30", "gender": "M", "nationality": "FRA", "...": "..." }, "biometricData": [ { "biometricType": "FINGER", "biometricSubType": "RIGHT_INDEX", "instance": "string", "encounterId": "string", "image": "c3RyaW5n", "imageRef": "http://imageserver.com/image?id=00003", "captureDate": "2019-05-21T12:00:00Z", "captureDevice": "string", "impressionType": "LIVE_SCAN_PLAIN", "width": 1, "height": 1, "bitdepth": 1, "mimeType": "string", "resolution": 1, "compression": "WSQ", "missing": [ { "biometricSubType": "RIGHT_INDEX", "presence": "BANDAGED" } ], "metadata": "string", "comment": "string", "template": "c3RyaW5n", "templateRef": "http://dataserver.com/template?id=00014", "templateFormat": "string", "quality": 1, "qualityFormat": "string", "algorithm": "string", "vendor": "string" } ], "credentialData": [ { "credentialId": "string", "status": "NEW", "statusOther": "string", "credentialNumber": "string", "personId": "string", "credentialType": "ID_CARD", "issuedDate": "2024-03-05T10:43:26.549244", "expiryDate": "2024-03-05T10:43:26.549244", "serialNumber": "string", "issuingAuthority": "string", "issuingPlace": "string", "others": { "...": "..." } } ], "contactData": { "email": "John.Doo@osia.com", "phone1": "555666777", "phone2": "555888999", "...": "..." } } ]
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "taskId": "123e4567-e89b-12d3-a456-426655440000", "others": { "...": "..." } }
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/identify/{taskID}¶
Read the result of a previously sent identify request
Scope required:
id.identify
- Parameters:
taskID (string) – taskID to get result for. Object of type string.
- Query Parameters:
transactionId (string) – The client specified id of the transaction. Object of type string. (Required)
- Status Codes:
200 OK – Operation successful, array of AttributeSet is available. Array of AttributeSet.
204 No Content – No content, taskID is valid but identify request is still ongoing, retry later.
400 Bad Request – Bad Request, Validation Errors, … Object of type Error.
401 Unauthorized – Unauthorized.
403 Forbidden – Operation not allowed.
404 Not Found – Not Found.
500 Internal Server Error – Internal server error. Object of type Error.
Example request:
GET /v1/identify/ABCDEFGHIJKLMNO?transactionId=string HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "biographicData": { "firstName": "John", "lastName": "Doo", "dateOfBirth": "1985-11-30", "gender": "M", "nationality": "FRA", "...": "..." }, "biometricData": [ { "biometricType": "FINGER", "biometricSubType": "RIGHT_INDEX", "instance": "string", "encounterId": "string", "image": "c3RyaW5n", "imageRef": "http://imageserver.com/image?id=00003", "captureDate": "2019-05-21T12:00:00Z", "captureDevice": "string", "impressionType": "LIVE_SCAN_PLAIN", "width": 1, "height": 1, "bitdepth": 1, "mimeType": "string", "resolution": 1, "compression": "WSQ", "missing": [ { "biometricSubType": "RIGHT_INDEX", "presence": "BANDAGED" } ], "metadata": "string", "comment": "string", "template": "c3RyaW5n", "templateRef": "http://dataserver.com/template?id=00014", "templateFormat": "string", "quality": 1, "qualityFormat": "string", "algorithm": "string", "vendor": "string" } ], "credentialData": [ { "credentialId": "string", "status": "NEW", "statusOther": "string", "credentialNumber": "string", "personId": "string", "credentialType": "ID_CARD", "issuedDate": "2024-03-05T10:43:26.549244", "expiryDate": "2024-03-05T10:43:26.549244", "serialNumber": "string", "issuingAuthority": "string", "issuingPlace": "string", "others": { "...": "..." } } ], "contactData": { "email": "John.Doo@osia.com", "phone1": "555666777", "phone2": "555888999", "...": "..." } } ]
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.8.1.2. Data Model¶
7.8.1.2.1. AttributeSet¶
a set of attributes used in verify
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
Object of type BiographicData |
The set of biographic data. |
|
|
Array of BiometricData |
||
|
Array of CredentialData |
||
|
Object of type ContactData |
7.8.1.2.2. BiographicData¶
The set of biographic data.
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
Additional properties |
Example #1:
{
"firstName": "John",
"lastName": "Doo",
"dateOfBirth": "1985-11-30",
"gender": "M",
"nationality": "FRA"
}
7.8.1.2.3. ContactData¶
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
Additional properties |
Example #1:
{
"email": "John.Doo@osia.com",
"phone1": "555666777",
"phone2": "555888999"
}
7.8.1.2.4. BiometricData¶
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
string |
Constraints: possible values are |
Yes |
|
string |
Constraints: possible values are |
|
|
string |
Used to separate two distincts biometric items of the same type and subtype. |
|
|
string |
the id of the encounter owner of this biometric. Constraints: read only |
|
|
string/byte |
Base64-encoded image. |
|
|
string/uri |
URI to an image. |
|
|
string/date-time |
||
|
string |
A string identifying the device used to capture the biometric. |
|
|
string |
Constraints: possible values are |
|
|
integer |
the width of the image. |
|
|
integer |
the height of the image. |
|
|
integer |
||
|
string |
the nature and format of the image. The mime type definitions should be in compliance with RFC 6838. |
|
|
integer |
the image resolution (in DPI). |
|
|
string |
Constraints: possible values are |
|
|
Array of MissingType |
Optional properties indicating if a part of the biometric data is missing. |
|
|
string |
An optional string used to convey information vendor-specific. |
|
|
string |
A comment about the biometric data. |
|
|
string/byte |
Base64-encoded template. |
|
|
string/uri |
URI to the template when it is managed in a dedicated data server. |
|
|
string |
Format of the template. One of ISO_19794_2, ISO_19794_2_NS, ISO_19794_2_CS, ISO_19794_2_2011, ANSI_378_2009 or ANSI_378. Can be extended to include additional proprietary template format |
|
|
integer/int64 |
Quality, as a number, of the biometric. |
|
|
string |
Format of the quality. One of ISO_19794, NFIQ, or NFIQ2. Can be extended to include additional proprietary quality format |
|
|
string |
||
|
string |
7.8.1.2.5. MissingType¶
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
string |
Constraints: possible values are |
|
|
string |
Constraints: possible values are |
7.8.1.2.6. CredentialData¶
A credential
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
string |
The unique id for this credential. Constraints: read only |
|
|
string |
The status of the credential. Constraints: possible values are |
|
|
string |
Details about the status when OTHER is used. Constraints: read only |
|
|
string |
The number attached to the credential (ex: passport number). |
|
|
string |
The unique id of the person that the credential request is for. |
|
|
string |
Type of the credential. e.g. “PASSPORT”, “ID_CARD”, … |
|
|
string/date-time |
The date and time that this credential was issued. |
|
|
string/date-time |
The date and time that this credential expires. |
|
|
string |
the serial number of the credential. |
|
|
string |
The authority issuing the credential (ex: the Ministry of Interior). |
|
|
string |
The place where the credential was issued (ex: Paris). |
|
|
Additional properties |
7.8.1.2.7. Error¶
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
integer/int32 |
Error code. |
Yes |
|
string |
Error message. |
Yes |
7.8.1.2.8. VerifyResult¶
result of a successful verify request
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
integer/int64 |
Yes |
|
|
string |
Yes |
|
|
string |
7.8.1.2.9. IdentifyRequest¶
a set of parameters used in identify
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
Object of type AttributeSet |
a set of attributes used in verify. |
Yes |
|
string |
Attribute set name describing what attributes are to be read. e.g. “DEFAULT_SET_01”, “SET_BIOM_01”, “EIDAS”, … |
Yes |
7.8.1.2.10. OutputAttributeSet¶
A template describing the expected attributes of a readAttributes request
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
Array of string |
list of BiographicData structure fields to include in the answer. |
|
|
Array |
an array of expected biometric data & fields. |
|
|
string |
Constraints: possible values are |
|
|
string |
Constraints: possible values are |
|
|
Array of string |
||
|
Array |
an array of expected credential type & fields. |
|
|
string |
Type of the credential. e.g. “PASSPORT”, “ID_CARD”, … |
|
|
Array of string |
||
|
Array of string |
list of ContactData structure fields to include in the answer. |
7.8.1.2.11. TaskId¶
Information about the asynchronous result. Only the taskId is mandatory but the implementation is free to return additional details such as: expected duration, URL to monitor the task, etc.
Attribute |
Type |
Description |
Required |
---|---|---|---|
|
string |
Yes |
|
|
Additional properties |