How to use Freelancer Verification

Lean’s Freelancer Verification API enables you to confirm if an individual in KSA holds a valid freelancer certificate, using the freelancer certificate number and National ID.

Looking for code examples and endpoint details? Refer to our API Reference.

Overview

Lean’s Freelancer Verification API lets you:

Confirm the status and validity of a freelancer certificate (e.g. ACTIVE, EXPIRED)
Retrieve certificate details: full name, category, and specialisation
Match a certificate with a National ID

Lean offers two verification types, designed for different use cases:

Verification Type	Common Use Cases	What’s Returned	Request data
Full Verification	Onboarding and KYC flows Compliance reviews	Certificate status (e.g. ACTIVE, EXPIRED, CANCELED) Certificate expiry date Freelancer’s full name (Arabic and English) Certificate category & specialisation National ID to Certificate match confirmation	Freelancer Certificate Number National ID
Status Verification	Ongoing eligibility checks Status monitoring	Certificate status (e.g. ACTIVE, EXPIRED, CANCELED) Certificate expiry date	Freelancer Certificate Number

Example response for Full Verification

{
  "status": "OK",
  "results_id": "e894ede4-dd81-41fb-b52d-fb4fec16c16c",
  "message": "Data successfully retrieved",
  "timestamp": "2025-05-19T12:09:54.672818827Z",
  "meta": null,
  "status_detail": null,
  "verifications": {
    "certficate_ownership_verified": VERIFIED,
    "national_id": "1107454009",
    "name": {
      "ar": "عادل عيد نفل الحارثي",
      "en": "adel"
    },
    "national_id_expiry_date": "1450-07-01",
    "certificate": [
      {
        "expiry_date": "2025-08-21",
        "number": "FL-013988291",
        "status": "ACTIVE",
        "revoked_at": null,
        "issue_date": "2024-08-21",
        "speciality": {
          "code": "AS090",
          "name": {
            "en": "Sales Promotion and Management",
            "ar": "ادارة وتنشيط المبيعات"
          },
          "category": {
            "name": {
              "en": "Sales & Marketing",
              "ar": "المبيعات والتسويق"
            },
            "code": "C106"
          }
        },
        "canceled_at": "null"
      }
    ],
    "gender": "MALE"
  }
}

Example response for Status Verification

{
  "status": "OK",
  "results_id": "e894ede4-dd81-41fb-b52d-fb4fec16c16c",
  "message": "Data successfully retrieved",
  "timestamp": "2025-05-19T12:09:54.672818827Z",
  "meta": null,
  "status_detail": null,
  "verifications": {
    "certficate_ownership_verified": "not checked",
    "national_id": "null",
    "name": {
      "ar": "null",
      "en": "null"
    },
    "national_id_expiry_date": "null",
    "certificate": [
      {
        "expiry_date": "null",
        "number": "FL-013988291",
        "status": "ACTIVE",
        "revoked_at": "null"
        "issue_date": "2024-08-21",
        "speciality": {
          "code": "null",
          "name": {
            "en": "null",
            "ar":	"null"
          },
          "category": {
            "name": {
              "en": "null",
              "ar": "null"
            },
            "code": "null"
          }
        },
        "canceled_at": "null"
      }
    ],
    "gender": "null"
  }
}

Testing the API

To test the Freelancer Verification API you can use the below mocked data and responses. For Full Verification use both the Freelancer Number and National ID and to test for the Status Verification use only the Freelancer Number.

Ownership match	Certificate status	Freelancer Number	National ID
Match	ACTIVE	FL-013988291	1107454009
Match	PENDING	FL-595215341	1107454009
Match	CANCELED	FL-090302137	1107454009
Match	REVOKED	FL-490775363	1107454009
Match	EXPIRED	FL-541440269	1107454009
Match	REJECTED	FL-560899391	1107454009
No match	N/A	FL-013988291	1046403927

Certificate status definitions

Status	Definition
ACTIVE	The freelance certificate that has been approved and is still valid and working
PENDING	Awaiting approval (or rejection) from issuing authority
CANCELED	Certificate has been cancelled by the freelancer
REVOKED	Issuing authority has revoked the certificate and it is no longer active
EXPIRED	Certificate has past the expiry date and is no longer active
REJECTED	Application denied and certificate not issued

For a complete list of the API response fields and their definitions, please refer to the API Reference.