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

# GET /certificate/confirmation-history

> Retrieve a paginated, filterable history of all certificate confirmations made on your Institution account.

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.

```text theme={null}
X-DigiCert-Secret: <your_api_secret_key>
```

Each environment uses a separate key. See [Environments](/configuration/environment) for details.

## Query Parameters

<ParamField query="year" type="string">
  Filter results to confirmations for a specific examination year (for example, `2013`).
</ParamField>

<ParamField query="search" type="string">
  Filter results by candidate number. Performs a partial match search (for example, `4251212055`).
</ParamField>

<ParamField query="start_date" type="string">
  Return only confirmations made on or after this date. Format: `YYYY-MM-DD` (for example, `2023-08-25`).
</ParamField>

<ParamField query="end_date" type="string">
  Return only confirmations made on or before this date. Format: `YYYY-MM-DD` (for example, `2023-08-30`).
</ParamField>

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

## Example Request

```bash theme={null}
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

<ResponseField name="status" type="string">
  The HTTP status string. Always `"OK"` for a successful request.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable summary (for example, `"Retrieved successfully"`).
</ResponseField>

<ResponseField name="data" type="object">
  A wrapper object containing the results and pagination metadata.

  <Expandable title="data fields">
    <ResponseField name="data" type="array of objects">
      The list of confirmation history records matching the applied filters.

      <Expandable title="Record fields">
        <ResponseField name="id" type="string">
          Unique identifier of the confirmation record.
        </ResponseField>

        <ResponseField name="type" type="string">
          The confirmation type. Always `"CONFIRMATION"`.
        </ResponseField>

        <ResponseField name="country" type="string | null">
          ISO 3166-1 alpha-2 country code (for example, `"NG"`). `null` when the country is unknown.
        </ResponseField>

        <ResponseField name="country_name" type="string">
          Full country name (for example, `"Nigeria"`). `"Unknown"` when the country could not be determined.
        </ResponseField>

        <ResponseField name="status" type="string">
          Match status of the confirmation (for example, `"Match Found"`).
        </ResponseField>

        <ResponseField name="group_id" type="string | null">
          An identifier grouping bulk confirmations submitted together. `null` for individually submitted confirmations.
        </ResponseField>

        <ResponseField name="candidate" type="object">
          Basic candidate details from the matched certificate record.
        </ResponseField>

        <ResponseField name="candidate_number" type="string">
          The candidate number from the original confirmation request.
        </ResponseField>

        <ResponseField name="year" type="string">
          The examination year from the original confirmation request.
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp of when the confirmation was made.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Pagination metadata for the result set.
    </ResponseField>
  </Expandable>
</ResponseField>

## Success Response

**Status: `200 OK`**

```json theme={null}
{
  "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) |