Wathq Commercial Registration

The Wathq API lets you verify a Saudi company by its Commercial Registration (CR) number. Azakaw looks the company up through Wathq (Commercial Registration, New Legislation) and returns the official record: company details, status, capital, owners (parties) and managers.

Unlike Nafath, Wathq is synchronous. There is no approval step, callback, webhook or polling. You send a CR number and get the result straight away.

The integration is a two-step flow:

Lookup – POST /ExtWathq/lookup fetches the company record from Wathq and stores it against your tenant.
Retrieve – GET /ExtWathq/company/{crNumber} returns the stored record.

Authentication

All requests require a bearer token in the Authorization header. The token must carry the External services claim.

Authorization: Bearer your-token-here

For details on how to obtain a token, see Authentication. The tenant is always taken from the token, never from the request body.

Lookup Company

POST {base_url}/ExtWathq/lookup

Looks up a company by CR number and stores the full record for your tenant. Real lookups (Live and Sandbox modes) consume one unit of your tenant's Wathq quota. A failed lookup is refunded.

Request Body

{
  "crNumber": "4030010781",
  "clientId": "string",
  "formId": "string"
}

Parameters

Parameter	Type	Required	Description
crNumber	string	Yes	The commercial registration number. Must be exactly 10 digits
clientId	string	No	The client the lookup is attributed to. Used for mode resolution and audit. If your credential is restricted to specific clients, it must be one of them. If omitted, your single or default client is used
formId	string	No	A form used only to resolve a form-level mode override. Ignored if your credential cannot access that form

Response

{
  "version": "string",
  "statusCode": 200,
  "messages": [
    "Processed successfully"
  ],
  "result": {
    "crNumber": "4030010781",
    "companyName": "string",
    "mode": 3
  }
}

Response Fields

Field	Type	Description
version	string	API version
statusCode	number	HTTP status code (200 for success)
messages	array	Response messages
crNumber	string	The CR number that was looked up
companyName	string	Company name as registered with Wathq (Arabic)
mode	number	The mode the lookup was served in

Get Stored Company Record

GET {base_url}/ExtWathq/company/{crNumber}

Returns the most recent stored record for a CR number within your tenant, as saved by a previous lookup. This endpoint does not call Wathq and does not consume quota.

The record includes owner and manager identity numbers. If your credential is restricted to specific clients, you only see records looked up under those clients.

Parameters

Parameter	Type	Required	Description
crNumber	string	Yes	The 10-digit commercial registration number

Response

result is null if no lookup has been stored for this CR.

{
  "version": "string",
  "statusCode": 200,
  "messages": [
    "Processed successfully"
  ],
  "result": {
    "crNumber": "4030010781",
    "mode": 2,
    "whenCreatedUtc": "2026-08-07T10:15:00Z",
    "company": {
      "crNationalNumber": "7000850920",
      "crNumber": "4030010781",
      "versionNo": 1,
      "name": "string",
      "nameLangId": 1,
      "nameLangDesc": "اللغة العربية",
      "crCapital": 13000000,
      "companyDuration": 5,
      "isMain": true,
      "issueDateGregorian": "1976-12-07",
      "issueDateHijri": "16-12-1396",
      "mainCrNationalNumber": null,
      "mainCrNumber": null,
      "inLiquidationProcess": false,
      "hasEcommerce": false,
      "headquarterCityId": 18,
      "headquarterCityName": "جدة",
      "isLicenseBased": false,
      "licenseIssuerNationalNumber": null,
      "licenseIssuerName": null,
      "partnersNationalityId": 1,
      "PartnersNationalityName": "سعودية",
      "entityType": {
        "id": 1,
        "name": "شركة",
        "formId": 3,
        "formName": "توصية بسيطة",
        "characters": []
      },
      "status": {
        "id": 1,
        "name": "نشط",
        "confirmationDate": { "gregorian": "2025-04-03", "hijri": "05-10-1446" }
      },
      "contactInfo": {
        "phoneNo": null,
        "mobileNo": "string",
        "email": "string",
        "websiteUrl": null
      },
      "capital": {
        "currencyId": 1,
        "currencyName": "ريال سعودي",
        "contributionCapital": {
          "typeId": 1,
          "typeName": "نقدي",
          "cashCapital": -1,
          "inKindCapital": 0,
          "contributionValue": 0,
          "totalCashContribution": 0,
          "totalInKindContribution": 0
        }
      },
      "parties": [
        {
          "name": "string",
          "typeId": 1,
          "typeName": "فرد سعودي",
          "identity": { "id": "1003589726", "typeId": 1, "typeName": "هوية وطنية" },
          "partnership": [{ "id": 2, "name": "شريك متضامن" }],
          "partnerShare": {
            "cashContributionCount": 0,
            "inKindContributionCount": 0,
            "totalContributionCount": 0
          },
          "nationality": { "id": 113, "name": "السعودية" },
          "crNumber": null,
          "licenseNo": null
        }
      ],
      "management": {
        "structureId": 1,
        "structureName": "مدير",
        "managers": [
          {
            "name": "string",
            "typeId": 1,
            "typeName": "فرد سعودي",
            "isLicensed": false,
            "identity": { "id": "1003589726", "typeId": 1, "typeName": "هوية وطنية" },
            "nationality": { "id": 113, "name": "السعودية" },
            "positions": []
          }
        ]
      },
      "activities": []
    }
  }
}

Response Fields

Field	Type	Description
crNumber	string	The CR number
mode	number	The mode the record was fetched in
whenCreatedUtc	string	When the record was stored (UTC)
company	object	The full Wathq company record (see below)

Company

