Skip to content

Quick Start

This guide walks you through integrating your ATS with CarvOS in 10 minutes.

Prerequisites

Before you begin, ensure you have:

  • API credentials (API key and webhook secret)
  • A development environment to test webhooks
  • Access to your ATS's webhook configuration

Info

Need credentials? Contact your Carv account manager to obtain API credentials. Existing customers can use the self-service portal to manage credentials and test webhooks.

Step 1: Authenticate

All API requests require authentication via the X-API-Key header, plus context headers identifying the client and user:

curl -X POST "https://api.carvos.io/v1/candidates" \
  -H "X-API-Key: your-api-key" \
  -H "X-ATS-Client-ID: your-client-id" \
  -H "X-ATS-User-ID: your-user-id" \
  -H "Content-Type: application/json" \
  -d '{"candidate_id": "test-123", "first_name": "Jane", "last_name": "Smith", "email": "jane@example.com"}'

import requests

response = requests.post(
    "https://api.carvos.io/v1/candidates",
    headers={
        "X-API-Key": "your-api-key",
        "X-ATS-Client-ID": "your-client-id",
        "X-ATS-User-ID": "your-user-id",
        "Content-Type": "application/json",
    },
    json={
        "candidate_id": "test-123",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
    },
)

All write operations return 202 Accepted immediately — processing happens asynchronously. The response body carries a reference_id (UUID7) that identifies the business flow end-to-end:

{"reference_id": "019db49a-860b-74cb-8199-635ca3ad7f59"}

The same reference_id appears on the outgoing webhook payload and as the X-Carv-Causation-ID header when we deliver results — save it alongside your local state if you want to join your view of a request to ours. See Outgoing Webhooks: X-Carv-Causation-ID.

Reporting issues

Always include the reference_id when contacting support. It lets us pull the full end-to-end trace of your request — ingress, processing, and any outgoing webhook deliveries — from a single identifier.

Step 2: Set Up Webhook Receiver

CarvOS sends processed data back to your webhook endpoint. Create an endpoint that:

  1. Accepts POST requests
  2. Verifies the HMAC-SHA256 signature
  3. Returns a 2xx status within 5 seconds

Tip

Use the webhook sandbox to test your integration before going live.

from hmac import compare_digest
import hmac
import hashlib

def verify_webhook(payload: bytes, signature_header: str, secret: str) -> bool:
    """Verify the webhook signature (format: t={timestamp},v1={signature})."""
    parts = dict(part.split("=", 1) for part in signature_header.split(","))
    timestamp = parts["t"]
    provided_sig = parts["v1"]

    signed_payload = f"{timestamp}.".encode() + payload
    expected = hmac.new(
        secret.encode(),
        signed_payload,
        hashlib.sha256
    ).hexdigest()
    return compare_digest(expected, provided_sig)

Step 3: Configure Webhooks

Use the self-service portal to configure:

  • Your outgoing webhook URL — where CarvOS sends processed data
  • Webhook secrets — for signing and verifying payloads

Note

Webhook configuration is managed through the self-service portal, not via API endpoints.

Step 4: Send Your First Candidate

Push a candidate to CarvOS via the REST API or incoming webhooks:

curl -X POST "https://api.carvos.io/v1/candidates" \
  -H "X-API-Key: your-api-key" \
  -H "X-ATS-Client-ID: your-client-id" \
  -H "X-ATS-User-ID: your-user-id" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "candidate-123",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com"
  }'

curl -X POST "https://api.carvos.io/v1/webhooks/your-ats-id" \
  -H "X-Webhook-Signature: t=1234567890,v1=abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "candidate.created",
    "event_id": "evt-001",
    "client_id": "your-client-id",
    "user_id": "your-user-id",
    "candidate_id": "candidate-123",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com"
  }'

See the API Reference for the full request and response schemas.

Step 5: Receive Processed Data

CarvOS sends processed data back to your webhook endpoint:

{
  "event": "candidate.created",
  "event_id": "evt_abc123",
  "reference_id": "019db49a-860b-74cb-8199-635ca3ad7f59",
  "client_id": "your-client-id",
  "timestamp": "2026-02-25T10:30:00Z",
  "status": "success",
  "error": null,
  "data": {
    "candidate_id": "candidate-123",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com"
  }
}

Next Steps