Base URL
All API requests should be made to:/v1/persons endpoint, you would make a request to:
Authentication
All API endpoints require authentication using Bearer tokens in the Authorization header. Add your API key as follows:Response Format
All API endpoints follow a consistent response format:Successful Responses
Example Successful Response
Error Responses
Example Error Response
200: Operation completed successfully400: Invalid request or missing fields401: Missing or invalid API key403: Forbidden - insufficient permissions404: Resource not found429: Rate limit exceeded500: Unexpected server error
Rate Limits
API requests are rate-limited using a sliding window of 60 requests per minute per API key. If you exceed the limit, the API will respond with a429 Too Many Requests status code.
Rate limits apply per API key. Each key has its own independent counter.
Rate Limit Headers
Every API response includes headers to help you track your current usage:Rate Limit Exceeded Response
When the rate limit is exceeded, the API returns a429 status code with a Retry-After header:
Best Practices
- Check rate limit headers on every response to monitor your usage.
- Implement exponential backoff when you receive a
429response — wait for theretry_after_secondsvalue before retrying. - Spread requests over time rather than sending them in bursts to avoid hitting the limit.
- Cache responses where possible to reduce the total number of API calls.