QERDS identification and registration

Definition

The following information defines the API call developed to identify and register users in our QERDS service without the need to send a first communication.

Customer requests through the API call that we initiate a registration process of a user with mandatory data (name, surname and email) in the QERDS qualified notifications service, once registered in the service, the customer may send through the general API (EviNoticeSubmit) or the web portal certified communications to that user.

^{Request Method : PUT}

^{Request URL : https://verifid.ecertia.com/api/v1/Enrollments}

^{Authentication : This API requires via an API key. They key must be included in the request header.}

Request Headers

Header Name	Value	Description

Header Name	Value	Description
X-VerifiD-ApiToken	your_api_key_here	The API key for authenticating the request

Request Body

List of Parameters

Field	Type	Description	Example

Field	Type	Description	Example
Profile	string	Required profile to identify how to enroll the user	Bit4Id::SPIDOnly::Customer
Language	string	Language preference for UI and documents to be generated on enrollment. Typically uses ISO 639-1 codes.	it
Email	string	The email address of the user. Must be a valid email format.	j.doe@namirial.com
FirstName	string	The first name of the user.	John
LastName	string	The last name of the user.	Doe
ReturnUrl	string	The URL to which the user will be redirected after enrollment. Must be a valid URL.	https://customer.com/{id}/enroll

Example of request in JSON

{
"Profile": "Bit4Id::SPIDOnly::Customer",
"Language": "it",
"Email": "j.doe@namirial.com",
"FirstName": "John",
"LastName": "Doe",
"ReturnUrl": "https://customer.com/{id}/enroll/"

}

Request Response

Status 200 OK

Example of response in JSON

{
"Id": "018fa01b-1c42-4588-90da-dcaa52a8a236",
"Kinds": ["Email"],
"State": "New",
"Outcome": null,
"Name": "John",
"LastName": "Doe",
"DocumentNumber": null,
"Email": "j.doe@namirial.com",
"Phone": null,
"Language": "it",
"Provider": "bit4id",

"Consumer": "Customer",
"IdentificationUrl": null,
"EnrollUrl": "https://verifid.ecertia.com/enrollment/start/018fa01b-1c42-4588-90da-dcaa52a8a236",
"ReturnUrl": "https://customer.com/a9474480-ffbe-4382-b2f0-9a7d7592fec2/enroll"
}

Response Schema

Field	Type	Description	Example

Field	Type	Description	Example
Id	string	Unique identifier for the enrollment	018fa01b-1c42-4588-90da-dcaa52a8a236
Kinds	array	Types of communication channels added on the enrollment (Email, Phone).	["Email"]
State	string	Current state of the enrollment process.	New
Outcome	string	Outcome of the enrollment process, if available.	null
Name	string	First name of the user.	John
LastName	string	Last name of the user.	Doe
DocumentNumber	string	Document number associated with the user, if available.	null
Email	string	Email address of the user.	j.doe@namirial.com
Phone	string	Phone number of the user, if available.	null
Language	string	Language preference of the enrollment process	it
Provider	string	Identity provider that will validate the enrollment.	bit4id
IdentificationUrl	string	Identification Provider URL to start the identification, if available.	null
EnrollUrl	string	Landing URL for starting the enrollment process.	https://verifid.ecertia.com/enrollment/start/018fa01b-1c42-4588-90da-dcaa52a8a236
ReturnUrl more info at the bottom	string	URL to which the user will be redirected after enrollment. Result will be informed on "verifidResult" querystring param OK => https://customer.com/{customerid}/enroll?verifidResult=success KO => https://customer.com/{customerid}/enroll?verifidResult=error&verifidError=UnexpectedFailure	I.e. https://customer.com/{customerid}/enroll

Status 401 Unauthorized

Example of response in JSON

{
"Type": "https://verif.id/error/-authn",
"Title": "There was a problem authenticating the request",
"Details": "Authentication failed: bad token."
}

Status 400 Bad Request

Example of response in JSON

{
"Type": "https://verif.id/error/-bad-request",
"Title": "The request is invalid",
"Details": "Bit4Id::SPIDOnly::Customer can't enroll requests with an empty lastname"
}

Status 503 Service Unavailable

Example of response in JSON

{
"Type": "https://verif.id/error/-service-unavailable",
"Title": "The server is currently unable to handle the request",
"Details": "Problems found trying to contact with OnBoarding Today API"
}

Return URL

^{https://{returnUrl}?{verifIdResult=}&{verifIdError=}}

QueryString Values:

verifidResult (string) : success | error
verifidError (string) : errorcode

verifidError Codes

Code	Description

Code	Description
NotSupportedDocument	Identity Document provided during validation is not supported
RequestAlteredInfo	Provided verification info as been altered during OnBoarding process
RequestIsExpired	Current request is expired
RequestInvalidInfo	Enrollment request data is not correct
UnexpectedFailure	Unexpected failure while processing the Enrollment
OnBoardingProviderError	Problems occured with Onboarding Provider
PdfValidationError	Pdf Certificate validation has failed