API Reference
Complete reference for the V.E.R.I.F.Y.™ REST API. Base URL: https://api.verify.25alpha.ai
Authentication
All endpoints except /v1/verify/ping require an API key in the request header.
X-Verify-API-Key: vfy_live_xxxxxxxxxxxxxxxxxxxxxxxx
Never expose your API key in client-side code. Keys are rate-limited by tier.
Health Check
No authentication required. Returns service status and current version.
// Response 200 OK
{
"status": "ok",
"service": "verify",
"version": "1.0.0",
"timestamp": "2026-06-10T00:00:00.000Z"
}Verification Endpoints
All verification endpoints accept POST requests and return a VerificationToken. Feature flags must be enabled per population before the endpoint becomes active.
// Request
{
"user_id": "your_internal_user_id", // required
"document_data": "base64_string", // required for document pipelines
"otp_code": "123456", // required for citizen pipeline
"credential_hash": "sha256_hash", // required for global pipeline
"coppa_consent": true, // required for users under 13/18
"gdpr_consent": true // required for EU users
}
// Response 200 OK — VerificationToken
// Response 503 — Feature flag not yet enabled
// Response 401 — Invalid or missing API key
// Response 400 — Invalid request body// Request
{
"user_id": "your_internal_user_id", // required
"document_data": "base64_string", // required for document pipelines
"otp_code": "123456", // required for citizen pipeline
"credential_hash": "sha256_hash", // required for global pipeline
"coppa_consent": true, // required for users under 13/18
"gdpr_consent": true // required for EU users
}
// Response 200 OK — VerificationToken
// Response 503 — Feature flag not yet enabled
// Response 401 — Invalid or missing API key
// Response 400 — Invalid request body// Request
{
"user_id": "your_internal_user_id", // required
"document_data": "base64_string", // required for document pipelines
"otp_code": "123456", // required for citizen pipeline
"credential_hash": "sha256_hash", // required for global pipeline
"coppa_consent": true, // required for users under 13/18
"gdpr_consent": true // required for EU users
}
// Response 200 OK — VerificationToken
// Response 503 — Feature flag not yet enabled
// Response 401 — Invalid or missing API key
// Response 400 — Invalid request body// Request
{
"user_id": "your_internal_user_id", // required
"document_data": "base64_string", // required for document pipelines
"otp_code": "123456", // required for citizen pipeline
"credential_hash": "sha256_hash", // required for global pipeline
"coppa_consent": true, // required for users under 13/18
"gdpr_consent": true // required for EU users
}
// Response 200 OK — VerificationToken
// Response 503 — Feature flag not yet enabled
// Response 401 — Invalid or missing API key
// Response 400 — Invalid request body// Request
{
"user_id": "your_internal_user_id", // required
"document_data": "base64_string", // required for document pipelines
"otp_code": "123456", // required for citizen pipeline
"credential_hash": "sha256_hash", // required for global pipeline
"coppa_consent": true, // required for users under 13/18
"gdpr_consent": true // required for EU users
}
// Response 200 OK — VerificationToken
// Response 503 — Feature flag not yet enabled
// Response 401 — Invalid or missing API key
// Response 400 — Invalid request body// Request
{
"user_id": "your_internal_user_id", // required
"document_data": "base64_string", // required for document pipelines
"otp_code": "123456", // required for citizen pipeline
"credential_hash": "sha256_hash", // required for global pipeline
"coppa_consent": true, // required for users under 13/18
"gdpr_consent": true // required for EU users
}
// Response 200 OK — VerificationToken
// Response 503 — Feature flag not yet enabled
// Response 401 — Invalid or missing API key
// Response 400 — Invalid request bodyVerificationToken Schema
token_idstring (UUID v4)Globally unique token identifier. The only value you should store.verifiedbooleanTrue if confidence meets the population-specific threshold.populationVerifyPopulationOne of: veteran, federal, edu, athlete, citizen, global.confidencenumber (0.0–1.0)Composite confidence score. Veteran/edu/athlete: ≥0.85. Federal: ≥0.90. Citizen: ≥0.75.timestampstring (ISO 8601)UTC timestamp of verification event.expires_atstring (ISO 8601)Token TTL — 1 hour from issuance by default.arceb_trace_idstring (UUID)Immutable reference to the ARCEB audit log entry.hash_presentbooleanTrue only for global pipeline — indicates continuity hash was stored (PAT-119).behavioral_trustnumber | nullBehavioral trust score 0.0–1.0 (PAT-120). Non-null for citizen pipeline only.compliance_flagsComplianceFlagsObject containing all compliance boolean flags for this verification.ComplianceFlags Schema
ferpa_compliantedu, athleteTrue when FERPA-compliant processing was performed. Always true for edu pipeline.coppa_consentedu, athlete, citizen, globalTrue when explicit COPPA consent was provided by the caller for users under 13.gdpr_consentcitizen, globalTrue when GDPR consent was provided. Required for EU users. Always true for global pipeline.fcra_access_logveteran, federalTrue when an FCRA-compliant access log entry was created.glba_mfacitizen, federalTrue when GLBA-compliant multi-factor authentication was performed.arceb_traceallAlways true. Every verification event writes an immutable ARCEB audit record.Error Codes
200OKVerification completed. Check the verified field in the returned VerificationToken.400Bad RequestInvalid request body. Check the details field for Zod validation errors.401UnauthorizedMissing or invalid X-Verify-API-Key header.503Service UnavailableThe requested population pipeline is not yet enabled. Check flag_key in the response.500Internal Server ErrorVerification failed. Retry with exponential backoff.Frequently Asked Questions
How do I authenticate with the V.E.R.I.F.Y.™ API?
All API requests require an X-Verify-API-Key header containing your tenant API key. Keys are available after signing up for a paid plan. Keys are stored as SHA-256 hashes — the raw key is never persisted.
How do I verify veteran status programmatically?
POST to https://api.verify.25alpha.ai/v1/verify/veteran with your X-Verify-API-Key header and a JSON body containing user_id and document_data (base64 encoded DD-214 or equivalent). The response includes a VerificationToken with a verified boolean and confidence score.
What is the VerificationToken schema?
A VerificationToken contains: token_id (UUID v4), verified (boolean), population (string), confidence (0.0-1.0), timestamp (ISO 8601), expires_at (ISO 8601), arceb_trace_id (UUID), hash_present (boolean), behavioral_trust (number or null), and compliance_flags (object with ferpa_compliant, coppa_consent, gdpr_consent, fcra_access_log, glba_mfa, arceb_trace).
What are ComplianceFlags in the VerificationToken?
ComplianceFlags are boolean fields indicating which compliance frameworks were satisfied: ferpa_compliant (FERPA for edu/athlete), coppa_consent (COPPA for minors), gdpr_consent (GDPR for EU users), fcra_access_log (FCRA for veteran/federal), glba_mfa (GLBA for citizen/federal), arceb_trace (always true — every event is ARCEB logged).
Does V.E.R.I.F.Y.™ store identity documents?
No. Documents submitted via the document_data field are analyzed in volatile memory only and never written to any database or storage layer. This is enforced at the code level per PAT-118. Only hashed identifiers and confidence scores are persisted.
What is ARCEB audit logging?
ARCEB (Automated Record Creation and Evidence Binding) is the immutable audit logging framework for V.E.R.I.F.Y.™. Every verification event writes a permanent record containing only hashed identifiers, compliance flags, confidence scores, and timing data. A database trigger prevents UPDATE and DELETE operations — records are immutable for 7 years.
What is the global pipeline credential_hash requirement?
The global pipeline requires a credential_hash field containing the SHA-256 hash of the user's passport or credential number. The raw credential number must NEVER be sent to the API — only the hash. V.E.R.I.F.Y.™ then adds a server-side salt and stores only the double-hashed value for continuity verification (PAT-119).