Blockchain Credentials API Integration Guide

API Integration Overview

Integrate blockchain credential issuance directly into your systems with the OnChainCert API. This guide covers everything developers need to know.

Getting Started

Authentication

All API requests require authentication via API key:

Authorization: Bearer YOUR_API_KEY

Get your API key from the OnChainCert dashboard under Settings → API.

Base URL

https://api.onchaincert.org/v1

Response Format

All responses are JSON:

{
  "success": true,
  "data": { ... },
  "error": null
}

Core Endpoints

Issue Certificate

POST /certificates

{
  "recipientName": "Jane Doe",
  "recipientEmail": "[email protected]",
  "title": "Course Completion Certificate",
  "description": "Successfully completed Python Fundamentals",
  "issueDate": "2025-12-07",
  "certificateFile": "base64_encoded_pdf",
  "metadata": {
    "courseId": "PY101",
    "grade": "A",
    "hours": 40
  }
}

Response:

{
  "success": true,
  "data": {
    "certificateId": "CERT-ABC123-XYZ789",
    "transactionHash": "0x7f83b1657ff1fc53...",
    "verificationUrl": "https://onchaincert.org/verify/CERT-ABC123-XYZ789",
    "status": "confirmed"
  }
}

Verify Certificate

GET /certificates/{certificateId}/verify

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "certificateId": "CERT-ABC123-XYZ789",
    "recipientName": "Jane Doe",
    "title": "Course Completion Certificate",
    "issueDate": "2025-12-07",
    "issuer": {
      "name": "Example Academy",
      "verified": true
    },
    "blockchain": {
      "network": "polygon",
      "transactionHash": "0x7f83b1657ff1fc53...",
      "blockNumber": 12345678
    }
  }
}

Get Certificate Details

GET /certificates/{certificateId}

Returns full certificate details including metadata.

List Certificates

GET /certificates

Query parameters:

• page: Page number (default: 1)
• limit: Results per page (default: 20, max: 100)
• status: Filter by status
• from: Start date
• to: End date

Bulk Operations

Bulk Issue

POST /certificates/bulk

{
  "certificates": [
    {
      "recipientName": "Jane Doe",
      "recipientEmail": "[email protected]",
      "title": "Certificate Title",
      "certificateFile": "base64_pdf"
    },
    {
      "recipientName": "John Smith",
      "recipientEmail": "[email protected]",
      "title": "Certificate Title",
      "certificateFile": "base64_pdf"
    }
  ]
}

Bulk Status

GET /certificates/bulk/{batchId}

Check status of bulk issuance operation.

Webhooks

Configure Webhooks

Set webhook URL in dashboard under Settings → Webhooks.

Webhook Events

certificate.issued

{
  "event": "certificate.issued",
  "data": {
    "certificateId": "CERT-ABC123",
    "status": "confirmed",
    "transactionHash": "0x..."
  },
  "timestamp": "2025-12-07T10:30:00Z"
}

certificate.verified

{
  "event": "certificate.verified",
  "data": {
    "certificateId": "CERT-ABC123",
    "verifierInfo": { ... }
  },
  "timestamp": "2025-12-07T11:00:00Z"
}

Error Handling

Error Response Format

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Recipient email is required",
    "field": "recipientEmail"
  }
}

Common Error Codes

• UNAUTHORIZED: Invalid or missing API key
• INVALID_REQUEST: Request validation failed
• NOT_FOUND: Certificate not found
• RATE_LIMITED: Too many requests
• INTERNAL_ERROR: Server error

Rate Limits

• Standard: 100 requests/minute
• Bulk operations: 10 requests/minute
• Verification: 1000 requests/minute

Code Examples

Node.js

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://api.onchaincert.org/v1',
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

async function issueCertificate(data) {
  const response = await client.post('/certificates', data);
  return response.data;
}

Python

import requests

headers = {'Authorization': f'Bearer {API_KEY}'}
base_url = 'https://api.onchaincert.org/v1'

def issue_certificate(data):
    response = requests.post(
        f'{base_url}/certificates',
        json=data,
        headers=headers
    )
    return response.json()

Best Practices

1. Store Certificate IDs: Save returned certificate IDs for future reference
2. Handle Webhooks: Use webhooks for async confirmation
3. Implement Retry Logic: Handle transient failures gracefully
4. Validate Input: Check data before API calls
5. Secure API Keys: Never expose keys in client-side code

Get API access →

API questions? Contact us.