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/confirmSandbox POST https://api.sandbox.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 Request Body An array of certificate objects to confirm. Each object must include: The ISO 3166-1 alpha-2 country code for the country in which the examination was taken (for example, "NG" for Nigeria).
The official WAEC candidate number assigned to the student (for example, "4251212055").
The four-digit year in which the examination was taken (for example, "2013").
Example Request curl -X POST https://api.sandbox.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 The HTTP status string. Always "OK" for a successful request.
A human-readable summary of the request outcome (for example, "Request completed").
An array of result objects, one per submitted certificate entry. Each object contains: false when the lookup was processed without an error, regardless of whether a certificate was found.
An echo of the original request for this entry — includes country, candidate_number, and year.
A human-readable outcome for this specific entry (for example, "Certificate already verified." or "Certificate not found!").
The matched certificate record, or null if no certificate was found for this entry. Unique identifier of the confirmation record.
ISO 3166-1 alpha-2 country code (for example, "NG").
Full country name (for example, "Nigeria").
Match status for the lookup. "Match Found" when a record was located.
The candidate number from the original request.
The examination year from the original request.
The full certificate details. Subject results. Each entry includes:
subject (string) — subject namegrade (string) — grade awarded (for example, "B3", "C6") 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 UNAUTHORIZED401The X-DigiCert-Secret header is missing or invalid VALIDATION_ERROR422The certificates array is empty or an entry is missing required fields
