Validate customer

info

This is a draft version of the SME Onboarding APIs. The final version is expected to be released by the end of September. The API specifications are subjected to go through a few more changes before the final version is released.

Validate Customer API validates the customer's information collected during the SME account-opening journey.

The API uses the customer's ID Number, mobile number, SME Unified Number, date of birth, calendar type, and OTP to perform the required validation.

A successful validation response can also provide customer and corporate address information along with verification statuses returned by the underlying banking and verification services.

Important information

Call Validate Customer after successfully generating the OTP.
Submit the OTP entered by the customer together with the required identity and SME information.
Proceed to Manage User only after receiving a successful validation response.
If validation fails, use StatusDetail to determine the appropriate error handling and customer experience.

Domain details

Environment	Domain	Rate/Limit
Sandbox	sandboxapi.onesingleview.com	3 Calls per Minute
Production/LIVE	To be provided upon onboarding	Based on contract

Endpoint

Endpoint	Method	Authentication requirements
`/api/v2/smeonboarding/validatecustomer`	POST	Header SVReferenceID CompanyId Device DateTimeStamp Access token Request body Signature

Method

Authentication requirements

/api/v2/smeonboarding/validatecustomer

POST

Header

SVReferenceID
CompanyId
Device
DateTimeStamp
Access token

Request body

Signature

Sample request

Validate Customer Request

curl --location 'https://sandboxapi.onesingleview.com/api/v2/smeonboarding/validatecustomer' \
--header 'SVReferenceID:  SV123456' \
--header 'CompanyId: SINGLEVIEW1234' \
--header 'Device: web' \
--header 'DateTimeStamp: 2025-01-07T10:20:39' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiTDNyMmpxV29JS2I4MTNodDBNeVN4WFRCZjlqUlNWQzFad3B5QnlkOVpHelZXR2ZwUmFQNUUrY3d6cVQ5bi9OV0lwR2V5STNNMkdPL1pqakd4ZG0yclJkVEZxY3lhWGNpWnZFejl0V1EySjQxK2VvSlk2ZjdJZkFsV3BKRi9VL1YydDEzMUtnRnVhcnd6MzVQY1UzbnFEV0p0UWlzIiwiaWF0IjoxNzY3NzYxODc3LCJleHAiOjE3Njc3NjU0Nzd9.lWDSB3Rk_TtdUbKyFcCdaE5XGo7UDiTu2kDcqEyU7vg' \
--header 'Content-Type: application/json' \
--data '{
"Message": {
  "ValidateCustomerRequest": {
    "IdNumber": "1650613233",
    "MobileNumber": "966561231699",
    "UnifiedNumber": "7002965167",
    "CalenderType": "2",
    "DateOfBirth": "09/09/1409",
    "OTP": "2356"
    }
  },
"Signature": "rZZ9alg/2k9B5uWSdnW3AfYswAMqA4HXyNX3jIzckWb4o37uS4eKFEQ3xRn/dBarN6EGjfaXiMSOPdKyyjjrgT80K5ReXzQ7cC1INuU79ozlLgK8yTFz+nq785geQ+He4PR+hD35DkF9qnela9qmcr3GhAXpTjZG12hmaJEyzeofh6q3p+jqLFd208eAImubnL6SbSBDEAi5SLRH1K2I1U77OmFNirrfGV8qd+gsi+lqgyF9mpNj6lzy/fJNNe0qEr2WHvG1R7E2g3EhqovDNanQt6RFgkWegtlE37Eyi5qO3xlTqu76317ZWfMI7jHxs48fOLTNtBCOwUboVze5Tw=="
}'

Request parameters

JSON Tag	Requirement	Description	Data type
ValidateCustomerRequest	Mandatory	Root node containing information to request to validate customer information	Object
IdNumber	Mandatory	Customer's Iqama/ID number	String
MobileNumber	Mandatory	Customer mobile number along	String
UnifiedNumber	Mandatory	SME's Commercial Registration (CR) Unified Number	String
CalenderType	Mandatory	Calendar type used for the customer's date of birth to be mentioned as: `1` = Gregorian `2` = Hijri	String
DateOfBirth	Mandatory	Customer's date of birth in the format applicable to the selected calendar type	String
OTP	Mandatory	OTP received by the customer through the Generate OTP step	String

Sample response

Validate Customer Response

{
  "ValidateCustomerResponse": {
    "StatusCode": "Completed",
    "StatusDetail": "Validation process completed.",
    "TimeStamp": "2026-08-27T07:16:54"
  },
  "Data": {
    "Citizen": {
      "Addresses": [
        {
          "Street": "Murabba",
          "CityCode": "TAIF",
          "AdditionalNumber": "3434",
          "District": "Malaz",
          "PostalCode": "12345",
          "BuildingNumber": "6649",
          "UnitNumber": "2239",
          "CityNameEnglish": "Taif",
          "CityNameArabic": "شسي"
        }
      ]
    },
    "Corp": {
      "Addresses": [
        {
          "Street": "Murabba",
          "CityCode": "TAIF",
          "AdditionalNumber": "3434",
          "District": "Malaz",
          "PostalCode": "12345",
          "BuildingNumber": "6649",
          "UnitNumber": "2239",
          "CityNameEnglish": "Taif",
          "CityNameArabic": "شسي"
        }
      ]
    },
    "WathiqStatus": "active",
    "TahaqouqStatus": "true",
    "CustomerCode": "NO",
    "YakeenStatus": "success"
  }
}

Response parameters

JSON Tag	Description	Data type
ValidateCustomerResponse	Root node containing information of response for validation of customer information	Object
StatusCode	Code representing status of the transaction in the request	String
StatusDetail	Details of the status code represented for the transaction in the request	String
TimeStamp	Time and date of the response	String
Data	Tag carrying information about the customer and corporation	Object
Citizen	Customer-related information returned by the validation service	Object
Corp	Corporate/SME information returned by the validation service	Object
Street	Name of the street	String
CityCode	City code	String
AdditionalNumber	Additional address number	String
District	District name	String
PostalCode	Postal code	String
BuildingNumber	Building number	String
UnitNumber	Unit or apartment number	String
CityNameEnglish	City name in English	String
CityNameArabic	City name in Arabic	String
WathiqStatus	Wathiq verification status specified as `active` or `inactive`	String
TahaqouqStatus	Tahaqouq verification status specified as `true` or `false`	String
CustomerCode	Customer status returned by the service specified as: `YES` - Existing customer `NO` - New customer	String
YakeenStatus	Yakeen verification status specified as `success` or `failed`	String

Status codes & information

StatusCode	StatusDetail
Completed	Validation process completed.
Failed	Bank response description
Response_Timeout	Timeout! Unable to get response from the bank. Please try again or contact SingleView support if issue persists.

Categories

GENERAL INFORMATION

GETTING STARTED

AUTHENTICATION

Data APIs

Payment APIs

SADAD

Virtual Accounts

SME Onboarding (Draft)

RESOURCES

API Archives

Domain details

Endpoint

Sample request

Sample response

Status codes & information