Registration
Digital Identity API - Registration
The Digital Identity API delivers a secure and robust solution for seamless user registration and verification.
Key Features
Ensures the authenticity of user-provided information.
Verifies email addresses and phone numbers.
With this API, you can manage user identities while ensuring a high level of security and trust.
💼 Transaction Flow
Check existence of the user
Verify if the email and phone already exist in the system.
Phone Verification
Request OTP: Send an OTP to the provided phone number.
Verify OTP: Validate the OTP entered by the user.
Use the
phoneNumberOtpRequestIdreturned from this step in subsequent requests.
Email Verification
Request OTP: Send an OTP to the provided email address.
Verify OTP: Validate the OTP entered by the user.
Use the
EmailNumberOtpRequestIdreturned from this step in subsequent requests.
Create User
Create the user with the verified phone number email.
Ensure the
phoneNumberOtpRequestIdandEmailNumberOtpRequestIdfrom the previous steps is used to maintain the transaction flow.
⚠️ Note: Always use the phoneNumberOtpRequestId and EmailNumberOtpRequestId returned from each step in subsequent requests.
Create a new user
The process can be summarized in the flow chart below.
Step1 - Check existence
One call to confirm whether the phone number or the email address has been used before for the same tenant.
Note: You can enter one of the two parameters in request body, but sending none of them should lead to an error.
Success
POST /api/DigitalIdentity/CheckExistenceOfEmailOrPhone HTTP/1.1
Host:
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 47
{
"email": "[email protected]",
"phoneNumber": "text"
}Success
{
"data": {
"isEmailExists": true,
"isPhoneNumberExists": true
},
"error_code": 1,
"error_message": "text",
"error_descriptions": null
}Step2 - Verify phone number
Two step process to verify phone number ownership
Call request OTP: in this step we only need the phoneNumber parameter to request the OTP verification. In response to this API call, the response body has a "phoneNumberOtpRequestId" parameter, this should be used in the next step.
Verify the OTP: calling the same endpoint with two additional parameters in the request body.
phoneNumberOtpRequestId: UUID received from the previous API call.
phoneNumberOtp: the six-digit OTP received via SMS by the registered phone number.
^\+[1-9]{1}[0-9]{1,14}$Success
POST /api/DigitalIdentity/Register/StepVerifyPhone HTTP/1.1
Host:
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 153
{
"phoneNumber": "text",
"phoneNumberOtp": "text",
"phoneNumberOtpRequestId": "text",
"transactionId": "123e4567-e89b-12d3-a456-426614174000",
"returnUrl": "text"
}Success
{
"data": {
"phoneNumberOtpRequestId": "123e4567-e89b-12d3-a456-426614174000",
"phoneOtpExpireInSeconds": 1,
"isPhoneNumberConfirmed": true,
"transactionId": "123e4567-e89b-12d3-a456-426614174000"
},
"error_code": 1,
"error_message": "text",
"error_descriptions": null
}Step 3 - Verify email (Optional)
Just like the phone number, we need to validate the Email address of the end-user. The process is typically the same, although it is not mandatory on registration.
If you want to skip this step, you can go directly to Step 4 directly and add a skipEmail param to the request body with value "true".
Keep in mind, you need to register and validate the Email address before you proceed with business request creation.
Two step process for email verification
Request OTP for email
Verify the OTP
Success
POST /api/DigitalIdentity/Register/StepVerifyEmail HTTP/1.1
Host:
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 135
{
"email": "text",
"emailOtp": "text",
"emailOtpRequestId": "text",
"transactionId": "123e4567-e89b-12d3-a456-426614174000",
"returnUrl": "text"
}Success
{
"data": {
"emailOtpRequestId": "123e4567-e89b-12d3-a456-426614174000",
"emailOtpExpireInSeconds": 1,
"isEmailConfirmed": true,
"transactionId": "123e4567-e89b-12d3-a456-426614174000"
},
"error_code": null,
"error_message": "text"
}Step 4 - Create user
Finalize user registration after successful phone and email (If provided) verification
The first step is to send an OTP to the email address. The request body should contain "email". The second step is to verify the OTP. The request body should contain "email", "emailOtp" and "emailOtpRequestId".
^\+[1-9]{1}[0-9]{1,14}$Success
POST /api/DigitalIdentity/Register/StepCreate HTTP/1.1
Host:
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 262
{
"password": "text",
"emailOtpRequestId": "text",
"phoneNumberOtpRequestId": "text",
"geoLocation": {
"latitude": 1,
"longitude": 1
},
"imei": "text",
"imsi": "text",
"phoneNumber": "text",
"skipEmail": true,
"transactionId": "123e4567-e89b-12d3-a456-426614174000",
"returnUrl": "text"
}Success
{
"data": {
"isPhoneNumberConfirmed": true,
"isEmailConfirmed": true,
"accessToken": "text",
"refreshToken": "text",
"user": {
"id": 1,
"name": "text",
"surname": "text",
"fullName": "text",
"userName": "text",
"emailAddress": "text",
"phoneNumber": "text",
"idNumber": "text",
"address": "text"
},
"transactionId": "123e4567-e89b-12d3-a456-426614174000"
},
"error_code": 1,
"error_message": "text",
"error_descriptions": null
}🔐 OTP Handling
⚠️ Error Handling
Last updated