> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waec.org/llms.txt
> Use this file to discover all available pages before exploring further.

# What Are Digital WAEC Certificates?

> Learn how the WAEC Certificate Digitization API represents certificate records, their data model, and how a certificate moves through its lifecycle.

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

```json theme={null}
{
  "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`.

```json theme={null}
{
  "is_error": false,
  "request": { "country": "NG", "candidate_number": "4010144000", "year": "2017" },
  "message": "Certificate not found!",
  "result": null
}
```

<Note>
  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.
</Note>

## Next steps

* See the [Confirm Certificates guide](/guides/confirm-certificates) for a walkthrough of confirming certificates in bulk.
* See the [POST /certificate/confirm reference](/api-reference/certificate-confirmation/confirm) for the full request and response schema.