{
  "openapi": "3.1.0",
  "info": {
    "title": "TRCN Teacher Verification API",
    "summary": "Public registration lookup for Nigerian teachers.",
    "description": "Verify any Nigerian teacher's TRCN registration, certificate, and license status programmatically. Free public REST endpoint, no API key required. Maintained by the Teachers Registration Council of Nigeria (TRCN), the statutory body that regulates the teaching profession in Nigeria under the TRCN Act, CAP T3, LFN 2004.",
    "version": "1.0.0",
    "contact": {
      "name": "TRCN Integrations Team",
      "url": "https://trcn.gov.ng/contact"
    },
    "license": {
      "name": "Public service — no licence fee",
      "url": "https://trcn.gov.ng/code-of-conduct"
    },
    "termsOfService": "https://trcn.gov.ng/cookie-policy"
  },
  "servers": [
    {
      "url": "https://api.trcn.gov.ng",
      "description": "Production"
    }
  ],
  "paths": {
    "/teacher/verify-license": {
      "get": {
        "operationId": "verifyTeacherLicense",
        "summary": "Verify a teacher by registration number, TID, NIN, email, or phone",
        "description": "Looks up a Nigerian teacher in the TRCN register and returns their certificate and license status. The `searchTerm` parameter accepts multiple identifier types — the API auto-detects which based on the value's shape.\n\n**HTTP status semantics**: a 200 is returned both when a teacher is found and when no record matches. Read the `found` boolean to distinguish. Non-200 responses indicate a request or server error, not 'no match'.\n\n**Caching**: responses may be cached by intermediate proxies for up to 5 minutes. For longer-lived caching on the client, persist `verifiedAt` alongside the response so you can prove when the check was performed.",
        "tags": ["Verification"],
        "parameters": [
          {
            "name": "searchTerm",
            "in": "query",
            "required": true,
            "description": "Identifier to look up. Accepted formats: TRCN registration number (e.g. `TRCN/ABJ/2024/123456`), Teacher ID (e.g. `1234567`), NIN (11 digits), email address, or Nigerian phone number.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "example": "TRCN/ABJ/2024/123456"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lookup completed. Inspect `found` to determine whether a teacher matched.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResult"
                },
                "examples": {
                  "found": {
                    "summary": "Teacher found, license currently valid",
                    "value": {
                      "found": true,
                      "name": "Adeyemi John Olumide",
                      "tId": "1234567",
                      "status": "Licensed",
                      "state": "Lagos",
                      "teacher": {
                        "name": "Adeyemi John Olumide",
                        "tId": "1234567",
                        "state": "Lagos",
                        "category": "Professional",
                        "photoUrl": "https://api.trcn.gov.ng/file/proxy/..."
                      },
                      "certificate": {
                        "status": "VERIFIED",
                        "regNo": "TRCN/ABJ/2024/123456",
                        "issueDate": "2024-01-15"
                      },
                      "license": {
                        "status": "VALID",
                        "issueDate": "2024-01-15",
                        "expiryDate": "2027-01-14",
                        "daysRemaining": 612
                      },
                      "verifiedAt": "2026-05-18T15:30:00.000Z"
                    }
                  },
                  "notFound": {
                    "summary": "No teacher matched the search term",
                    "value": {
                      "found": false,
                      "verifiedAt": "2026-05-18T15:30:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request — `searchTerm` was missing, empty, or whitespace only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 400,
                  "message": "searchTerm query parameter is required",
                  "error": "Bad Request"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests — rate limit exceeded for the source IP. Retry with exponential back-off (start at 1s, max 3 retries)."
          },
          "500": {
            "description": "Internal Server Error — a transient backend issue. Check trcn.gov.ng/status for incident updates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VerificationResult": {
        "type": "object",
        "required": ["found", "verifiedAt"],
        "properties": {
          "found": {
            "type": "boolean",
            "description": "True when a TRCN record matched the search term."
          },
          "name": {
            "type": "string",
            "description": "Convenience flattening of `teacher.name`. Present only when `found = true`."
          },
          "tId": {
            "type": "string",
            "description": "Convenience flattening of `teacher.tId`. Present only when `found = true`."
          },
          "status": {
            "type": "string",
            "enum": ["Licensed", "Expired", "Unlicensed"],
            "description": "Convenience flattening of `license.status` mapped to a display-friendly label."
          },
          "state": {
            "type": "string",
            "description": "State of origin where TRCN holds the registration."
          },
          "teacher": {
            "$ref": "#/components/schemas/Teacher",
            "description": "Present only when `found = true`."
          },
          "certificate": {
            "$ref": "#/components/schemas/Certificate"
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "verifiedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Server timestamp when the lookup ran. Persist alongside any cached response."
          }
        }
      },
      "Teacher": {
        "type": "object",
        "required": ["name", "tId"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Concatenated `lastName firstName middleName` as TRCN holds them."
          },
          "tId": {
            "type": "string",
            "description": "Teacher ID. Stable across name changes. Use `certificate.regNo` for cross-system identity."
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "category": {
            "type": "string",
            "nullable": true,
            "description": "Registration category (e.g. Professional, Associate)."
          },
          "photoUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Optional photo URL. May be present but not guaranteed; do not rely on it for identity confirmation in production flows."
          }
        }
      },
      "Certificate": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["VERIFIED", "NOT_FOUND"],
            "description": "Whether TRCN holds a verified certificate for the teacher."
          },
          "regNo": {
            "type": "string",
            "nullable": true,
            "description": "Canonical TRCN registration number — use this as the stable cross-system identifier.",
            "example": "TRCN/ABJ/2024/123456"
          },
          "issueDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "ISO-8601 date the certificate was issued (YYYY-MM-DD)."
          }
        }
      },
      "License": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["VALID", "EXPIRED", "NOT_FOUND"],
            "description": "Current licensing status. Anything other than VALID should be treated as 'not currently licensed'."
          },
          "issueDate": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "expiryDate": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "daysRemaining": {
            "type": "integer",
            "nullable": true,
            "description": "Days until expiry, or negative if already expired."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["statusCode", "message"],
        "properties": {
          "statusCode": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          },
          "error": {
            "type": "string",
            "description": "NestJS-standard error category, e.g. 'Bad Request', 'Internal Server Error'."
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Verification",
      "description": "Public teacher-registration lookup endpoints."
    }
  ],
  "externalDocs": {
    "description": "Human-readable developer guide",
    "url": "https://trcn.gov.ng/developers/teacher-verification-api"
  }
}