Verify API

Overview#

The /verifyendpoint is the core of AlliedPass. Send it a user's registration or sign-in data and receive a risk score, risk level, and a detailed breakdown of each signal analyzed. You can then use the riskLevel to decide whether to allow, challenge, or block the request.

Authentication#

All requests must include your API key in the Authorization header. API keys are scoped to a project — create and manage them from the API Keys page.

Authorization: Bearer ap_live_<identifier>_<secret>

Rate Limits#

Rate limits are enforced per API key, per minute. When exceeded, the API returns 429 Too Many Requests. Rate limit headers (RateLimit-*) are included in every response.

Endpoint & Request#

Response#

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "riskScore": 82,
  "riskLevel": "low",
  "isVpn": false,
  "isProxy": false,
  "isTor": false,
  "isDisposableEmail": false,
  "secureGateway": false,
  "email": {
    "address": "user@example.com",
    "domain": "example.com",
    "disposable": false,
    "freeProvider": false,
    "roleAddress": false,
    "tagged": false,
    "noReply": false
  },
  "phone": {
    "number": "+2348012345678",
    "valid": true,
    "voip": false,
    "lineType": "mobile",
    "carrier": "MTN Nigeria",
    "countryCode": "NG"
  },
  "flaggedReasons": [],
  "geo": {
    "country": "NG",
    "city": "Lagos",
    "isp": "MTN Nigeria"
  },
  "device": {
    "browser": "Chrome",
    "os": "Windows",
    "fingerprintId": "3f9a1c72b4e8d05a2f6c"
  }
}

Risk Score#

The riskScore is a value from 0 to 100, where higher means safer.

Flagged Reasons#

The flaggedReasons array contains zero or more of the following codes. An empty array means no risk signals were detected.

Errors#

All errors follow a consistent format:

{
  "error": {
    "code": "SNAKE_CASE_CODE",
    "message": "Human-readable description"
  }
}

Whitelisting#

Emails and domains can be whitelisted per-project from the AlliedPass dashboard. Whitelisted entries bypass the disposable email signal — a known internal or partner email will not be flagged even if its domain appears on a disposable list. Manage your whitelist from the Logs page.

Code Examples#

A full end-to-end verification call. Replace ap_live_your_key_here with an API key from the API Keys page.

const response = await fetch("https://api.alliedpass.com/verify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ap_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "user@example.com",
    ip: "203.0.113.42",
    phone: "+2348012345678",
    userAgent: navigator.userAgent,
  }),
});

const result = await response.json();

if (result.riskLevel === "high") {
  // Block or challenge the user
}