API Documentation

Complete developer guide for integrating VerifyChain's blockchain verification into your applications

Quick Navigation

Authentication

Secure your API requests with API keys and OAuth 2.0

All API requests require authentication using your API key. Include your API key in the Authorization header of each request.

curl -X GET "https://api.verifychain.us/v1/documents" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"

Getting Your API Key

1. Log in to your VerifyChain dashboard
2. Navigate to Settings → API Keys
3. Click "Generate New Key"
4. Copy and securely store your key

Base URL: https://api.verifychain.us/v1/

Document Verification

Upload, verify, and manage document verification requests

POST /documents/upload

Upload a document for verification

Parameters

Parameter Type Required Description
file File Required Document file (PDF, JPG, PNG)
document_type String Required Type of document (degree, certificate, transcript)
issuer_id String Optional ID of the issuing institution
metadata Object Optional Additional document metadata

Example Request

curl -X POST "https://api.verifychain.us/v1/documents/upload" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@degree.pdf" \ -F "document_type=degree" \ -F "issuer_id=university_123"

Example Response

{ "success": true, "document_id": "doc_abc123xyz", "verification_url": "https://verify.verifychain.us/doc_abc123xyz", "blockchain_hash": "0x8f14e45fceea167a5a36dedd4bea2543", "status": "pending_verification", "created_at": "2024-01-15T10:30:00Z" }
GET /documents/{document_id}/verify

Verify the authenticity of a document

Example Response

{ "success": true, "document_id": "doc_abc123xyz", "verification_status": "verified", "blockchain_confirmed": true, "issuer_verified": true, "tamper_detected": false, "verification_details": { "issued_date": "2023-06-15", "issuer": "Stanford University", "recipient": "John Doe", "document_type": "Bachelor's Degree" } }

Certificate Management

Generate and manage verification certificates

POST /certificates/generate

Generate a verification certificate

GET /certificates/{certificate_id}

Retrieve certificate details

GET /certificates

List all certificates

Webhooks

Real-time notifications for verification events

Webhooks allow you to receive real-time notifications when verification events occur.

Webhook Events

  • document.uploaded - Document successfully uploaded
  • document.verified - Document verification completed
  • document.failed - Document verification failed
  • certificate.generated - Verification certificate created

Example Webhook Payload

{ "event": "document.verified", "timestamp": "2024-01-15T10:35:00Z", "data": { "document_id": "doc_abc123xyz", "status": "verified", "verification_url": "https://verify.verifychain.us/doc_abc123xyz" } }

Error Handling

Understanding API error responses and status codes

HTTP Status Codes

Code Status Description
200 OK Request successful
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
404 Not Found Resource not found
429 Rate Limited Too many requests
500 Server Error Internal server error

Error Response Format

{ "success": false, "error": { "code": "INVALID_DOCUMENT_TYPE", "message": "Unsupported document type provided", "details": "Supported types: degree, certificate, transcript" } }

SDKs & Libraries

Official libraries for popular programming languages

JavaScript/Node.js

npm install verifychain-sdk

Python

pip install verifychain

Java

Maven dependency available

PHP

composer require verifychain/sdk

Quick Start Example (JavaScript)

const VerifyChain = require('verifychain-sdk'); const client = new VerifyChain({ apiKey: 'your_api_key_here' }); // Upload and verify a document async function verifyDocument() { try { const result = await client.documents.upload({ file: './degree.pdf', documentType: 'degree', issuerId: 'university_123' }); console.log('Document uploaded:', result.document_id); console.log('Verification URL:', result.verification_url); } catch (error) { console.error('Error:', error.message); } }