API Overview

The ROUND0 API allows you to integrate candidate screening into your existing workflows and systems.

Prerequisites

To use the ROUND0 API, you need:

1. ROUND0 account with verified email
2. Connectivity Package subscription
3. API key generated from Settings

Base URL

All API endpoints are accessed via:

https://rz-app-omega.vercel.app/api/v1

Authentication

The ROUND0 API uses API keys for authentication.

Creating an API Key

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Enter a name for the key (e.g., "Production ATS Integration")
4. Click Create
5. Copy the API key immediately - it will only be shown once

API keys have the format:

rz_live_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd

Using Your API Key

Include your API key in the Authorization header of every request:

Authorization: Bearer rz_live_1234567890abcdef...

Example request:

curl https://rz-app-omega.vercel.app/api/v1/jobs \
  -H "Authorization: Bearer rz_live_1234567890abcdef..."

API Key Management

View keys:

• Navigate to Settings → API Keys
• See all active keys with their names and creation dates
• Last used timestamp shown for each key

Revoke keys:

• Click Delete next to the key
• Confirm revocation
• Key is immediately invalidated

Rate Limiting

API requests are rate-limited to prevent abuse and ensure system stability.

Default Limits

• 100 requests per minute per API key
• Limits reset every 60 seconds

Rate Limit Headers

Every API response includes rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 75
X-RateLimit-Reset: 1640000000

Headers explained:

• X-RateLimit-Limit: Maximum requests allowed per window
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when the limit resets

Exceeding Rate Limits

If you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 30 seconds."
  }
}

Best practices:

1. Monitor rate limit headers
2. Implement exponential backoff for retries
3. Cache responses when possible
4. Batch requests where supported

Higher Limits

Need higher rate limits? Contact our sales team at info@round0.io to discuss enterprise plans.

Request Format

Content Type

All POST, PATCH, and PUT requests must include:

Content-Type: application/json

Request Body

Request bodies must be valid JSON:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "candidate": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Response Format

Success Responses

Successful requests return appropriate HTTP status codes and JSON responses:

200 OK - Request succeeded:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "invited",
  "interview_url": "https://interview.round0.io/interview/abc123..."
}

201 Created - Resource created successfully:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T10:30:00Z"
}

Error Responses

Errors return appropriate HTTP status codes and error objects:

{
  "error": {
    "type": "validation_error",
    "message": "Invalid job_id provided",
    "details": {
      "field": "job_id",
      "reason": "Job not found"
    }
  }
}

HTTP Status Codes

Error Types

Common error types you may encounter:

authentication_error

• Missing or invalid API key
• Revoked API key

permission_error

• No active Connectivity Package subscription
• Insufficient permissions for resource

validation_error

• Invalid request parameters
• Missing required fields
• Malformed data

resource_not_found

• Requested resource doesn't exist
• Resource belongs to different user

rate_limit_exceeded

• Too many requests
• Retry after cooldown period

insufficient_credits

• Not enough credits to create interview
• Purchase more credits or wait for pending interviews to complete

trial_restriction

• Feature not available during trial
• Purchase credits to unlock feature

Pagination

List endpoints support pagination using cursor-based pagination:

Request Parameters

GET /api/v1/jobs?limit=20&cursor=eyJpZCI6IjEyMyJ9

Parameters:

• limit: Number of results per page (default: 20, max: 100)
• cursor: Cursor token from previous response (for next page)

Response Format

