Skip to main content

OpenAPI Reference

VeriMe provides a complete OpenAPI 3.1.0 specification for the VeriMe API, offering both human-readable documentation and machine-readable schema definitions.

Interactive API Documentation​

Visit the Interactive API Reference to explore:

  • 📋 Complete endpoint documentation - Every API endpoint with detailed descriptions
  • 📝 Request/response schemas - Full schema definitions with data types and constraints
  • 💡 Live examples - Real request and response examples for every endpoint
  • 🔍 Schema explorer - Navigate through complex data structures
  • 🎨 Try it out - Test endpoints directly from the documentation (sandbox environment)

API Specification File​

The OpenAPI specification is available at:

  • File location: static/openapi/verime-api.yaml
  • Format: OpenAPI 3.1.0 (YAML)
  • Access: Download OpenAPI Spec
Source of Truth

The OpenAPI specification in this repository is synchronized from the master API specification repository. Do not manually edit the YAML file - all changes must be made in the source repository.

Using the OpenAPI Spec​

For API Consumers​

Generate client libraries in your preferred language:

# Using OpenAPI Generator
npx @openapitools/openapi-generator-cli generate \
  -i https://preview-docs.verime.coop/openapi/verime-api.yaml \
  -g typescript-axios \
  -o ./src/generated/verime-client

# Using Swagger Codegen
swagger-codegen generate \
  -i https://preview-docs.verime.coop/openapi/verime-api.yaml \
  -l python \
  -o ./verime_client

For Postman Users​

Import the OpenAPI spec directly into Postman:

  1. Open Postman
  2. Click Import button
  3. Select Link tab
  4. Paste: https://preview-docs.verime.coop/openapi/verime-api.yaml
  5. Click Continue to import the collection

For API Testing​

Use tools like Dredd or Prism to test against the spec:

# API mocking with Prism
npx @stoplight/prism-cli mock \
  static/openapi/verime-api.yaml

# Contract testing with Dredd
dredd static/openapi/verime-api.yaml \
  https://sandbox.verime.coop/api

API Sections​

The VeriMe API is organized into the following sections:

Verification Endpoints​

Core identity verification operations:

  • POST /v1/verify/isPerson - Verify if a subject is a real person
  • POST /v1/verify/hasPresence - Check recent activity presence

View full documentation →

Voucher Management​

Manage verification vouchers:

  • POST /v1/vouchers/issue - Issue new vouchers
  • POST /v1/vouchers/redeem - Redeem a voucher
  • POST /v1/vouchers/purchase - Purchase voucher balance
  • GET /v1/vouchers/inventory - Check voucher inventory
  • GET /v1/vouchers/{voucherCode} - Inspect voucher status

View full documentation →

Receipts​

Audit trail and receipt management:

  • GET /v1/receipts - List receipts with filtering
  • GET /v1/receipts/{receiptId} - Retrieve specific receipt

View full documentation →

Reports​

Analytics and usage reports:

  • GET /v1/reports/verifications - Aggregated verification metrics
  • GET /v1/reports/vouchers - Voucher usage analytics

View full documentation →

Operations​

System health and status:

  • GET /v1/cache/status - VeriFactCache synchronization status

View full documentation →

Authentication​

All API endpoints require authentication using the SubscriberHMAC security scheme:

X-Subscriber-Key: your-subscriber-key
X-Signature: HMAC-SHA256(canonical-request)
X-Nonce: unique-nonce-value

Important: Nonces expire after 2 minutes. Each request must include a fresh nonce to prevent replay attacks.

See Authentication Guide for implementation details.

Environments​

Production​

  • Base URL: https://verime.coop/api
  • Use for: Live production operations
  • Credentials: Production API keys

Sandbox​

  • Base URL: https://sandbox.verime.coop/api
  • Use for: Development and testing
  • Credentials: Sandbox API keys
Development Best Practice

Always develop and test in the sandbox environment before deploying to production.

Versioning​

Current API version: 1.0.0

The VeriMe API uses URL path versioning (/v1/). When breaking changes are introduced:

  • A new version path will be created (e.g., /v2/)
  • Previous versions remain supported for a deprecation period
  • Migration guides will be provided in the documentation

OpenAPI Features​

Schema Validation​

All request and response bodies are validated against JSON schemas defined in the OpenAPI spec:

components:
  schemas:
    VerificationRequest:
      type: object
      required: [invocationId, localAccountId, subject, verificationContext]
      properties:
        invocationId:
          type: string
          description: ULID supplied by subscriber to ensure idempotency
        # ... additional properties

Response Examples​

Every endpoint includes realistic examples:

{
  "verificationOutcome": {
    "result": "verified",
    "confidence": 0.97,
    "confidenceBand": "high",
    "reasonCodes": ["cache_match", "biometric_verification"],
    "expiresAt": "2024-09-01T00:00:00Z"
  },
  "maskedFact": { ... },
  "receipt": { ... }
}

Error Responses​

Standard error response format across all endpoints:

{
  "error": {
    "code": "voucher.insufficient_balance",
    "message": "Voucher balance exhausted for product standard-isPerson.",
    "details": [
      "Purchase additional vouchers via /api/v1/vouchers/purchase."
    ]
  },
  "receipt": { ... }
}

Integration Support​

Need Help?​

Reporting Issues​

Found a problem with the API specification?

  1. Check the Interactive API Reference for the latest version
  2. Report issues via GitHub
  3. For urgent API issues, contact support@verime.coop

Next Steps​

🚀 Quick Start

Follow the Getting Started Guide to make your first API call.

📖 Deep Dive

Explore detailed endpoint documentation in the API Reference.