Getting Started with KYC Genie API

Learn how to integrate KYC Genie's API to automate your due diligence workflows. This guide will walk you through authentication, making your first API call, and common patterns.

Before you begin

Make sure you have an active KYC Genie account. If you don't have one, sign up for free to get started.

Prerequisites

Active KYC Genie account
API key
HTTP client (cURL, Postman, or programming language HTTP library)

Authentication

KYC Genie uses API keys to authenticate requests. Your API keys are linked to your tenant and provide access to your organization's data.

Getting Your API Key

Log in to your KYC Genie account
Navigate to Settings → API Keys
Click "Create API Key"
Give your key a descriptive name (e.g., "Production Server")
Select the appropriate type (Test or Live)
Copy and securely store your API key

Keep your API keys secure!

Never share your API keys or commit them to version control. Treat them like passwords. If a key is compromised, revoke it immediately from your account settings.

Using Your API Key

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer sk_test_123

Your First API Request

Let's make a simple request to list your questionnaires. This is a great way to verify your authentication is working correctly.

List Questionnaires

The questionnaires endpoint returns all DDQ templates you've created:

GET /api/v1/questionnaires/

Understanding Responses

All API responses are returned in JSON format. The structure varies depending on the endpoint type:

List Endpoints (Paginated)

List endpoints (e.g., GET /questionnaires/, GET /responses/) return paginated results with the following structure:

Pagination Fields

Field	Type	Description
`count`	integer	Total number of results
`next`	string	URL for the next page of results (null if last page)
`previous`	string	URL for the previous page (null if first page)
`results`	array	Array of result objects

Single Resource Endpoints

Endpoints that return a single resource (e.g., GET /responses/{id}/, POST /responses/) return the object directly without pagination wrapper.

Rate Limits

To ensure fair usage and system stability, the API enforces rate limits based on your subscription plan:

Plan	Hourly Limit	Burst Limit
Free	1,000 requests/hour	20 requests/minute
Basic	1,000 requests/hour	20 requests/minute
Standard	1,000 requests/hour	20 requests/minute
Pro	1,000 requests/hour	20 requests/minute

Rate Limit Headers

Every API response includes headers to help you track your usage:

Hourly Rate Limit

X-RateLimit-Limit - Total requests allowed per hour
X-RateLimit-Remaining - Requests remaining in current hour
X-RateLimit-Reset - Seconds until the hourly limit resets

Burst Rate Limit (Per-Minute)

X-RateLimit-Burst-Limit - Maximum requests per minute
X-RateLimit-Burst-Remaining - Requests remaining this minute
X-RateLimit-Burst-Reset - Seconds until the burst limit resets

Handling Rate Limits

If you exceed your rate limit, you'll receive a 429 Too Many Requests response. Check the X-RateLimit-Reset header to know when you can retry.

We recommend implementing exponential backoff in your integration to gracefully handle rate limiting.

Error Handling

KYC Genie uses standard HTTP status codes to indicate success or failure. Error responses include a JSON body with details:

Common Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource successfully created
`400`	Bad Request	Invalid request parameters or body
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions or credits
`404`	Not Found	Resource doesn't exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Something went wrong on our end

Error Response Format

All error responses follow a consistent, structured format for easy parsing and handling:

{
  "error": true,
  "status_code": 400,
  "message": "Validation failed",
  "errors": {
    "name": ["This field is required."],
    "email": ["Enter a valid email address."]
  }
}

Error Fields

Field	Type	Description
`error`	boolean	Always `true` for error responses
`status_code`	integer	HTTP status code (400, 401, 403, etc.)
`message`	string	Human-readable error summary
`errors`	object	Detailed error information (field-level validation, error details, etc.)

PII Protection

Error messages automatically mask sensitive information (emails, SSNs, card numbers) to prevent accidental exposure in logs and monitoring systems.

Next Steps

Now that you've made your first API request, explore these resources to build powerful integrations:

Core Concepts

Learn about DDQs, responses, entities, and workflows

API Reference

Complete documentation for all endpoints

Need help?

If you get stuck, check out our FAQs or contact support. We're here to help!