API Overview¶

The Circuit KYC Network API is a RESTful API that enables banks and fintechs to share verified identity data securely.

Base URLs¶

Environment	URL
Production	`https://api.circuit-kyc.com`
Sandbox	`https://sandbox.circuit-kyc.com`

Authentication¶

All endpoints (except /health and /billing/pricing) require an API key:

curl -H "X-API-Key: sk_sandbox_your-key" https://sandbox.circuit-kyc.com/api/v1/...

See Authentication for details.

Request Format¶

All requests use JSON bodies
Set Content-Type: application/json
UTF-8 encoding required

curl -X POST https://sandbox.circuit-kyc.com/api/v1/check-eligibility \
  -H "X-API-Key: sk_sandbox_your-key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Response Format¶

All responses return JSON with appropriate HTTP status codes.

Success Response¶

{
  "eligible": true,
  "kyc_level": "standard",
  "confidence_score": 0.87,
  "request_id": "req_abc123"
}

Error Response¶

{
  "detail": "Invalid API key"
}

HTTP Status Codes¶

Code	Meaning
`200`	Success
`201`	Created
`202`	Accepted (async operation)
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`402`	Payment Required - Insufficient credits
`404`	Not Found
`429`	Too Many Requests - Rate limited
`500`	Server Error

Rate Limits¶

Requests are rate-limited per API key:

Tier	Requests/minute
Sandbox	25
Starter	100
Growth	500
Enterprise	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1705329600

When rate limited, you'll receive a 429 response with Retry-After header.

Endpoints¶

Core Operations¶

Endpoint	Method	Credits	Description
`/api/v1/check-eligibility`	POST	1	Check KYC eligibility
`/api/v1/assess-risk`	POST	5	Risk assessment
`/api/v1/claim-identity`	POST	10	Claim identity credential
`/api/v1/ingest`	POST	FREE	Ingest KYC data

Credentials¶

Endpoint	Method	Description
`/api/v1/issue`	POST	Issue credential
`/api/v1/verify`	POST	Verify credential

Billing¶

Endpoint	Method	Auth	Description
`/api/v1/billing/pricing`	GET	No	Get pricing
`/api/v1/billing/credits`	GET	Yes	Get balance
`/api/v1/billing/overview`	GET	Yes	Billing dashboard

Compliance¶

Endpoint	Method	Description
`/api/v1/compliance/gdpr/forget`	POST	Right to be forgotten

Pagination¶

Endpoints that return lists support pagination:

GET /api/v1/billing/usage?page=1&page_size=50

Response includes pagination info:

{
  "records": [...],
  "page": 1,
  "page_size": 50,
  "total_pages": 5
}

Interactive Documentation¶

Swagger UI: /docs
ReDoc: /redoc
OpenAPI Spec: /api/v1/openapi.json

SDKs¶

Official SDKs handle authentication, retries, and error handling: