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-historySandbox GET https://api.sandbox.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 Filter results to confirmations for a specific examination year (for example, 2013).
Filter results by candidate number. Performs a partial match search (for example, 4251212055).
Return only confirmations made on or after this date. Format: YYYY-MM-DD (for example, 2023-08-25).
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.sandbox.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 The HTTP status string. Always "OK" for a successful request.
A human-readable summary (for example, "Retrieved successfully").
A wrapper object containing the results and pagination metadata. The list of confirmation history records matching the applied filters. Unique identifier of the confirmation record.
The confirmation type. Always "CONFIRMATION".
ISO 3166-1 alpha-2 country code (for example, "NG"). null when the country is unknown.
Full country name (for example, "Nigeria"). "Unknown" when the country could not be determined.
Match status of the confirmation (for example, "Match Found").
An identifier grouping bulk confirmations submitted together. null for individually submitted confirmations.
Basic candidate details from the matched certificate record.
The candidate number from the original confirmation request.
The examination year from the original confirmation request.
ISO 8601 timestamp of when the confirmation was made.
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 UNAUTHORIZED401The X-DigiCert-Secret header is missing or invalid VALIDATION_ERROR422A query parameter contains an invalid value (for example, a malformed date)
