When you confirm a certificate through the API, the platform looks up the candidate’s record in the WAEC database and returns a structured confirmation object. This page explains the shape of that data so you know what to expect and how to use it.
Confirmation result object
Each entry in a confirmation response contains a result object when a match is found, or null when no record exists for the supplied details.
| Field | Type | Description |
|---|
id | string | Unique identifier for this confirmation record. |
country | string | ISO 3166-1 alpha-2 country code (e.g. "NG"). |
country_name | string | Full country name (e.g. "Nigeria"). |
status | string | Match outcome. "Match Found" when the record was located. |
candidate_number | string | The candidate number from the request. |
year | string | The examination year from the request. |
certificate | object | The full certificate details (see below). |
created_at | string | ISO 8601 timestamp of when this confirmation was created. |
Certificate object
The certificate field inside a result contains the candidate’s full examination record.
| Field | Type | Description |
|---|
surname | string | Candidate’s surname. |
firstname | string | Candidate’s first name. |
othernames | string | Candidate’s other names. |
candidate_number | string | The WAEC candidate number. |
year | string | Examination year. |
dob | string | Date of birth in YYYY-MM-DD format. |
gender | string | Candidate’s gender (e.g. "FEMALE", "MALE"). |
center | string | Name of the examination centre. |
exam_title | string | Full examination title. |
results | array | Subject results — each entry has a subject (string) and grade (string). |
Example certificate object
{
"surname": "AYANTUNJI",
"firstname": "ELIZABETH",
"othernames": "BUNMI",
"candidate_number": "4251212052",
"year": "2022",
"dob": "2003-10-04",
"gender": "FEMALE",
"center": "ISIU SENIOR GRAMMAR SCHOOL, ISIU",
"exam_title": "WASSCE (SC) 2022",
"results": [
{ "subject": "ENGLISH LANGUAGE", "grade": "D7" },
{ "subject": "GENERAL MATHEMATICS", "grade": "E8" },
{ "subject": "ECONOMICS", "grade": "C6" },
{ "subject": "CHRISTIAN RELIGIOUS STUDIES", "grade": "E8" }
]
}
Not-found results
If no matching record is found for a given candidate, the result field is null and the entry’s message is "Certificate not found!". The overall request still returns 200 OK.
{
"is_error": false,
"request": { "country": "NG", "candidate_number": "4010144000", "year": "2017" },
"message": "Certificate not found!",
"result": null
}
Always iterate through every entry in the data array and check result individually. A single not-found entry does not cause the whole request to fail.
Next steps
