Skip to content

The 5-Minute Onboarding Guide

Get from zero to your first successful API call in 5 minutes.

Prerequisites

  • A Circuit KYC account (sign up here)
  • Your sandbox API key (find it in the dashboard)

Step 1: Install the SDK (30 seconds)

pip install circuit-kyc

npm install @circuit-kyc/sdk

No installation needed - use cURL or any HTTP client.

Step 2: Initialize the Client (30 seconds)

from circuit_kyc import CircuitClient

# Use your sandbox key - starts with sk_sandbox_
client = CircuitClient(api_key="sk_sandbox_your-key-here")

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

const client = new CircuitClient({
  apiKey: 'sk_sandbox_your-key-here',
});

# Set your API key as an environment variable
export CIRCUIT_API_KEY="sk_sandbox_your-key-here"

Step 3: Check Eligibility (1 minute)

Your first API call! Check if a test user is eligible for fast-track KYC:

result = client.check_eligibility(
    email="test@example.com",
    phone="+14155551234"
)

print(f"Eligible: {result.eligible}")
print(f"KYC Level: {result.kyc_level}")
print(f"Confidence: {result.confidence_score}")

const result = await client.checkEligibility({
  email: 'test@example.com',
  phone: '+14155551234',
});

console.log('Eligible:', result.eligible);
console.log('KYC Level:', result.kyc_level);
console.log('Confidence:', result.confidence_score);

curl -X POST https://sandbox.circuit-kyc.com/api/v1/check-eligibility \
  -H "X-API-Key: $CIRCUIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "phone": "+14155551234"
  }'

Expected Response:

{
  "eligible": true,
  "kyc_level": "standard",
  "confidence_score": 0.87,
  "contributing_sources": 2,
  "requires_additional_verification": false,
  "matched_fields": ["email", "phone", "name"],
  "request_id": "req_abc123"
}

Step 4: Handle the Response (2 minutes)

Based on the eligibility response, decide your next action:

if result.eligible and result.confidence_score > 0.8:
    # High confidence - fast-track the user
    print("✅ Fast-track approved!")

    # Optionally claim the identity to get a credential
    credential = client.claim_identity(
        subject_id="your-internal-user-id",
        email="test@example.com",
        eligibility_request_id=result.request_id
    )

elif result.eligible:
    # Medium confidence - may need light verification
    print("⚠️ Eligible with conditions")
    print(f"May need to verify: {result.requires_additional_verification}")

else:
    # Not eligible - proceed with full KYC
    print("❌ Full KYC required")
    redirect_to_full_kyc_flow()

if (result.eligible && result.confidence_score > 0.8) {
  // High confidence - fast-track the user
  console.log('✅ Fast-track approved!');

  // Optionally claim the identity
  const credential = await client.claimIdentity({
    subjectId: 'your-internal-user-id',
    email: 'test@example.com',
    eligibilityRequestId: result.request_id,
    consentGiven: true,
  });
} else if (result.eligible) {
  // Medium confidence - may need light verification
  console.log('⚠️ Eligible with conditions');
} else {
  // Not eligible - proceed with full KYC
  console.log('❌ Full KYC required');
  redirectToFullKycFlow();
}

Step 5: Check Your Credits (30 seconds)

Each eligibility check costs 1 credit. Check your balance:

balance = client.get_credit_balance()
print(f"Credits remaining: {balance.available_credits}")

const balance = await client.getCreditBalance();
console.log('Credits remaining:', balance.available_credits);

curl https://sandbox.circuit-kyc.com/api/v1/billing/credits \
  -H "X-API-Key: $CIRCUIT_API_KEY"

What's Next?

Congratulations! You've made your first Circuit API call. Here's what to explore next:

Guide Description
Handling Webhooks Process async data ingestion events
Rate Limits & Quotas Handle 429 and 402 errors gracefully
Error Handling Build robust integrations
API Reference Complete endpoint documentation

Common Issues

"Invalid API key"

Make sure you're using a sandbox key (sk_sandbox_...) with the sandbox URL, or a live key (sk_live_...) with production.

"Rate limit exceeded"

You've hit the rate limit. Check the Retry-After header and wait before retrying.

"Insufficient credits"

Purchase more credits or enable auto-recharge in your dashboard.

Need Help?