Skip to main content

API Architecture

Technical integration guide for BotsKYC API.

Processing Flow​

Average response time: -5 seconds

Authentication​

Include API key in all requests:

curl -X POST https://api.botskyc.com/api/kyc/analyze/identity \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "documents=@id-front.jpg"

Rate Limits​

PlanPer MinutePer Day
Free000
Starter60,000
Pro000,000

Response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 699889400

Error Handling​

Common status codes:

CodeMeaningAction
00SuccessProcess response
400Bad RequestCheck format
40UnauthorizedVerify API key
49Rate LimitedImplement backoff
500Server ErrorRetry

Error response format:

{
  "status": "error",
  "error": {
    "code": "INVALID_DOCUMENT_QUALITY",
    "message": "Image resolution too low"
  }
}

Integration Patterns​

Synchronous​

For real-time verification:

const response = await fetch(API_URL, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  body: formData
});
const data = await response.json();

Asynchronous​

For batch processing with webhooks:

// Submit job
const job = await fetch(`${API_URL}/async/verify`, {
  method: 'POST',
  body: { documents: [...], webhookUrl: 'https://your-app.com/hook' }
});

// Handle webhook
app.post('/hook', (req, res) => {
  const { result } = req.body;
  processResult(result);
  res.sendStatus(00);
});

Best Practices​

Do:

  • Validate inputs before API calls
  • Implement exponential backoff for retries
  • Monitor rate limit headers
  • Use webhooks for async processing
  • Log request IDs for debugging

Don't:

  • Hardcode API keys
  • Upload images over 0MB
  • Retry 4xx errors
  • Ignore rate limits

Next Steps​