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

# Confirm Certificates in Bulk

> Learn how to confirm one or more WAEC certificates in a single request, handle not-found results, and process the full candidate and subject data returned.

The confirm endpoint lets you submit multiple WAEC certificates for confirmation in a single request. The platform looks up each one independently and returns the full candidate record when a match is found. This guide covers how to structure the request, process the response, and handle the case where a certificate is not found.

## How it works

1. You send a `POST` request with an array of certificate entries — each with a `country`, `candidate_number`, and `year`.
2. The platform queries each entry against the WAEC database.
3. The response contains one result object per entry. Entries that matched include the full certificate data; entries with no match return `result: null`.
4. For confirmed certificates where the candidate has a registered email, a digital copy is sent to them automatically.

<Note>
  The entire request always returns `200 OK`. Per-entry outcomes are determined by the `result` field — not the HTTP status code.
</Note>

## Confirm a single certificate

```bash theme={null}
curl --request POST \
  --url https://api.smartdocument.org/api/v1/external/certificate/confirm \
  --header 'X-DigiCert-Secret: YOUR_API_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "certificates": [
      {
        "country": "NG",
        "candidate_number": "4251212052",
        "year": "2022"
      }
    ]
  }'
```

## Confirm multiple certificates

Add as many entries as needed to the `certificates` array. Each is processed independently:

```bash theme={null}
curl --request POST \
  --url https://api.sandbox.smartdocument.org/api/v1/external/certificate/confirm \
  --header 'X-DigiCert-Secret: YOUR_API_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "certificates": [
      { "country": "NG", "candidate_number": "4251212052", "year": "2022" },
      { "country": "NG", "candidate_number": "4251212051", "year": "2017" },
      { "country": "NG", "candidate_number": "4010144000", "year": "2017" }
    ]
  }'
```

## Processing the response

Iterate through the `data` array and check each entry's `result` field:

```javascript theme={null}
const response = await fetch(
  'https://api.smartdocument.org/api/v1/external/certificate/confirm',
  {
    method: 'POST',
    headers: {
      'X-DigiCert-Secret': process.env.DIGICERT_SECRET_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      certificates: [
        { country: 'NG', candidate_number: '4251212052', year: '2022' },
        { country: 'NG', candidate_number: '4010144000', year: '2017' },
      ],
    }),
  }
);

const { data } = await response.json();

for (const entry of data) {
  if (entry.result === null) {
    console.log(`Not found: ${entry.request.candidate_number}`);
  } else {
    const { surname, firstname, results } = entry.result.certificate;
    console.log(`Confirmed: ${firstname} ${surname}`);
    console.log('Subjects:', results);
  }
}
```

## Handling not-found results

When a candidate is not found, the entry looks like this:

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

`is_error` is `false` — this is an expected outcome, not an API error. Use `result === null` as your not-found check.

## Viewing confirmation history

After confirming certificates, you can retrieve a full log of your account's confirmations — filterable by year, candidate number, and date range:

```bash theme={null}
curl --request GET \
  --url 'https://api.smartdocument.org/api/v1/external/certificate/confirmation-history?year=2022' \
  --header 'X-DigiCert-Secret: YOUR_API_SECRET_KEY'
```

See the [Confirmation History reference](/api-reference/certificate-confirmation/history) for all available filters and the full response schema.