{
  "data": [
    { "id": "1", "title": "Software Engineer" },
    { "id": "2", "title": "Product Manager" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjIifQ==",
    "has_more": true
  }
}

Fields:

• data: Array of results
• pagination.next_cursor: Cursor for next page (null if no more pages)
• pagination.has_more: Boolean indicating if more results exist

Example: Fetching All Results

let allJobs = [];
let cursor = null;

do {
  const url = cursor
    ? `/api/v1/jobs?cursor=${cursor}`
    : '/api/v1/jobs';

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const result = await response.json();
  allJobs = [...allJobs, ...result.data];
  cursor = result.pagination.next_cursor;

} while (cursor !== null);

Idempotency

Some endpoints support idempotency to safely retry requests without duplicating operations.

Idempotency Keys

Include an idempotency key in the header for POST requests:

Idempotency-Key: unique-string-12345

Key requirements:

• Must be a unique string (UUID recommended)
• Maximum 255 characters
• Valid for 24 hours

Example:

curl -X POST https://rz-app-omega.vercel.app/api/v1/invitations \
  -H "Authorization: Bearer rz_live_..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "...", "candidate": {...}}'

Behavior:

• First request: Processes normally
• Duplicate request (same key within 24h): Returns cached response without creating duplicate

Use cases:

• Network retries
• Distributed systems
• Ensuring exactly-once semantics

Webhooks

The API works seamlessly with webhooks to create event-driven workflows.

Integration pattern:

1. Create interview via API
2. Receive interview_started webhook when candidate begins
3. Receive interview_ended webhook when candidate completes
4. Fetch results via API if needed

See Webhooks Guide for setup instructions.

API Endpoints

The ROUND0 API provides these endpoint groups:

Jobs

Create and manage job descriptions:

• POST /api/v1/jobs - Create a job
• GET /api/v1/jobs - List jobs
• GET /api/v1/jobs/:id - Get job details

See Jobs API Reference for details.

Candidates

Create and manage candidates with CV data:

• POST /api/v1/candidates - Create a candidate
• GET /api/v1/candidates - List candidates
• GET /api/v1/candidates/:id - Get candidate details
• PATCH /api/v1/candidates/:id - Update a candidate
• DELETE /api/v1/candidates/:id - Delete a candidate

See Candidates API Reference for details.

Invitations

Create screening interviews:

• POST /api/v1/invitations - Create interview invitation

See Invitations API Reference for details.

Interviews

Retrieve interview results:

• GET /api/v1/interviews/:id - Get interview results
• GET /api/v1/interviews/:id/questions - Get interview questions

See Interviews API Reference for details.

Postman Collection

We provide a Postman collection to help you explore and test the API quickly.

Using the collection:

1. Download the collection file above
2. Open Postman and click Import
3. Select the downloaded JSON file
4. Set the api_key variable to your API key in the collection variables
5. Start making requests

The collection includes all endpoints with example requests and environment variables for easy configuration.

SDK and Libraries

Currently, ROUND0 provides a REST API without official SDKs.

Community libraries:

• We encourage community-contributed libraries
• Share your library by opening a GitHub issue

Building your own:

• Use standard HTTP libraries in your language
• Implement authentication, rate limiting, and error handling
• Consider contributing back to the community

Best Practices

Security

1. Protect API keys: Never commit keys to version control
2. Use environment variables: Store keys securely
3. Rotate keys periodically: Create new keys and revoke old ones
4. Separate keys by environment: Different keys for dev/staging/production

Error Handling

1. Handle all error codes: Don't assume success
2. Implement retry logic: For 429, 500, 503 errors
3. Use exponential backoff: Increasing delays between retries
4. Log errors: For debugging and monitoring

Performance

1. Monitor rate limits: Use headers to track usage
2. Batch when possible: Group operations to reduce requests
3. Cache responses: Cache data that doesn't change frequently
4. Use webhooks: Instead of polling for status updates

Testing

1. Test in development: Use test accounts and test credits
2. Handle edge cases: Test error scenarios
3. Validate responses: Don't assume response format
4. Monitor in production: Track API usage and errors

Support

Documentation

• API Reference - Complete endpoint documentation
• Webhooks Guide - Webhook setup and events

Getting Help

info@round0.io

Next Steps

• Create Jobs via API - Programmatically create job descriptions
• Manage Candidates - Create and manage candidates with CV data
• Create Interview Invitations - Automate interview creation
• Retrieve Results - Fetch interview transcripts
• Set up Webhooks - Real-time notifications