API Reference

Everything you need to
verify humans.

One endpoint. Behavioral signals. A confidence score. No friction for your users — and no false positives.

API Operationalv1Try live demo →
Base URL
https://humaverify.com
Quickstart
⚡ 2 lines to integrate
Step 1 — Add the snippet to your HTML (enriches behavioral signals)
<script src="https://humaverify.com/huma.js"></script>
Step 2 — Call verify at any critical moment (signup, login, checkout)
const result = await Huma.verify('user_123', 'huma_live_...');
if (result.human && result.confidence > 0.8) { // ✅ allow }

The snippet silently collects behavioral signals (mouse, keyboard, scroll) and sends them with each verify call for a richer score.

Authentication

All requests must include your API key in the Authorization header as a Bearer token.

Authorization: Bearer huma_live_••••••••••••••••

Get your key from your dashboard →

Endpoints
POST/api/v1/verifyVerify a user

Analyzes a user's behavioral signals and returns a human confidence score. Call at critical moments — signups, logins, form submissions, high-value actions.

Request body

ParameterTypeRequiredDescription
userIdstringYesYour internal user identifier. Not stored — used only for behavioral analysis.

Response fields

FieldTypeDescription
humanbooleanTrue if the user is likely human (confidence ≥ 0.5).
confidencenumberScore from 0.0 to 1.0. Higher = more human-like behavior.
tokenstringUnique verification token. Store for audit purposes.
pii_storedbooleanAlways false. HUMA never stores personal information.

Example

REQUEST
curl -X POST https://humaverify.com/api/v1/verify \
  -H "Authorization: Bearer huma_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_abc123"}'
RESPONSE 200 OK
{
  "human": true,
  "confidence": 0.92,
  "token": "h_verified_Kd3mP8luYMC2Mi1x",
  "pii_stored": false
}
Error codes
StatusCodeMeaning
200—Verification successful.
401MISSING_AUTHNo Authorization header provided.
401INVALID_API_KEY_FORMATKey doesn't match format (huma_live_...).
401INVALID_API_KEYKey not found in database. Check your dashboard.
400—Missing or invalid userId in request body.
402TRIAL_EXPIREDFree trial has expired. Upgrade at humaverify.com/#pricing.
429MONTHLY_LIMIT_EXCEEDEDMonthly plan limit reached. Upgrade your plan.
429BURST_LIMIT_EXCEEDEDToo many requests per minute. Check Retry-After header.
429USER_FLOOD_DETECTEDSame userId verified too many times per minute (max 10/min).
503—Service temporarily unavailable. Retry with exponential backoff.
Node.js SDK

Install

npm install @usehuma/node

Usage

import Huma from "@usehuma/node";

const huma = new Huma("huma_live_your_key_here");

const result = await huma.verify("user_123");

if (result.human && result.confidence > 0.7) {
  // ✅ Real human — allow the action
} else {
  // 🚫 Bot — block or challenge
}

Error handling

import Huma, { HumaError } from "@usehuma/node";

try {
  const result = await huma.verify("user_123");
} catch (err) {
  if (err instanceof HumaError) {
    if (err.status === 429) {
      console.log(`Rate limited. Retry in ${err.retryAfter}s`);
    }
    if (err.status === 402) {
      // Trial expired — redirect user to upgrade
    }
  }
}

Ready to integrate?

Get your API key in seconds. 14-day free trial. No credit card required.

GET YOUR API KEY →