Field	Type	Description
crNumber	string	Commercial registration number
crNationalNumber	string	CR national (unified) number
versionNo	number	Version of the CR record
name	string	Registered company name (Arabic)
crCapital	number	Registered capital amount
companyDuration	number	Company duration
isMain	boolean	Whether this is the main CR (not a branch)
mainCrNumber / mainCrNationalNumber	string	Main CR identifiers, when this is not the main CR
issueDateGregorian	string	Issue date, `yyyy-MM-dd`
issueDateHijri	string	Issue date, Hijri calendar (`dd-MM-yyyy`)
inLiquidationProcess	boolean	Whether the company is being liquidated
hasEcommerce	boolean	Whether the company has an e-commerce registration
headquarterCityId / headquarterCityName	number / string	Headquarters city
isLicenseBased	boolean	Whether the CR is license based
licenseIssuerName / licenseIssuerNationalNumber	string	License issuer, when license based
partnersNationalityId / PartnersNationalityName	number / string	Nationality of the partners. Note the capital `P` in `PartnersNationalityName`, as returned by Wathq
entityType	object	Entity type: `id`, `name`, `formId`, `formName`, `characters`
status	object	Register status: `id`, `name`, and date objects (`confirmationDate`, `reactivationDate`, `suspensionDate`, `deletionDate`, each `{ gregorian, hijri }` when set)
contactInfo	object	`phoneNo`, `mobileNo`, `email`, `websiteUrl`
eCommerce	object	E-store details (`eStore` list), when present
capital	object	`currencyId`, `currencyName`, `contributionCapital` or `stockCapital`
fiscalYear	object	Fiscal year end (`endMonth`, `endDay`, ...), when present
parties	array	Owners (see below)
management	object	`structureId`, `structureName` and the `managers` array
activities	array	Registered activities (`id`, `name`)

note

contributionCapital.cashCapital may be -1. This means the value is undisclosed, not a real amount. Treat it as unknown.

Party (Owner)

Field	Type	Description
name	string	Owner name
typeId / typeName	number / string	Owner type (for example Saudi individual)
identity	object	`id`, `typeId`, `typeName`. The national ID, Iqama or passport number
partnership	array	Partnership roles (`id`, `name`)
partnerShare	object	`cashContributionCount`, `inKindContributionCount`, `totalContributionCount`
nationality	object	`id`, `name`, and `nameEn` when available
crNumber	string	CR number, when the owner is a company
licenseNo	string	License number, when applicable

Manager

Field	Type	Description
name	string	Manager name
typeId / typeName	number / string	Manager type
isLicensed	boolean	Whether the manager is licensed
identity	object	`id`, `typeId`, `typeName`
nationality	object	`id`, `name`, and `nameEn` when available
positions	array	Board positions (`id`, `name`)

info

Wathq returns names and lookup values in Arabic. In the Sandbox, Wathq masks personal and contact data, so values contain placeholder x characters.

Modes

Every lookup is served in one of three modes. The mode is resolved from the most specific scope that has a configuration: form, then client, then tenant, then the global default. If nothing is configured, the mode is Simulation.

Value	Mode	Description	Quota
1	Live	Calls the production Wathq API. Returns real company data	Consumes 1 per lookup
2	Sandbox	Calls the Wathq sandbox with real requests but Wathq test data	Consumes 1 per lookup
3	Simulation	No network call. Returns a fixed, captured sample record, with your requested CR number echoed back	None

The mode field in each response tells you which one served the request. Data from Simulation and Sandbox is not real company data and must not be used for real onboarding decisions.

warning

Simulation is the default. A new tenant returns sample data until its mode is set to Live. Check mode in the lookup response before relying on the result.

Quota

Live and Sandbox lookups are billed against a per-tenant quota. Simulation lookups and stored-record retrieval (GET /ExtWathq/company/{crNumber}) are not.

A quota slot is reserved before the call to Wathq and refunded if the call fails.
If the tenant has no quota configured, is blocked, or has used its allowance, the request fails with 429.

Integration Flow

Look up: call POST /ExtWathq/lookup with the 10-digit crNumber. Check mode in the response.
Retrieve: call GET /ExtWathq/company/{crNumber} to read the stored company record, including owners and managers.
Use the data: use parties and management.managers (identities, nationalities, roles) for your beneficial-owner and director checks, such as sanctions screening.

If you use Azakaw onboarding forms with a Wathq field, the platform performs the equivalent steps for you. It auto-fills the mapped form fields and populates owners and managers.

Error Handling

Status Code	Description	Solution
400	`A valid 10-digit commercial-registration number is required.`	Send a CR number of exactly 10 digits
400	Mode not configured (Live or Sandbox credentials missing)	Contact Azakaw support. The tenant's mode must be configured
401	Unauthorized access	Check the authentication token
403	Tenant claim missing from the token, or the token lacks access	Use a token with the External services claim
429	Wathq quota exceeded, not configured, or blocked for this tenant	Contact Azakaw support to increase the quota

Best Practices

Validate the CR number client-side (10 digits) before calling the API.
Check mode in every lookup response, and never treat Simulation or Sandbox results as verified real company data.
Look up once, then read: use GET /ExtWathq/company/{crNumber} for repeat reads instead of repeating billable lookups.
Protect owner and manager data: the stored record includes identity numbers. Do not log it or expose it client-side.
Handle Arabic values: names, statuses and entity types come back in Arabic.

Authentication​

Lookup Company​

Request Body​

Parameters​

Response​

Response Fields​

Get Stored Company Record​

Parameters​

Response​

Response Fields​

Company​

Party (Owner)​

Manager​

Modes​

Quota​

Integration Flow​

Error Handling​

Best Practices​

Authentication

Lookup Company

Request Body

Parameters

Response

Response Fields

Get Stored Company Record

Parameters

Response

Response Fields

Company

Party (Owner)

Manager

Modes

Quota

Integration Flow

Error Handling

Best Practices