Skip to main content
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.
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.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"
      }
    ]
  }'

​
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.sandbox.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.sandbox.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.