Developer Docs

API Documentation

Integrate blockchain certificate verification into your application.

Quick Start

Verify a certificate with a single API call:

GET https://api.onchaincert.org/v1/certificates/verify?certId=OCC-ABC123-XYZ

Base URL

https://api.onchaincert.org/v1

Current API version: v1

Endpoints

GET /v1/certificates/verify Public

Verify the authenticity of a certificate on the blockchain.

Query Parameters

Parameter	Type	Description
certId	string	Required. The certificate ID to verify.

Success Response

{
  "success": true,
  "valid": true,
  "certId": "CERT-1234567890-ABC123",
  "certHash": "0x7f83b1657ff1fc...",
  "issuedAt": "2024-12-01T10:30:00.000Z",
  "metadata": {
    "recipientName": "John Doe",
    "certificateTitle": "Web Development Bootcamp",
    "issuerName": "TechAcademy"
  }
}

Not Found Response

{
  "success": true,
  "valid": false,
  "certId": "INVALID-ID",
  "certHash": null,
  "issuedAt": null,
  "metadata": null
}

POST /v1/certificates/issue Auth Required

Issue a new certificate on the blockchain. Requires authentication.

Headers

Header	Value
Authorization	Bearer <access_token>
Content-Type	application/json

Request Body

{
  "certId": "CERT-1234567890-ABC123",
  "certHash": "0x7f83b1657ff1fc...",
  "metadata": {
    "recipientName": "John Doe",
    "certificateTitle": "Web Development Bootcamp",
    "issuerName": "TechAcademy"
  }
}

Success Response

{
  "success": true,
  "certId": "CERT-1234567890-ABC123",
  "txHash": "0x123abc...",
  "blockNumber": 12345678
}

GET /v1/subscription Auth Required

Get the current user's subscription status and quota.

Success Response

{
  "success": true,
  "subscription": {
    "plan": "starter",
    "monthly_quota": 100,
    "monthly_used": 25,
    "status": "active"
  }
}

GET /v1/health Public

Check API health status.

Response

{
  "status": "ok",
  "version": "1",
  "timestamp": "2024-12-02T12:00:00.000Z"
}

Rate Limiting

API endpoints are rate limited to prevent abuse:

Endpoint	Limit
/v1/certificates/verify	30 requests/minute per IP
/v1/certificates/issue	10 requests/minute per user
/v1/subscription	20 requests/minute per IP
/v1/checkout	5 requests/minute per IP

When rate limited, you'll receive a 429 response with Retry-After header.

Error Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid token
429	Too Many Requests - Rate limited
500	Internal Server Error

Code Examples

JavaScript / Node.js

const API_BASE = 'https://api.onchaincert.org/v1';

async function verifyCertificate(certId) {
  const response = await fetch(
    `${API_BASE}/certificates/verify?certId=${certId}`
  );
  const data = await response.json();
  return data;
}

// Usage
const result = await verifyCertificate('OCC-ABC123-XYZ');
console.log(result.valid); // true or false

Python

import requests

API_BASE = "https://api.onchaincert.org/v1"

def verify_certificate(cert_id):
    response = requests.get(
        f"{API_BASE}/certificates/verify",
        params={"certId": cert_id}
    )
    return response.json()

# Usage
result = verify_certificate("OCC-ABC123-XYZ")
print(result["valid"])  # True or False

cURL

curl "https://api.onchaincert.org/v1/certificates/verify?certId=OCC-ABC123-XYZ"

Need Help?

If you have questions or need assistance with the API, contact our support team.

Contact Developer Support