Skip to content

Application Scoring

This guide walks you through the complete flow to get AI-powered application scores from CarvOS. You'll push a candidate with their CV, a vacancy, create an application linking them, and receive the scored result via webhook.

Prerequisites

Overview

sequenceDiagram
    participant ATS
    participant CarvOS

    ATS->>CarvOS: 1. Upload CV
    CarvOS-->>ATS: 200 OK (carv_file_id)

    ATS->>CarvOS: 2. Push candidate (with CV)
    CarvOS-->>ATS: 202 Accepted
    CarvOS->>ATS: candidate.created

    ATS->>CarvOS: 3. Push vacancy
    CarvOS-->>ATS: 202 Accepted
    CarvOS->>ATS: vacancy.created

    ATS->>CarvOS: 4. Create application (links candidate + vacancy)
    CarvOS-->>ATS: 202 Accepted
    Note over CarvOS: AI scoring
    CarvOS->>ATS: application.created (with score)

Every step after the upload returns 202 Accepted immediately. CarvOS processes asynchronously and delivers results via outgoing webhooks.

Step 1: Upload the CV

Required for accurate scoring

The CV is the primary source of knowledge for application scoring. Without a CV attached to the candidate or application, CarvOS cannot produce an accurate score. Always upload and attach the CV before creating the application.

Upload the candidate's CV before sending the candidate data. You'll reference the returned carv_file_id in the next step.

curl -X POST "https://api.carvos.io/uploads" \
  -H "X-API-Key: your-api-key" \
  -H "X-ATS-Client-ID: acme-corp" \
  -F "file=@resume.pdf"

The response includes the file reference and an expiration deadline:

{
  "carv_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "file_name": "resume.pdf",
  "content_type": "application/pdf",
  "file_size": 245760,
  "uploaded_at": "2026-03-12T10:30:00Z",
  "expires_at": "2026-03-15T10:30:00Z"
}

Warning

Files expire at the expires_at deadline if not referenced in a webhook. Send the candidate or application webhook before then.

One upload per webhook

Each carv_file_id can only be used in one webhook. If you need to attach the same CV to both a candidate and an application, upload the file twice to get two separate carv_file_id values.

See File Uploads for supported file types, size limits, and error handling.

Step 2: Push a Candidate with the CV

Send candidate data with the uploaded CV attached. The files.resume field references the carv_file_id from the previous step.

curl -X POST "https://api.carvos.io/v1/candidates" \
  -H "X-API-Key: your-api-key" \
  -H "X-ATS-Client-ID: acme-corp" \
  -H "X-ATS-User-ID: admin-user" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "candidate-123",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "files": {
      "resume": {
        "carv_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }'

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": "acme-corp",
    "user_id": "admin-user",
    "candidate_id": "candidate-123",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "files": {
      "resume": {
        "carv_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }'

CarvOS confirms with a candidate.created outgoing webhook once the profile is normalized.

See the API Reference for the full candidate schema.

Step 3: Push a Vacancy

Send the vacancy (open position) that the candidate will apply to:

curl -X POST "https://api.carvos.io/v1/vacancies" \
  -H "X-API-Key: your-api-key" \
  -H "X-ATS-Client-ID: acme-corp" \
  -H "X-ATS-User-ID: admin-user" \
  -H "Content-Type: application/json" \
  -d '{
    "vacancy_id": "vacancy-456",
    "title": "Senior Software Engineer",
    "description": "We are looking for..."
  }'

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": "vacancy.created",
    "event_id": "evt-002",
    "client_id": "acme-corp",
    "user_id": "admin-user",
    "vacancy_id": "vacancy-456",
    "title": "Senior Software Engineer",
    "description": "We are looking for..."
  }'

CarvOS confirms with a vacancy.created outgoing webhook.

See the API Reference for the full vacancy schema.

Step 4: Create an Application

Link the candidate to the vacancy by creating an application. This triggers AI scoring.

If you attached the CV to the candidate in Step 2, the application doesn't need a file reference — CarvOS already has the CV. If you prefer to attach the CV to the application instead, upload the file separately (a new carv_file_id) and include it in the files.resume field here.

curl -X POST "https://api.carvos.io/v1/applications" \
  -H "X-API-Key: your-api-key" \
  -H "X-ATS-Client-ID: acme-corp" \
  -H "X-ATS-User-ID: admin-user" \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "app-789",
    "candidate_id": "candidate-123",
    "vacancy_id": "vacancy-456"
  }'

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": "application.created",
    "event_id": "evt-003",
    "client_id": "acme-corp",
    "user_id": "admin-user",
    "application_id": "app-789",
    "candidate_id": "candidate-123",
    "vacancy_id": "vacancy-456"
  }'

CarvOS processes the application, scores the candidate-vacancy match, and delivers the result via an application.created outgoing webhook.

See the API Reference for the full application schema.

Step 5: Receive the Score

CarvOS delivers the scored application to your webhook endpoint. Check your webhook receiver for the application.created event with the scoring data.

Outgoing Events Reference

Event When
candidate.created Candidate profile created and normalized
candidate.updated Candidate data updated after a change
candidate.deleted Candidate removed
vacancy.created Vacancy created and normalized
vacancy.updated Vacancy data updated
vacancy.deleted Vacancy removed
application.created Application created and scored
application.updated Application data updated
application.deleted Application removed

If processing fails permanently, CarvOS sends the same event type with status: "failure", data: null, and an error object. See Failure Events for details.

For full payload schemas, see the API Reference for Candidates, Vacancies, and Applications.

Next Steps