> ## 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.

# POST /certificate/confirm

> Submit one or more WAEC certificate records for confirmation. A digital copy is sent to the registered email if available.

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.

```text theme={null}
X-DigiCert-Secret: <your_api_secret_key>
```

Each environment uses a separate key. See [Environments](/configuration/environment) for details.

## Content-Type

```text theme={null}
application/json
```

## Request Body

<ParamField body="certificates" type="array of objects" required>
  An array of certificate objects to confirm. Each object must include:

  <Expandable title="Certificate object">
    <ParamField body="country" type="string" required>
      The ISO 3166-1 alpha-2 country code for the country in which the examination was taken (for example, `"NG"` for Nigeria).
    </ParamField>

    <ParamField body="candidate_number" type="string" required>
      The official WAEC candidate number assigned to the student (for example, `"4251212055"`).
    </ParamField>

    <ParamField body="year" type="string" required>
      The four-digit year in which the examination was taken (for example, `"2013"`).
    </ParamField>
  </Expandable>
</ParamField>

## Example Request

```bash theme={null}
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

<ResponseField name="status" type="string">
  The HTTP status string. Always `"OK"` for a successful request.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable summary of the request outcome (for example, `"Request completed"`).
</ResponseField>

<ResponseField name="data" type="array of objects">
  An array of result objects, one per submitted certificate entry. Each object contains:

  <Expandable title="Result object">
    <ResponseField name="is_error" type="boolean">
      `false` when the lookup was processed without an error, regardless of whether a certificate was found.
    </ResponseField>

    <ResponseField name="request" type="object">
      An echo of the original request for this entry — includes `country`, `candidate_number`, and `year`.
    </ResponseField>

    <ResponseField name="message" type="string">
      A human-readable outcome for this specific entry (for example, `"Certificate already verified."` or `"Certificate not found!"`).
    </ResponseField>

    <ResponseField name="result" type="object | null">
      The matched certificate record, or `null` if no certificate was found for this entry.

      <Expandable title="Result fields">
        <ResponseField name="id" type="string">
          Unique identifier of the confirmation record.
        </ResponseField>

        <ResponseField name="country" type="string">
          ISO 3166-1 alpha-2 country code (for example, `"NG"`).
        </ResponseField>

        <ResponseField name="country_name" type="string">
          Full country name (for example, `"Nigeria"`).
        </ResponseField>

        <ResponseField name="status" type="string">
          Match status for the lookup. `"Match Found"` when a record was located.
        </ResponseField>

        <ResponseField name="candidate_number" type="string">
          The candidate number from the original request.
        </ResponseField>

        <ResponseField name="year" type="string">
          The examination year from the original request.
        </ResponseField>

        <ResponseField name="certificate" type="object">
          The full certificate details.

          <Expandable title="Certificate fields">
            <ResponseField name="results" type="array of objects">
              Subject results. Each entry includes:

              * `subject` (string) — subject name
              * `grade` (string) — grade awarded (for example, `"B3"`, `"C6"`)
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp of when this confirmation record was created.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Success Response

**Status: `200 OK`**

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

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

## 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 |