Skip to content

Data Ingestion API

Push KYC verification data into the Circuit network. This endpoint is used by banks and financial institutions to share verified identity data.

Endpoint

POST /api/v1/ingest

Authentication

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

Request Body

{
  "email": "user@example.com",
  "phone_number": "+15551234567",
  "full_name": "John Doe",
  "date_of_birth": "1990-01-15",
  "kyc_status": "APPROVED",
  "tier": "Tier1",
  "document_reference": "doc_abc123",
  "kyc_expires_at": "2025-01-15T00:00:00Z",
  "extra_data": {
    "verification_method": "document_scan",
    "document_type": "passport"
  }
}

Request Fields

Field Type Required Description
email string Yes User's email address
phone_number string Yes Phone number in E.164 format
full_name string Yes User's full legal name
date_of_birth string No Date of birth (YYYY-MM-DD)
kyc_status string Yes Status: APPROVED, REJECTED, PENDING_REVIEW, EXPIRED
tier string No KYC tier level (default: Tier1)
document_reference string No Reference to evidence document
data_source_id string No Identifier for your data source
kyc_expires_at string No KYC expiration date (ISO 8601)
extra_data object No Additional bank-specific data

Response

{
  "status": "received",
  "ingestion_id": "b4322eab-0ff6-4b53-af8d-26fc5c1eedc2",
  "timestamp": "2024-01-15T10:30:00.282712+00:00",
  "message": "Payload queued for processing"
}
Field Type Description
status string Always received on success
ingestion_id string Unique ID for tracking this ingestion
timestamp string When the data was received
message string Status message

KYC Status Values

Status Description
APPROVED Identity verified and approved
REJECTED Identity verification failed
PENDING_REVIEW Manual review required
EXPIRED Previous verification has expired

Example

curl -X POST https://api.circuitkyc.com/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_api_key" \
  -d '{
    "email": "john.doe@example.com",
    "phone_number": "+15551234567",
    "full_name": "John Doe",
    "date_of_birth": "1990-01-15",
    "kyc_status": "APPROVED",
    "tier": "Tier1"
  }'

from circuit_kyc import CircuitKYC

client = CircuitKYC(api_key="sk_live_your_api_key")

result = client.ingest(
    email="john.doe@example.com",
    phone_number="+15551234567",
    full_name="John Doe",
    date_of_birth="1990-01-15",
    kyc_status="APPROVED",
    tier="Tier1"
)

print(f"Ingestion ID: {result.ingestion_id}")

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

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

const result = await client.ingest({
  email: 'john.doe@example.com',
  phoneNumber: '+15551234567',
  fullName: 'John Doe',
  dateOfBirth: '1990-01-15',
  kycStatus: 'APPROVED',
  tier: 'Tier1'
});

console.log(`Ingestion ID: ${result.ingestionId}`);

Credit Cost

FREE - Data ingestion is free to encourage data sharing.

Processing

Ingested data is:

  1. Validated for format and completeness
  2. Queued to Kafka for async processing
  3. Encrypted and stored in the identity registry
  4. Made available for eligibility checks

Processing typically completes within 1-5 seconds.

Webhooks

You can configure webhooks to receive notifications when:

  • Data processing completes
  • Identity status changes
  • Verification expires

See Webhooks Guide for configuration.

Best Practices

  1. Batch wisely - For bulk uploads, use reasonable batch sizes
  2. Idempotency - Re-ingesting the same identity updates the existing record
  3. Data freshness - Re-ingest when verification is renewed
  4. Phone format - Always use E.164 format (+country code)