Getting Started
The Croupier API lets you integrate AI-powered candidate discovery directly into your existing tools. Every request is authenticated, rate-limited, and returns structured JSON.
To get started, you'll need an API key. API access is a separate offering from our web plans and requires a custom agreement. This protects against abuse and ensures your volume is properly supported. Reach out to our team to request access.
Authentication
All API requests require a Bearer token in the Authorization header. Tokens are scoped to your account and carry the same permissions as your web dashboard.
Authorization: Bearer <YOUR_API_TOKEN>Never expose your API token in client-side code or public repositories. Rotate tokens periodically from your account settings.
Rate Limits
Rate limits are negotiated per account based on your expected volume and use case. We do not offer self-serve API access — every API account is reviewed before credentials are issued. This prevents abuse and protects the platform for all users.
- Standard: 100 requests / minute — suitable for small teams and ATS integrations
- High Volume: 500 requests / minute — suitable for enterprise workflows and bulk operations
- Custom: Tailored limits for large-scale integrations — contact us
Rate limit headers are returned with every response:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1718900000Search Candidates
Search 100,000+ professional profiles by job title, skills, location, and experience. Returns a ranked list of candidates with AI fit scores.
Query Parameters
job_title— required. Target role, e.g. "Software Engineer"skills— comma-separated required skillslocation— city, region, or "Remote"experience— 1-3, 3-5, 5+, or 10+limit— max results, default 20, max 100
Example Request
curl -X GET "https://api.dealerschoice.systems/v1/candidates/search?job_title=Software+Engineer&skills=Python,React&location=San+Francisco&experience=5+&limit=20" \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json"Example Response
{
"candidates": [
{
"id": "cand_7f8a9b2c",
"name": "Sarah Chen",
"title": "Senior Software Engineer",
"company": "Upstart",
"location": "San Francisco Bay Area",
"years_experience": 8,
"skills": ["Python", "React", "AWS", "Kubernetes"],
"ai_score": 96,
"verdict": "Hire",
"reasoning": "Strong technical match with deep cloud infrastructure experience..."
}
],
"total": 1,
"search_id": "srch_3d2e1a4b"
}Rank Profile
Submit a candidate profile and receive an AI-generated fit score with written reasoning. Useful for evaluating applicants from your own pipeline.
Request Body
{
"job_title": "Software Engineer",
"required_skills": ["Python", "React", "AWS"],
"candidate": {
"name": "Alex Rivera",
"title": "Backend Engineer",
"experience_years": 4,
"skills": ["Python", "Django", "PostgreSQL", "AWS"],
"location": "Remote"
}
}Response
{
"ai_score": 84,
"verdict": "Hire",
"reasoning": "Strong Python and AWS experience. Missing React but has solid backend fundamentals...",
"strengths": ["Python", "AWS"],
"concerns": ["Missing React frontend experience"]
}Search History
List all searches performed by your account, with pagination and filtering by date range.
curl -X GET "https://api.dealerschoice.systems/v1/searches?limit=50&from=2026-01-01" \
-H "Authorization: Bearer sk_live_..."Webhooks
Receive real-time events when candidate searches complete or when new high-scoring candidates are discovered. Configure webhook endpoints from your dashboard.
Event Types
search.completed— triggered when a candidate search finishescandidate.ranked— triggered when a candidate scores above your thresholdsubscription.updated— triggered on plan changes
Webhook Payload
{
"event": "search.completed",
"timestamp": "2026-06-25T14:32:00Z",
"data": {
"search_id": "srch_3d2e1a4b",
"candidates_found": 42,
"top_score": 96
}
}Error Codes
All errors follow a consistent JSON structure:
{
"error": {
"code": "rate_limit_exceeded",
"message": "You have exceeded your rate limit. Retry after 60 seconds.",
"status": 429
}
}400— Bad Request — missing or invalid parameters401— Unauthorized — invalid or missing API token403— Forbidden — API access not enabled for this account404— Not Found — candidate or search ID does not exist429— Too Many Requests — rate limit exceeded500— Internal Server Error — contact support
SDKs
Official SDKs are available for popular languages. Community contributions welcome.
- Python:
pip install croupier-api - JavaScript / Node.js:
npm install @dealerschoice/croupier-api - Ruby:
gem install croupier
Ready to integrate?
API access is a separate offering from our web plans. Every API account is reviewed before credentials are issued to prevent abuse and ensure proper support. Our team will set you up with credentials, walk through your use case, and help you go live.
Contact Us →