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 |
|
|
Retrieve all certificates | Onboarding and KYC flows\ |
|
|
Status Verification | Ongoing eligibility checks |
|
|
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 Retrieve all certificates
{
"status": "OK",
"results_id": "e286fa03-219c-470e-abdd-0d8796afdb28",
"message": "Freelancer verification successful",
"timestamp": "2025-08-19T05:57:17.733635157Z",
"meta": null,
"status_detail": null,
"verifications": {
"certificate_ownership_verified": "VERIFIED",
"national_id": "1107454009",
"national_id_expiry_date": "2030-12-31",
"name": {
"ar": "مستقل نشط",
"en": "Active Freelancer"
},
"gender": "MALE",
"certificate": [
{
"expiry_date": "2026-08-01",
"number": "FL-013988291",
"status": "ACTIVE",
"revoked_at": null,
"issue_date": "2024-08-01",
"speciality": {
"code": "SD001",
"name": {
"ar": "تطوير البرمجيات",
"en": "Software Development"
},
"category": {
"name": {
"ar": "تقنية المعلومات",
"en": "Information Technology"
},
"code": "IT001"
}
},
"canceled_at": null
},
{
"expiry_date": "2027-01-01",
"number": "FL-595215341",
"status": "PENDING",
"revoked_at": null,
"issue_date": "2025-01-01",
"speciality": {
"code": "DM002",
"name": {
"ar": "التسويق الرقمي",
"en": "Digital Marketing"
},
"category": {
"name": {
"ar": "التسويق",
"en": "Marketing"
},
"code": "MKT001"
}
},
"canceled_at": null
},
{
"expiry_date": "2025-02-01",
"number": "FL-090302137",
"status": "CANCELED",
"revoked_at": null,
"issue_date": "2023-02-01",
"speciality": {
"code": "GD003",
"name": {
"ar": "التصميم الجرافيكي",
"en": "Graphic Design"
},
"category": {
"name": {
"ar": "الفنون الإبداعية",
"en": "Creative Arts"
},
"code": "CA001"
}
},
"canceled_at": "2024-06-20T00:00:00Z"
},
{
"expiry_date": "2025-04-15",
"number": "FL-490775363",
"status": "REVOKED",
"revoked_at": "2024-05-15T00:00:00Z",
"issue_date": "2023-04-15",
"speciality": {
"code": "DS004",
"name": {
"ar": "علم البيانات",
"en": "Data Science"
},
"category": {
"name": {
"ar": "تقنية المعلومات",
"en": "Information Technology"
},
"code": "IT001"
}
},
"canceled_at": null
},
{
"expiry_date": "2024-03-01",
"number": "FL-541440269",
"status": "EXPIRED",
"revoked_at": null,
"issue_date": "2022-03-01",
"speciality": {
"code": "PM005",
"name": {
"ar": "إدارة المشاريع",
"en": "Project Management"
},
"category": {
"name": {
"ar": "أعمال",
"en": "Business"
},
"code": "BIZ002"
}
},
"canceled_at": null
},
{
"expiry_date": null,
"number": "FL-560899391",
"status": "REJECTED",
"revoked_at": null,
"issue_date": null,
"speciality": {
"code": "HR006",
"name": {
"ar": "الموارد البشرية",
"en": "Human Resources"
},
"category": {
"name": {
"ar": "أعمال",
"en": "Business"
},
"code": "BIZ002"
}
},
"canceled_at": null
}
]
}
}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. To test;
- Full Verification: use both the Freelancer Number and National ID
- Retrieve all certificates: use only the National ID (1107454009)
- 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.
Updated 17 days ago