Skip to main content

Verification Check API

The /verifications/check endpoint is the core API for verifying researcher identities against configured policies.

Overview​

This API allows subscribers to check if a researcher (identified by email) meets a specific verification policy. The endpoint handles various scenarios including:

  • Existing verified identities
  • Pending vouchers
  • Auto-issuing new vouchers
  • Rate limiting and service health checks

Decision Flow​

The following diagram illustrates the complete decision tree for the verification check endpoint:

Viewing the Diagram

This flowchart is complex and detailed. For the best viewing experience:

  • Scroll horizontally - The diagram extends beyond the page width for better readability
  • Zoom in your browser - Use Ctrl/Cmd + (or Ctrl/Cmd + mouse wheel) to enlarge
  • Zoom out for overview - Use Ctrl/Cmd - to see the full structure
  • Reset zoom - Use Ctrl/Cmd 0 to return to normal size
  • View full-page diagram → - Opens the diagram in a dedicated page for easier navigation
Request Parameters

Inputs:

  • email / subject - Subject identifier
  • policy_id - Verification policy to check
  • auto_issue_on_not_found (boolean) - Auto-issue voucher if not found
  • on_pending_voucher (enum) - CONTINUE | RESEND | SUPERSEDE (optional)
  • correlation_id, Idempotency-Key - Tracking headers
Self-Signup Flow

Account may be created later without a voucher (self-signup). When the person signs in/creates an account later, the backend auto-discovers matching active vouchers and links them.

Request Parameters​

Required Parameters​

  • email (string): Email address of the subject to verify
  • policy_id (string): ID of the verification policy to check against

Optional Parameters​

  • auto_issue_on_not_found (boolean): Whether to automatically issue a verification voucher if the subject is not found. Default: false
  • on_pending_voucher (enum): Action to take if an active voucher already exists
    • CONTINUE: Return the existing voucher information (default)
    • RESEND: Resend the verification email (throttled, no charge)
    • SUPERSEDE: Invalidate old voucher and issue a new one
  • correlation_id (string): Client-provided correlation ID for tracking
  • Idempotency-Key (header): Ensures the request is processed only once

Response Statuses​

The API returns different response statuses based on the verification state:

Success Responses (200)​

  • VERIFIED: Subject has a valid, verified identity meeting the policy
  • NOT_FOUND: Subject not found, next action should be to issue a voucher
  • PENDING_VOUCHER: Verification voucher has been sent and is awaiting completion
  • VOUCHER_ISSUED: New verification voucher has been issued and sent

Error Responses​

  • 422 UNPROCESSABLE_ENTITY: Invalid request parameters
  • 429 TOO_MANY_REQUESTS: Rate limit exceeded
  • 402 PAYMENT_REQUIRED: Spending caps exceeded
  • 503 SERVICE_UNAVAILABLE: Service health check failed or delivery unavailable

Notification Model​

info

VeriMe uses an outcome delivery model without requiring webhook configuration.

  • In-app notifications: Subscribers receive notifications when:

    • A voucher is REDEEMED (completed via voucher link)
    • A voucher is COMPLETED_EXTERNALLY (user verified without the voucher)
    • A voucher EXPIRES without being used

  • Optional webhooks: Emit events if configured:

    • verification.completed (includes optional voucher_id)
    • voucher.expired
    • delivery.bounced

  • Billing: Only REDEEMED vouchers are charged. COMPLETED_EXTERNALLY and EXPIRED vouchers are not billed.

Self-Signup Case​

If a person creates a VeriMe account and passes the verification policy without using the voucher link, any active voucher for the same (email, policy, subscriber) combination is automatically set to COMPLETED_EXTERNALLY. The subscriber will see VERIFIED status on the next check.

Example Usage​

Production Environment​

# Check if a researcher is verified
curl -X POST https://verime.coop/api/v1/verifications/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "researcher@university.edu",
    "policy_id": "pol_basic_verification",
    "auto_issue_on_not_found": true
  }'

Sandbox Environment​

# Test in sandbox environment
curl -X POST https://sandbox.verime.coop/api/v1/verifications/check \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "researcher@university.edu",
    "policy_id": "pol_basic_verification",
    "auto_issue_on_not_found": true
  }'
API Endpoints
  • Production: https://verime.coop/api/v1
  • Sandbox: https://sandbox.verime.coop/api/v1

Use the sandbox environment for testing without affecting production data.

See Also​