Procesamiento por Lotes

La arquitectura de procesamiento por lotes le permite enviar los CV de los candidatos como URL firmadas, procesarlos de forma asíncrona en segundo plano mediante AWS SQS y clasificarlos automáticamente frente a una descripción de puesto.

Choose Your Workflow

Path A: Signed Document URLs

Send signed URLs → We download & parse → Score → Rank

POST /v1/create-job

POST /v1/batch/init

POST /v1/batch

Poll status → Get results

Path B: JSON Batch

New

Send pre-parsed JSON resumes → Score → Rank

POST /v1/create-job

POST /v1/batch-json (up to 500)

Poll status → Get results

Documents are submitted as signed URLs only. We do not accept raw multipart file uploads. Each document_url must be a publicly reachable HTTPS link (e.g. an S3 pre-signed URL) to a PDF, DOCX, or TXT resume. Our servers download and parse it for you. URLs that resolve to private or internal addresses are rejected.

The Workflow

1. Create a Job Description

The first step is sending your target job description to POST /v1/create-job. You will receive a unique Job ID.

2a. Upload Candidates (Signed URLs)

Send a JSON array of candidates — each with a signed document_url — to POST /v1/batch/init. We securely download, parse, and store each resume (up to 25 per request). You can attach your own external_candidate_id to each candidate.

2b. Submit JSON Resumes New

Alternatively, send up to 500 pre-parsed resumes as JSON to POST /v1/batch-json. This combines upload, parsing, and batch initialization into a single API call. You can attach your own external_candidate_id to each candidate.

3. Initialize the Batch (Signed-URL path only)

Call POST /v1/batch with your job_id. This reserves PAYG credits, places all uploaded candidates into a background SQS Queue, and starts the AI matching engine. (Skip this step if you used /v1/batch-json — it initializes automatically.)

4. Poll the Status

Use GET /v1/batch/status/{batch_id} to check real-time progress. The response includes completed_count, failed_count, processing_count, and a progress_percent.

5. View Ranked Candidates

Hit GET /v1/batch/{batch_id}/rank to retrieve all candidates sorted automatically by our AI models based on their Match Score.

6. Extract Parsed Dictionary

Alternatively, use GET /v1/batch/{batch_id}/parsed if you only require the raw JSON structure of the resumes without AI intelligence.

7. Webhook Delivery (Optional)

If you configured a Webhook URL in your dashboard, our background workers will automatically send a structured HTTP POST directly to your server containing the completion status and final counts, eliminating the need to poll.

Batch Status Lifecycle

A batch's status is always one of the following lowercase values:

processing — workers still scoringcompleted — all candidates scoredpartial — finished, but some failedfailed — every candidate failed

Candidate-level status values follow the same convention: uploaded → processing → completed | failed.

Response Comparison

Field	`/parsed`	`/rank`
`candidate_id`	✅ Always	✅ Always
`external_candidate_id`	✅ or null	✅ or null
`parsed_resume`	✅	❌
`match_score`	❌	✅
`profile_score`	❌	✅
Sorted by score	❌	✅ Desc

Recommended Integration Workflow

This diagram shows the complete state machine for integrating the Batch Processing system into your application. Follow either Path A (signed document URLs) or Path B (pre-parsed JSON) depending on your data source.

🔗 Path A — Signed URL Flow

Create a job description → receive job_id
Submit signed document URLs via POST /v1/batch/init
Call POST /v1/batch to start AI scoring
Poll GET /batch/status until terminal
Fetch ranked or parsed results

🧩 Path B — JSON Batch Flow

Create a job description → receive job_id
Submit up to 500 pre-parsed resumes in one call
Upload + batch init happens automatically
Poll GET /batch/status until terminal
Fetch ranked or parsed results

🔔 Alternative: Webhook Notification

Instead of polling, configure a Webhook URL in your dashboard. Our background workers will send an HTTP POST to your server when the batch is complete, containing the batch_id, status, and final counts.

Ideal Use Case

This architecture is specifically built for ATS platforms and Job Boards that handle bulk uploads and need to seamlessly process hundreds of candidates simultaneously without hitting standard HTTP timeouts.