Developer Documentation

Integrate human verification into your platform in minutes. Everything you need to prove your users are real.

Quick Start

Install the SDK for your language, initialize with your API key, and verify your first user in three lines of code.

JavaScript 
// JavaScript SDK
import { POYVerify } from '@poyverify/sdk';

const poy = new POYVerify({ apiKey: 'your-api-key' });

const result = await poy.verify(userId);

if (result.isHuman) {
  /* trusted user */
}
Python 
# Python SDK
from poyverify import POYVerify

poy = POYVerify(api_key="your-api-key")

result = poy.verify(user_id)

if result.is_human:
    # trusted user

Authentication

All API requests require a valid API key sent via the Authorization header using the Bearer token scheme.

HTTP Header 
Authorization: Bearer your-api-key

You can generate API keys from the POY Dashboard. Each key is scoped to a single project and can be revoked at any time.

⚠
Never expose your API key in client-side code or public repositories. Use environment variables and server-side calls only.

Base URL

https://poyverify.com/api/poy

Core Endpoints

POST /api/poy/verify

Perform a full human verification check on a user. Returns verification status, trust score, and metadata.

Request Body

JSON
{
  "userId": "usr_abc123",
  "checkType": "full",
  "metadata": {
    "ip": "203.0.113.42",
    "userAgent": "Mozilla/5.0..."
  }
}

Response

JSON - 200 OK
{
  "isHuman": true,
  "trustScore": 94,
  "poyId": "PoY #00482A1",
  "verifiedAt": "2026-04-07T12:00:00Z",
  "checks": {
    "liveness": "pass",
    "device": "pass",
    "behavioral": "pass"
  }
}
GET /api/poy/check?userId=usr_abc123

Quick boolean humanity check. Returns a simple true/false result with minimal latency - ideal for real-time gating.

Response

JSON - 200 OK
{
  "isHuman": true,
  "poyId": "PoY #00482A1"
}
POST /api/poy/public-enroll

Public enrollment endpoint. No authentication required. Rate limited to 10 requests per minute per IP. Used for onboarding new users directly from your front end.

Request Body

JSON
{
  "email": "user@example.com",
  "displayName": "Jane Doe",
  "platform": "your-app-name"
}

Response

JSON - 201 Created
{
  "poyId": "PoY #009F3B2",
  "enrollmentUrl": "https://poyverify.com/enroll?token=enr_...",
  "expiresAt": "2026-04-08T12:00:00Z"
}
GET /api/poy/profile?poyId=PoY%20%2300482A1

Public profile lookup. Returns non-sensitive verification status and badge information for a given PoY ID.

Response

JSON - 200 OK
{
  "poyId": "PoY #00482A1",
  "isVerified": true,
  "badgeLevel": "verified",
  "trustScore": 94,
  "verifiedSince": "2026-01-15T08:00:00Z"
}

Content Stamps

POST /api/poy/stamp/create

Stamp a piece of content as human-made. Generates a unique stamp ID and cryptographic signature tied to the creator's PoY identity.

Request Body

JSON
{
  "contentHash": "sha256:a1b2c3d4...",
  "contentType": "article",
  "title": "My Blog Post",
  "url": "https://example.com/post"
}

Response

JSON - 201 Created
{
  "stampId": "stmp_7f8a9b0c1d2e",
  "signature": "ecdsa:...",
  "createdBy": "PoY #00482A1",
  "createdAt": "2026-04-07T12:30:00Z"
}
POST /api/poy/stamp/verify

Verify that a content stamp is authentic and was created by a verified human.

Request Body

JSON
{
  "stampId": "stmp_7f8a9b0c1d2e"
}

Response

JSON - 200 OK
{
  "valid": true,
  "createdBy": "PoY #00482A1",
  "contentType": "article",
  "stampedAt": "2026-04-07T12:30:00Z",
  "isHumanCreator": true
}

Trust & Authentication

GET /api/poy/trust?userId=usr_abc123

Query the trust score for a user. Returns a 0-100 score based on verification history, behavioral signals, and credential strength.

Response

JSON - 200 OK
{
  "userId": "usr_abc123",
  "trustScore": 94,
  "level": "high",
  "factors": {
    "liveness": 98,
    "device": 90,
    "behavioral": 92,
    "credential": 95
  }
}
POST /api/poy/passkey/register

Initiate WebAuthn passkey registration for a user. Returns a challenge and credential creation options that you pass to the browser's WebAuthn API.

Request Body

JSON
{
  "userId": "usr_abc123",
  "displayName": "Jane Doe"
}

Response

JSON - 200 OK
{
  "challenge": "base64url-encoded-challenge",
  "rp": { "name": "POY Verify", "id": "poyverify.com" },
  "user": {
    "id": "base64url-user-id",
    "name": "Jane Doe",
    "displayName": "Jane Doe"
  },
  "pubKeyCredParams": [
    { "type": "public-key", "alg": -7 }
  ],
  "timeout": 60000
}
POST /api/poy/passkey/authenticate

Authenticate a user with a previously registered WebAuthn passkey. Returns a signed session token on success.

Request Body

JSON
{
  "credentialId": "base64url-credential-id",
  "authenticatorData": "base64url-auth-data",
  "clientDataJSON": "base64url-client-data",
  "signature": "base64url-signature"
}

Response

JSON - 200 OK
{
  "authenticated": true,
  "sessionToken": "poy_sess_...",
  "expiresAt": "2026-04-07T14:00:00Z",
  "userId": "usr_abc123"
}

Rate Limits

API rate limits are enforced per API key. Exceeding the limit returns a 429 status code with a Retry-After header.

Plan Requests / Minute Requests / Day
Free 60 1,000
Pro 300 50,000
Enterprise Custom Unlimited
ⓘ
The /api/poy/public-enroll endpoint has a separate limit of 10 requests per minute per IP address, regardless of API key.

Error Codes

All errors return a JSON body with a code and human-readable message field.

Error Response Format
{
  "error": {
    "code": 401,
    "message": "Invalid or missing API key."
  }
}
Status Meaning Common Cause
400 Bad Request Missing required fields or invalid format
401 Unauthorized Missing or invalid API key
403 Forbidden API key lacks permission for this endpoint
404 Not Found User or resource does not exist
429 Too Many Requests Rate limit exceeded - check Retry-After header
500 Internal Server Error Unexpected server error - retry or contact support

SDKs

Official SDKs handle authentication, retries, and error parsing so you can focus on your integration.

JavaScript / Node.js

@poyverify/sdk

Works in Node.js 18+ and modern browsers. TypeScript support included.

npm install @poyverify/sdk

Python

poyverify

Python 3.8+ with async/await support. Fully typed with type hints.

pip install poyverify

Need a different language? The REST API works with any HTTP client. See the Authentication section for details.

Webhooks

Receive real-time notifications when verification events occur. Configure webhook URLs in your POY Dashboard.

Event Types

user.verified Fired when a user completes verification successfully
user.failed Fired when a verification attempt fails
stamp.created Fired when a new content stamp is created
trust.changed Fired when a user's trust score changes significantly
passkey.registered Fired when a user registers a new passkey

Webhook Payload

JSON
{
  "event": "user.verified",
  "timestamp": "2026-04-07T12:00:00Z",
  "data": {
    "userId": "usr_abc123",
    "poyId": "PoY #00482A1",
    "trustScore": 94
  }
}

Signature Verification

Every webhook request includes an X-POY-Signature header containing an HMAC-SHA256 signature of the request body. Verify this signature using your webhook secret to confirm authenticity.

JavaScript
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}