Saudi Arabia KYB Async API

Overview

Saudi Arabia KYB is a product created for the verification of businesses that are registered in the Kingdom of Saudi Arabia. The details of businesses are fetched by using the CR (commercial registration number). A commercial registration number is an authorised, unique identifier assigned by the Ministry of Commerce of KSA.

The Saudi Arabia KYB is designed to be an asynchronous API; therefore, there are two API that are combined to give the details of the requested CR number.

First API: Saudi Arabia Business Fetch API

Endpoint: saudi-business-number-fetch

Inputs: The API inputs are the CR number and a callback URL. This api initiates the request for getting the details of the provided CR number.

Output: The API outputs the request id as output in successful request. This request ID can be used to track the output from the second. The ID is useful if the client does not have available callback url service

Second API: Saudi Arabia Business Get Data API

Endpoint: /saudi-business-number-get-data

Inputs: The API takes a request ID as input, i.e. the output by the first API is the input for the second API. This request ID can be used by the client to get the details fetched for the initial inputs.

Output: The output provided the API completes the process to get details for a given CR number. The output includes the business details present for the given CR. The details of fields in the output is discussed below.

API Specification

1. Saudi Arabia Business Fetch API

Curl

curl --location 'https://api.signzy.ae/api/v3/uae/saudi-business-number-fetch' \
--header 'Authorization: <auth-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "businessNumber": "sample business number",
    "callbackUrl": "sample callback url"
}'

businessNumber Input Field Regex :

The businessNumber that is CR (Commercial Registration) number should have a length of 10 digits, from 0 to 9.

Sucess Response

{
  "result":{
     "requestId":"6818aaa6674f29f6b6a3c923"
   }
}

Description Table

Field	Description	Data Type
requestId	Tracking ID, that is generated for the requested CR number we want to check	string

Failure Responses

{
	"error": {
		"name": "error",
		"message": "Bad Request. Callback url is invalid.",
		"status": 400,
		"reason": "VALIDATION_ERROR",
		"type": "Bad Request",
		"statusCode": "400"
	}
}

2. Saudi Arabia Business Get Data API

Curl

curl --location 'https://api-preproduction.signzy.app/api/v3/uae/saudi-business-number-get-data' \
--header 'Authorization: <auth token>' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "0000a9add9feaf999df100a9"
}'

Success Response

{
	"result": {
		"businessNameArabic": "شركة كريدي اجريكول سي اي بي العربية المالية",
		"commercialRegistrationNumber": "1010741732",
		"durationOfEstablishment": "99",
		"recordStatus": "نشط",
		"capital": "50000000.0",
		"unifiedNationalNumber": "7025752143",
		"mailbox": "غير محدد",
		"recordIssueDate": "2021-09-14",
		"phone": [
			"0000000000",
			"0555450022"
		],
		"website": "",
		"businessActivityArabic": "التعامل في الأوراق المالية -  الترتيب في الأوراق المالية -  تقديم المشورة في الأوراق المالية"
	}
}

Description Table

Field	Description	Data Type
businessNameArabic	The Arabic name of the business	String
commercialRegistrationNumber	The commercial registration number of the business	String
durationOfEstablishment	The number of years the business has been established	String
recordStatus	The current status of the business record	String
capital	The capital value of the business	String
unifiedNationalNumber	The unified national number (e.g., tax ID or similar identifier)	String
mailbox	The mailbox address of the business (if defined)	String
recordIssueDate	The date when the business record was issued	Date
phone	List of phone numbers associated with the business	List of Strings
website	The website URL for the business (if available)	String
businessActivityArabic	The business activity description in Arabic	String

Failure Response

{
    "error": {
        "name": "error",
        "message": "Details are not found for the given request",
        "status": 404,
        "reason": "DATA_NOT_FOUND",
        "type": "Data not found",
        "statusCode": "404"
    }
}

Other Error Code Mapping

{
  "error": {
     "name": "error",
     "message": "Invalid authentication credentials",
     "status": 401,
     "reason": "AUTHENTICATION_ERROR",
     "type": "Bad Request",
     "statusCode": 401
  }
}

Field	Type	Description
name	string	Text displayed on the screen explaining error type.
reason	string	Reason for the error.
status	number	HTTP status code.
message	string	Error message indicating an upstream error.
type	string	Error type.
statusCode	number	Status code representing the error scenario.

Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [email protected]. We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.

We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!