Freelance Verification

Verify a freelancer's certificate and its status using their National ID and certificate number.

Integration guide

Goal: Confirm a freelancer's certificate is authentic and active, and retrieve the freelancer and certificate details.

Estimated time: 15 minutes

Prerequisites

Sandbox credentials and an access token
The freelancer's National ID and certificate number

Verification concept Commercial Registration

When to use

Freelance marketplaces running background checks
Recruitment platforms vetting candidates
Any workflow that must confirm a professional credential before engagement

What it returns

Request inputs

Field	Description
`nationalId`	The freelancer's 10-digit National ID
`certificateNumber`	Certificate to verify (format `FL-XXXXXXXXX`)

Response

Group	Fields
Freelancer	Name (English/Arabic), gender, national ID, expiry date
Certificate	Status, issue/expiry dates, number, specialization, category

Certificate status is one of: Active, Revoked, Rejected, Expired, Canceled, Pending.

Integration summary

Authenticate

Obtain a Bearer access token from your API credentials.

Submit the identity + certificate

curl -X POST https://sandbox.sparefinancial.sa/api/v2.0/av/FreelancerVerification/CertificateDetails \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "nationalId": "10XXXXXXXX", "certificateNumber": "FL-XXXXXXXXX" }'

const res = await fetch(
  "https://sandbox.sparefinancial.sa/api/v2.0/av/FreelancerVerification/CertificateDetails",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      nationalId: "10XXXXXXXX",
      certificateNumber: "FL-XXXXXXXXX",
    }),
  },
);

const data = await res.json();

import requests

res = requests.post(
    "https://sandbox.sparefinancial.sa/api/v2.0/av/FreelancerVerification/CertificateDetails",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "nationalId": "10XXXXXXXX",
        "certificateNumber": "FL-XXXXXXXXX",
    },
)

data = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

String body = """
    { "nationalId": "10XXXXXXXX", "certificateNumber": "FL-XXXXXXXXX" }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox.sparefinancial.sa/api/v2.0/av/FreelancerVerification/CertificateDetails"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

String result = response.body();

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

using var client = new HttpClient();

var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://sandbox.sparefinancial.sa/api/v2.0/av/FreelancerVerification/CertificateDetails");
request.Headers.Add("Authorization", $"Bearer {accessToken}");
request.Content = new StringContent(
    "{ \"nationalId\": \"10XXXXXXXX\", \"certificateNumber\": \"FL-XXXXXXXXX\" }",
    Encoding.UTF8,
    "application/json");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

package main

import (
	"bytes"
	"io"
	"net/http"
)

payload := []byte(`{ "nationalId": "10XXXXXXXX", "certificateNumber": "FL-XXXXXXXXX" }`)

req, err := http.NewRequest(
	http.MethodPost,
	"https://sandbox.sparefinancial.sa/api/v2.0/av/FreelancerVerification/CertificateDetails",
	bytes.NewReader(payload),
)
if err != nil {
	panic(err)
}

req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

body, _ := io.ReadAll(res.Body)

Act on the status

Only treat Active certificates as valid. Handle common errors: invalid format (400), expired token (401), missing record (404), mismatched credentials (412).

Key takeaways

Verifies a freelancer certificate from a National ID + certificate number (FL-XXXXXXXXX).
Only treat Active certificates as valid, other statuses (Revoked, Expired, Pending, etc.) should block or flag.
Watch for the 412 mismatched-credentials error alongside the usual 400 / 401 / 404.

Continue learning

Verification concept

The full verification suite.

Commercial Registration

Company registration lookup.