Skip to content

Eligibility Check API

Check if an identity exists in the Circuit KYC Network before issuing credentials.

Endpoint

POST /api/v1/check-eligibility

Authentication

Requires X-API-Key header with your API key.

Request Body

{
  "email": "user@example.com",
  "phone_number": "+15551234567"
}
Field Type Required Description
email string Yes User's email address
phone_number string Yes Phone number in E.164 format

Response

Success (200 OK)

{
  "found": true,
  "tier": "Tier1",
  "last_verified_at": "2024-01-15T10:30:00Z"
}

Not Found (200 OK)

{
  "found": false
}

Response Fields

Field Type Description
found boolean Whether the identity exists in the network
tier string KYC tier level (Tier1, Tier2, Tier3) - only if found
last_verified_at string ISO 8601 timestamp of last verification - only if found

Example

curl -X POST https://api.circuitkyc.com/api/v1/check-eligibility \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_api_key" \
  -d '{
    "email": "john.doe@example.com",
    "phone_number": "+15551234567"
  }'

from circuit_kyc import CircuitKYC

client = CircuitKYC(api_key="sk_live_your_api_key")

result = client.check_eligibility(
    email="john.doe@example.com",
    phone_number="+15551234567"
)

if result.found:
    print(f"Identity found with tier: {result.tier}")
else:
    print("Identity not found")

import { CircuitKYC } from '@circuit-kyc/sdk';

const client = new CircuitKYC({ apiKey: 'sk_live_your_api_key' });

const result = await client.checkEligibility({
  email: 'john.doe@example.com',
  phoneNumber: '+15551234567'
});

if (result.found) {
  console.log(`Identity found with tier: ${result.tier}`);
}

Credit Cost

1 credit per request.

Rate Limits

  • Sandbox: 75 requests/minute
  • Starter: 300 requests/minute
  • Growth: 1,500 requests/minute
  • Enterprise: 6,000 requests/minute

Error Responses

Status Description
400 Invalid request body
402 Insufficient credits
403 Invalid or missing API key
429 Rate limit exceeded
500 Internal server error