API Documentation PRIVATE BETA

Everything you need to integrate human verification into your platform. Two lines of code. Sub-50ms response. Zero data liability.

Overview

The POY Verify API provides REST endpoints for verifying humans, stamping content, and querying trust scores. All endpoints return JSON and use standard HTTP status codes.

Base URL: https://api.poyverify.com/v1

All API calls require authentication via API key. Responses are returned in under 50 milliseconds globally.

Authentication

Authenticate all requests by including your API key in the Authorization header:

Authorization: Bearer poy_live_xxxxxxxxxxxxxxxxxxxx

API keys are scoped to your platform with per-key rate limiting and domain restrictions. Get your API key by joining the waitlist.

Quick Start

JavaScript

npm install @poyverify/sdk

import { POYVerify } from '@poyverify/sdk';
const poy = new POYVerify('poy_live_xxxxxxxxxxxx');

// Verify a user is human
const result = await poy.verify(userId);
console.log(result.verified); // true
console.log(result.trustScore); // 98.2

// Stamp content as human-made
const stamp = await poy.stamp({
  content: articleBody,
  type: 'text'
});
console.log(stamp.hash); // "a3f9c2e1..."

Python

pip install poyverify

from poyverify import POYVerify

poy = POYVerify(api_key="poy_live_xxxxxxxxxxxx")

# Verify a user is human
result = poy.verify(user_id)
print(result.verified)    # True
print(result.trust_score) # 98.2

# Stamp content
stamp = poy.stamp(content=article, type="text")
print(stamp.hash) # "a3f9c2e1..."

cURL

curl -X POST https://api.poyverify.com/v1/verify \
  -H "Authorization: Bearer poy_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_123"}'

SDKs

Official SDKs for every major language and platform:

Verify Human

{
  "verified": true,
  "human_status": "confirmed",
  "trust_score": 98.2,
  "enrollment_active": true,
  "verified_since": "2026-03-15T00:00:00Z",
  "checks": {
    "biometric_liveness": true,
    "device_attestation": true,
    "enrollment_valid": true
  }
}

{
  "verified": false,
  "human_status": "unconfirmed",
  "trust_score": 0,
  "reason": "no_enrollment"
}

Stamp Content

{
  "stamped": true,
  "stamp_id": "stmp_a3f9c2e17b4d",
  "content_hash": "a3f9c2e17b4d8f2a6c9e...",
  "signature": "MEUCIQD7x8kL2F4N3K5M...",
  "timestamp": "2026-04-04T12:00:00Z",
  "human_verified": true
}

Check Stamp

{
  "verified": true,
  "human_verified": true,
  "stamp_age_seconds": 3600,
  "content_integrity": "intact",
  "creator_trust_score": 98.2
}

Trust Score

{
  "user_id": "user_123",
  "trust_score": 98.2,
  "max_score": 100,
  "signals": {
    "biometric_liveness": { "verified": true, "points": 60 },
    "email": { "verified": true, "points": 10 },
    "phone": { "verified": true, "points": 10 },
    "device": { "verified": true, "points": 10 },
    "voice": { "verified": false, "points": 0 },
    "social": { "verified": true, "points": 5 }
  },
  "verified_since": "2026-03-15T00:00:00Z",
  "last_verified": "2026-04-04T11:30:00Z"
}

Enrollment

User enrollment happens on-device through the POY Verify mobile SDK. The enrollment flow:

1. Initialize SDK with your API key
2. Call poy.enroll() - triggers camera liveness check
3. Device Secure Enclave generates key pair
4. Public key registered with POY registry
5. User receives verified status
// Entire flow takes 30 seconds

After enrollment, the user is a verified human on your platform. Verification status persists across sessions and can be checked via the Verify endpoint.

Webhooks

Configure webhooks to receive real-time notifications for verification events:

{
  "event": "verification.completed",
  "data": {
    "user_id": "user_123",
    "verified": true,
    "trust_score": 98.2,
    "timestamp": "2026-04-04T12:00:00Z"
  }
}

Webhook events: verification.completed, enrollment.created, stamp.created, trust.changed, enrollment.revoked

Error Codes

Rate Limits

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.