> ## 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 Started with WAEC Certificate Digitization

> Make your first API call in under 5 minutes — register an account, obtain a Bearer token, upload a certificate, and run your first verification.

This guide walks you through confirming your first WAEC certificate using the API. You will need your Institution account and API Secret key ready before you begin.

## Prerequisites

* An Institution account on the Digital Certificate platform
* An API Secret key — generate one from your Institution profile. See [Authentication](/authentication) for details.
* `curl` or any HTTP client

## Steps

<Steps>
  <Step title="Get your API Secret key">
    Log in to the Digital Certificate platform and navigate to your Institution profile. Generate an API Secret key. You will pass this key in the `X-DigiCert-Secret` header of every request.

    The platform has two environments — use the sandbox base URL and a sandbox key while developing, then switch to production when you are ready to go live.

    | Environment | Base URL                                        |
    | ----------- | ----------------------------------------------- |
    | Sandbox     | `https://api.smartdocument.org/api/v1/external` |
    | Production  | `https://api.waec.org/api/v1/external`          |

    <Note>
      Store your API Secret key securely — in an environment variable or secrets manager. Never hard-code it in your application or commit it to version control.
    </Note>
  </Step>

  <Step title="Confirm a certificate">
    Send a `POST` request to `/certificate/confirm` with the candidate's country, candidate number, and examination year. You can include multiple certificates in a single request.

    The example below uses the sandbox URL. Replace it with the production URL when you go live.

    ```bash theme={null}
    curl --request POST \
      --url https://api.smartdocument.org/api/v1/external/certificate/confirm \
      --header 'X-DigiCert-Secret: YOUR_SANDBOX_SECRET_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "certificates": [
          {
            "country": "NG",
            "candidate_number": "4251212052",
            "year": "2022"
          }
        ]
      }'
    ```

    A successful response returns `200 OK` with the confirmation results:

    ```json theme={null}
    {
      "status": "OK",
      "message": "Request completed",
      "data": [
        {
          "is_error": false,
          "request": {
            "country": "NG",
            "candidate_number": "4251212052",
            "year": "2022"
          },
          "message": "Certificate already verified.",
          "result": {
            "id": "ea9065b4-563b-48c7-a98f-0594948fc415",
            "country": "NG",
            "country_name": "Nigeria",
            "status": "Match Found",
            "candidate_number": "4251212052",
            "year": "2022",
            "certificate": {
              "surname": "AYANTUNJI",
              "firstname": "ELIZABETH",
              "othernames": "BUNMI",
              "candidate_number": "4251212052",
              "period": "WASSCE (SC) 2022",
              "year": "2022",
              "dob": "2003-10-04",
              "gender": "FEMALE",
              "center": "ISIU SENIOR GRAMMAR SCHOOL, ISIU",
              "certificate_number": "33607486",
              "exam_title": "WASSCE (SC) 2022",
              "results": [
                { "subject": "ENGLISH LANGUAGE", "grade": "D7" },
                { "subject": "GENERAL MATHEMATICS", "grade": "E8" }
              ]
            },
            "created_at": "2026-05-21T07:39:52.000000Z"
          }
        }
      ]
    }
    ```

    <Note>
      The API always returns `200 OK` even when a certificate is not found. Check each entry's `result` field — a `null` value means no match was found for that candidate.
    </Note>
  </Step>

  <Step title="Check your confirmation history">
    Retrieve a log of all confirmations on your account using `GET /certificate/confirmation-history`.

    ```bash theme={null}
    curl --request GET \
      --url 'https://api.smartdocument.org/api/v1/external/certificate/confirmation-history?year=2022' \
      --header 'X-DigiCert-Secret: YOUR_SANDBOX_SECRET_KEY'
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={3}>
  <Card title="Certificates" icon="certificate" href="/concepts/certificates">
    Understand how confirmation records are structured and what data is returned.
  </Card>

  <Card title="Confirm guide" icon="circle-check" href="/guides/confirm-certificates">
    Detailed guide on confirming certificates in bulk and handling not-found results.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/overview">
    Full endpoint reference with every parameter, response schema, and example.
  </Card>
</CardGroup>