Confirm Certificates in Bulk

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

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

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

Confirm a single certificate

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:

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:

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:

{
  "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:

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 for all available filters and the full response schema.

Get Started

Core Concepts

Guides

Configuration

How it works

Confirm a single certificate

Confirm multiple certificates

Processing the response

Handling not-found results

Viewing confirmation history

​How it works

​Confirm a single certificate

​Confirm multiple certificates

​Processing the response

​Handling not-found results

​Viewing confirmation history

How it works

Confirm a single certificate

Confirm multiple certificates

Processing the response

Handling not-found results

Viewing confirmation history