GET /certificate/confirmation-history

This endpoint returns a list of all certificate confirmations made on your Institution account. You can filter results by examination year, candidate number, and a date range to narrow down the records returned.

Endpoint

Environment	URL
Production	`GET https://api.waec.org/api/v1/external/certificate/confirmation-history`
Sandbox	`GET https://api.smartdocument.org/api/v1/external/certificate/confirmation-history`

Authentication

Required. Include your API Secret key in the X-DigiCert-Secret request header.

X-DigiCert-Secret: <your_api_secret_key>

Each environment uses a separate key. See Environments for details.

Query Parameters

string

Filter results to confirmations for a specific examination year (for example, 2013).

string

Filter results by candidate number. Performs a partial match search (for example, 4251212055).

string

Return only confirmations made on or after this date. Format: YYYY-MM-DD (for example, 2023-08-25).

string

Return only confirmations made on or before this date. Format: YYYY-MM-DD (for example, 2023-08-30).

All query parameters are optional. Omitting them returns the full confirmation history for your account.

Example Request

curl -X GET "https://api.smartdocument.org/api/v1/external/certificate/confirmation-history?year=2013&search=4251212055&start_date=2023-08-25&end_date=2023-08-30" \
  -H "X-DigiCert-Secret: <your_api_secret_key>"

Response Fields

string

The HTTP status string. Always "OK" for a successful request.

string

A human-readable summary (for example, "Retrieved successfully").

object

A wrapper object containing the results and pagination metadata.

Show data fields

array of objects

The list of confirmation history records matching the applied filters.

Show Record fields

string

Unique identifier of the confirmation record.

string

The confirmation type. Always "CONFIRMATION".

string | null

ISO 3166-1 alpha-2 country code (for example, "NG"). null when the country is unknown.

string

Full country name (for example, "Nigeria"). "Unknown" when the country could not be determined.

string

Match status of the confirmation (for example, "Match Found").

string | null

An identifier grouping bulk confirmations submitted together. null for individually submitted confirmations.

object

Basic candidate details from the matched certificate record.

string

The candidate number from the original confirmation request.

string

The examination year from the original confirmation request.

string

ISO 8601 timestamp of when the confirmation was made.

object

Pagination metadata for the result set.

Success Response

Status: 200 OK

{
  "status": "OK",
  "message": "Retrieved successfully",
  "data": {
    "data": [
      {
        "id": "7452c3eb-c106-4d78-b1ce-59c6e13e49eb",
        "type": "CONFIRMATION",
        "country": "NG",
        "country_name": "Nigeria",
        "status": "Match Found",
        "group_id": null,
        "candidate": {
          "id": "13a05682-63f5-4369-9837-b8ced0873518",
          "surname": "OGUNSANMI",
          "firstname": "IBUKUMI",
          "othernames": "",
          "candidate_number": "4251212052",
          "period": "JUNE 2013",
          "year": "2013",
          "gender": "MALE"
        },
        "candidate_number": "4251212052",
        "year": "2013",
        "created_at": "2026-05-21T07:29:07.000000Z"
      }
    ],
    "pagination": {
      "total": 10,
      "count": 10,
      "per_page": 15,
      "current_page": 1,
      "last_page": 1
    }
  }
}

Error Cases

Error Code	HTTP Status	When it occurs
`UNAUTHORIZED`	`401`	The `X-DigiCert-Secret` header is missing or invalid
`VALIDATION_ERROR`	`422`	A query parameter contains an invalid value (for example, a malformed date)

Overview

Certificate Confirmation

Endpoint

Authentication

Query Parameters

Example Request

Response Fields

Success Response

Error Cases

​Endpoint

​Authentication

​Query Parameters

​Example Request

​Response Fields

​Success Response

​Error Cases

Endpoint

Authentication

Query Parameters

Example Request

Response Fields

Success Response

Error Cases