POST /certificate/confirm

This endpoint confirms one or more WAEC certificates by candidate number, country, and exam year. For each certificate that is successfully confirmed, a digital copy is dispatched to the candidate’s registered email address when one is on record.

Endpoint

Environment	URL
Production	`POST https://api.waec.org/api/v1/external/certificate/confirm`
Sandbox	`POST https://api.smartdocument.org/api/v1/external/certificate/confirm`

Authentication

Required. Include your API Secret key in the X-DigiCert-Secret request header.

X-DigiCert-Secret: <your_api_secret_key>

Each environment uses a separate key. See Environments for details.

Content-Type

application/json

Request Body

array of objects

required

An array of certificate objects to confirm. Each object must include:

Show Certificate object

string

required

The ISO 3166-1 alpha-2 country code for the country in which the examination was taken (for example, "NG" for Nigeria).

string

required

The official WAEC candidate number assigned to the student (for example, "4251212055").

string

required

The four-digit year in which the examination was taken (for example, "2013").

Example Request

curl -X POST https://api.smartdocument.org/api/v1/external/certificate/confirm \
  -H "X-DigiCert-Secret: <your_api_secret_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "certificates": [
      {
        "country": "NG",
        "candidate_number": "4251212055",
        "year": "2013"
      },
      {
        "country": "NG",
        "candidate_number": "4251212051",
        "year": "2017"
      },
      {
        "country": "NG",
        "candidate_number": "4010144000",
        "year": "2017"
      }
    ]
  }'

Response Fields

string

The HTTP status string. Always "OK" for a successful request.

string

A human-readable summary of the request outcome (for example, "Request completed").

array of objects

An array of result objects, one per submitted certificate entry. Each object contains:

Show Result object

boolean

false when the lookup was processed without an error, regardless of whether a certificate was found.

object

An echo of the original request for this entry — includes country, candidate_number, and year.

string

A human-readable outcome for this specific entry (for example, "Certificate already verified." or "Certificate not found!").

object | null

The matched certificate record, or null if no certificate was found for this entry.

Show Result fields

string

Unique identifier of the confirmation record.

string

ISO 3166-1 alpha-2 country code (for example, "NG").

string

Full country name (for example, "Nigeria").

string

Match status for the lookup. "Match Found" when a record was located.

string

The candidate number from the original request.

string

The examination year from the original request.

object

The full certificate details.

Show Certificate fields

array of objects

Subject results. Each entry includes:

subject (string) — subject name
grade (string) — grade awarded (for example, "B3", "C6")

string

ISO 8601 timestamp of when this confirmation record was created.

Success Response

Status: 200 OK

{
  "status": "OK",
  "message": "Request completed",
  "data": [
    {
      "is_error": false,
      "request": {
        "country": "NG",
        "candidate_number": "4251212052",
        "year": "2022"
      },
      "message": "Certificate already verified.",
      "result": {
        "id": "ea9065b4-563b-48c7-a98f-0594948fc415",
        "country": "NG",
        "country_name": "Nigeria",
        "status": "Match Found",
        "candidate_number": "4251212052",
        "year": "2022",
        "certificate": {
          "surname": "JOHN",
          "firstname": "AKEEM",
          "othernames": "ADAMU",
          "candidate_number": "4010101001",
          "year": "2022",
          "dob": "2006-01-16",
          "gender": "FEMALE",
          "center": "LAGOS SENIOR GRAMMAR SCHOOL, LAGOS",
          "exam_title": "WASSCE (SC) 2022",
          "results": [
            { "subject": "CHRISTIAN RELIGIOUS STUDIES", "grade": "E8" },
            { "subject": "ECONOMICS", "grade": "C6" },
            { "subject": "ENGLISH LANGUAGE", "grade": "D7" },
            { "subject": "GENERAL MATHEMATICS", "grade": "E8" }
          ]
        },
        "created_at": "2026-05-21T07:39:52.000000Z"
      }
    },
    {
      "is_error": false,
      "request": {
        "country": "NG",
        "candidate_number": "4010144000",
        "year": "2017"
      },
      "message": "Certificate not found!",
      "result": null
    }
  ]
}

A 200 OK response is returned even when individual certificates are not found. Always check each entry’s result field — a null value indicates no match was found for that candidate.

Error Cases

Error Code	HTTP Status	When it occurs
`UNAUTHORIZED`	`401`	The `X-DigiCert-Secret` header is missing or invalid
`VALIDATION_ERROR`	`422`	The `certificates` array is empty or an entry is missing required fields

Overview

Certificate Confirmation

Endpoint

Authentication

Content-Type

Request Body

Example Request

Response Fields

Success Response

Error Cases

​Endpoint

​Authentication

​Content-Type

​Request Body

​Example Request

​Response Fields

​Success Response

​Error Cases

Endpoint

Authentication

Content-Type

Request Body

Example Request

Response Fields

Success Response

Error Cases