## Why integrate via API?
When assessments live outside your ATS, recruiters context-switch between tabs. Candidates receive emails from multiple systems. Results get lost in spreadsheets. API integration eliminates all of this—assessments become a native step in your existing workflow.
## Getting started
### 1. Generate your API key
Navigate to your Evalon dashboard → Settings → API Keys. Generate a key and store it securely (never commit it to source control). All API requests require the key in the `Authorization` header:
```
Authorization: Bearer eva_live_xxxxxxxxxxxx
```
### 2. Create an assessment session
Send a POST request to start a new assessment:
```
POST /api/v1/sessions/
{
"assessment_type": "marketing",
"candidate_email": "jane@example.com",
"candidate_name": "Jane Smith",
"project_id": "proj_abc123"
}
```
The response includes a `session_uuid` and a `candidate_url` that you embed in your ATS as a one-click link.
### 3. Configure webhooks
Rather than polling for results, configure a webhook endpoint in your dashboard. Evalon sends a POST request when a session status changes:
```
{
"event": "session.completed",
"session_uuid": "sess_xyz789",
"assessment_type": "marketing",
"score_summary": { "overall": 82, "sections": [...] },
"completed_at": "2026-01-15T14:30:00Z"
}
```
### 4. Retrieve the full scorecard
After completion, fetch the detailed scorecard:
```
GET /api/v1/sessions/{session_uuid}/scorecard/
```
The scorecard includes section-level scores, individual question performance, and a narrative summary you can display directly in your ATS candidate profile.
## Best practices for production
- **Idempotency:** Use the `candidate_email` + `project_id` combination as a natural key. Our API is idempotent—sending the same request twice returns the existing session instead of creating a duplicate.
- **Rate limits:** The API allows 100 requests per minute per key. For bulk operations (e.g., inviting an entire cohort), use the batch endpoint.
- **Error handling:** All errors return standard HTTP status codes with a `detail` field. Handle 429 (rate limit) with exponential backoff.
- **Security:** Rotate API keys quarterly. Use separate keys for staging and production. Never expose keys in client-side code.
## Popular ATS integrations
Evalon customers have built integrations with Greenhouse, Lever, Ashby, Workday, and custom ATS platforms. Our API is ATS-agnostic—if your system can make HTTP requests, it can integrate with Evalon.
Need help? Our platform team offers integration office hours every Thursday. Reach out via the API docs page to book a session.