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

1. Check existence of the user

   • Verify if the email and phone already exist in the system.

2. Phone Verification

   • Request OTP: Send an OTP to the provided phone number.

   • Verify OTP: Validate the OTP entered by the user.

   • Use the phoneNumberOtpRequestId returned from this step in subsequent requests.

3. Email Verification

   • Request OTP: Send an OTP to the provided email address.

   • Verify OTP: Validate the OTP entered by the user.

   • Use the EmailNumberOtpRequestId returned from this step in subsequent requests.

4. Create User

   • Create the user with the verified phone number email.

   • Ensure the phoneNumberOtpRequestId and EmailNumberOtpRequestId from 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.

post

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

emailstring · email · nullableOptional

phoneNumberstring · nullableOptional

Responses

200

Success

text/plainapplication/jsontext/json

post

/api/DigitalIdentity/CheckExistenceOfEmailOrPhone

HTTPcURLJavaScriptPython

POST /api/DigitalIdentity/CheckExistenceOfEmailOrPhone HTTP/1.1
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 47

{
  "email": "[email protected]",
  "phoneNumber": "text"
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

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

1. 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.

2. 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.

post

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

phoneNumberstringRequiredPattern: ^\+[1-9]{1}[0-9]{1,14}$

phoneNumberOtpstring · nullableOptional

phoneNumberOtpRequestIdstring · nullableOptional

transactionIdstring · uuidOptional

returnUrlstring · nullableOptional

Responses

200

Success

text/plainapplication/jsontext/json

post

/api/DigitalIdentity/Register/StepVerifyPhone

HTTPcURLJavaScriptPython

POST /api/DigitalIdentity/Register/StepVerifyPhone HTTP/1.1
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 153

{
  "phoneNumber": "text",
  "phoneNumberOtp": "text",
  "phoneNumberOtpRequestId": "text",
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "returnUrl": "text"
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

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

1. Request OTP for email

2. Verify the OTP

post

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

emailstringRequired

emailOtpstring · nullableOptional

emailOtpRequestIdstring · nullableOptional

transactionIdstring · uuidOptional

returnUrlstring · nullableOptional

Responses

200

Success

text/plainapplication/jsontext/json

post

/api/DigitalIdentity/Register/StepVerifyEmail

HTTPcURLJavaScriptPython

POST /api/DigitalIdentity/Register/StepVerifyEmail HTTP/1.1
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 135

{
  "email": "text",
  "emailOtp": "text",
  "emailOtpRequestId": "text",
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "returnUrl": "text"
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

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

If the user skipped adding an email during the account creation process but later needs to submit a business request, they must first add and verify their email. This endpoint is used to verify the user's email by validating the OTP sent to their email address.

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

post

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

passwordstringRequired

emailOtpRequestIdstring · nullableOptional

phoneNumberOtpRequestIdstring · nullableOptional

imeistringRequired

imsistring · nullableOptional

phoneNumberstring · nullableOptionalPattern: ^\+[1-9]{1}[0-9]{1,14}$

skipEmailbooleanOptional

transactionIdstring · uuidOptional

returnUrlstring · nullableOptional

Responses

200

Success

text/plainapplication/jsontext/json

post

/api/DigitalIdentity/Register/StepCreate

HTTPcURLJavaScriptPython

POST /api/DigitalIdentity/Register/StepCreate HTTP/1.1
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"
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

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

• Phone and email verification involve two API calls each:

  1. Request OTP.

  2. Verify OTP.

• OTPs have an expiration time. Check the OtpExpireInSeconds field in responses.

• Resend OTP if expired by making a new OTP request call.

⚠️ Error Handling

All endpoints return a standardized error object with an error_code and error_message in case of failures. Always check these fields for proper error handling in your application.

🌍 Geolocation and IMEI

• The CreateUser endpoint requires geolocation data. Ensure you have user consent before collecting and sending this information.

• The IMEI is used for device identification. Make sure you comply with local regulations regarding the collection and use of IMEI numbers.