Curriculo APIs for ATS builders
Build hiring products on Curriculo's AI layer. Your ATS stays the system of record; Curriculo handles prompt workflows, CV parsing, candidate scoring, 200+ language translation, transcription, interview summaries, hosted screening interviews and signed callbacks behind one Developer Console key.
Create an account, generate a key, and run real ATS workflows from the browser before writing code.
Request referenceRequired and optional inputs for each public API capability.
Screening interviewTrigger recorded candidate interviews and receive transcripts, evaluation data and private media links by callback.
Limits & performanceFile sizes, processing time, throughput and rate limits, measured on production.
Curriculo ATS MCP ↗A separate product: run your ATS from Claude, ChatGPT or Cursor over OAuth.
Email Agent ↗Copy a job's apply address, send a test resume, and connect Google Workspace or Microsoft 365.
Overview #
What the API is, and what it is not.
The Curriculo API exposes the same hiring-intelligence engines the Curriculo ATS product already runs. You call them directly with a Bearer key from the Developer Console. There is no ATS login, no session cookie and no organisation header involved.
Use it as the AI and media layer for your own ATS, job board or recruiting workflow. Your product owns candidates, jobs, status and recruiter UI; Curriculo supplies the heavy work behind the scenes.
Every capability can be run from the interactive documentation before you integrate: pick an operation, paste your key, attach a real CV, and read the response. You judge output quality on your own data first, with no integration work.
| Workflow | What Curriculo combines | Customer-facing result |
|---|---|---|
| Prompt / résumé assistant | CV parsing, structured resume context, generation, editing, translation and session history. | Add a resume workspace where users can ask questions, improve sections, create targeted versions and translate the CV. |
| Screening interview | Email delivery, hosted recording, transcription, translation-ready text, evaluation data, private media links and signed callbacks. | Trigger a recorded candidate step from your ATS and receive interview results without building recording infrastructure. |
| Candidate scoring | Job requirement capture, CV parsing and evaluation. | Show suitability score, rationale, matched skills and gaps beside each applicant. |
| Multilingual hiring | Language detection, direct translation, async translation and document translation across 200+ languages. | Route candidates and documents across language pairs without a separate translation vendor. |
Lists by default. Every input that can be a list, is a list. Send one item or a hundred: the response comes back as a list in the order you sent it, one result per item. A single item failing never collapses the rest of the batch.
The API is not a second ATS
POST /jobs/ on this API stores a job only as a string of requirements, so you can evaluate a list of CVs against it. It is not the Curriculo ATS Jobs API: there are no boards, no pagination and no organisation job list. Console ATS APIs keep their own pagination; the public API takes lists in one request instead.
Quickstart #
From sign-up to a working call, without a sales conversation.
Create your account
Sign up at console.curriculo.me. Sign-up is self-serve, so no sales call is needed to begin.
Generate an API key
On the API Keys page. The key is shown once, so store it somewhere safe. If it is ever lost or exposed, revoke it and issue a new one. Existing keys keep working until you revoke them.
Try each capability before writing code
Open the interactive documentation at api.curriculo.me/public/docs, click Authorize, paste your header, and use Try it out on any operation, file upload included. The console also shows a ready-to-copy request for each capability.
Authorization: Bearer key_...Hand the key to your engineering team
They need the key, the console templates they already saw working, and the Postman collection from the console docs page. Each capability is a single request, so integration stays small and self-contained.
Evaluation costs nothing. Sign-up, key creation and your first calls are covered by the $5.00 free credit. No payment method is needed to start, so you can judge output quality on your own CVs before any commercial discussion.
Authentication #
One key, the whole suite.
Every request carries your Developer Console key as a Bearer token. A console key activates the public API suite immediately. There is no onboarding call and no per-capability request. Prompt, parse, evaluate, translate, detect language, transcribe, interview summary and screening interview all sit on the same account and the same balance.
Authorization: Bearer key_...Key hygiene. The key is displayed once at creation. Issue separate keys per environment or team so they stay independently revocable, never commit a key to source control or paste it into an untrusted client, and revoke immediately on exposure. Keys are scoped to your organisation and see nothing else.
Capabilities #
What you send, what Curriculo handles, and what comes back.
Screening interview
AsyncCandidate emails, screening questions, job title, company name and a callback URL from your server.
Curriculo emails candidates, hosts the recorded interview, transcribes answers, prepares the response for evaluation, and POSTs signed results back to your system with transcript and private recording link.
Prompt / résumé assistant
SessionA CV once, then plain-language instructions from your product experience.
A working resume session for questions, edits, targeted rewrites and translated versions without re-uploading the same file.
Parse CV
One-shotOne CV or a list of CVs, PDF or Word, in a single call. One request is one charge, including a list of CVs.
The full résumé as clean, structured data: name, contact details, work history, education, skills. Values stay in the CV's own language and script. Nothing is translated or rewritten.
Evaluate candidate
One-shotRegister the job once as careers-page text, a JSON string, or a job PDF/DOCX. Then send one CV or a list of CV PDFs against that job.
Per CV: suitability score, written reasons, matched skills and gaps. The same evaluation the Curriculo ATS app shows recruiters. One request is one charge, including a list of CVs.
Translate
One-shotA list of texts (up to 200) or a PDF/DOCX upload. Always a list, so one item is a list of one.
All of them translated in one go, in the order you sent them. If one item fails, the rest still come back. The batch never collapses.
Detect language
One-shotOne text, or a list of texts, in a single call.
The language it is written in, which lets you route a CV or a message before you act on it.
Interview summary
One-shotVideo (mp4, mov, mkv) or audio (mp3, m4a, wav), or a transcript you already have. One interview, or a list.
If you sent media: the transcription, then AI analysis covering highlights, red flags, skills and a recommendation. The same interview scorer as the Curriculo ATS frontend. Transcript-only requests skip transcription.
Most calls are one-shot: nothing you send is stored, and no information carries from one request to the next. Prompt sessions keep a working copy for that session. Screening interviews keep candidate responses and private media so your ATS can retrieve completed recordings.
Request reference #
Every capability is one request with a short, fixed set of inputs.
Required inputs are the minimum for a valid request; optional ones only refine the result. For CV work, register the job once with its requirements, language and settings. Then send lists of documents against that job reference instead of repeating the requirements with every CV.
Parse CV
| Input | Required | Notes |
|---|---|---|
files | Required | One or more CVs in PDF or DOCX, up to 10 MB each. Attach a single file or a list; results come back in the same order. |
The synchronous call attaches CVs in the files field (PDF or DOCX, up to 10 MB each). The asynchronous call accepts those same files, HTTPS file_urls (one per line, or a JSON list), or both, up to 25 CVs. Add an optional callback_url and we POST the result when it is ready. If you omit it, poll the task.
Evaluate candidate
| Input | Required | Notes |
|---|---|---|
job_id | One of these | From POST /jobs/, an evaluate helper rather than the Curriculo ATS Jobs API (no boards, pagination or organisation jobs). Register requirements once, then send CV lists against this id. |
resume_pdfresume_pdfs | Required | One CV via resume_pdf, or several via resume_pdfs. PDF, up to 10 MB each. One request is one charge, including a list of CVs. |
job_details | One of these | A string: paste the careers-page prose, or a JSON string if you already hold structured requirements. Not an ATS job object. Use this, or job_id, or a job_file (PDF/DOCX). |
language | Optional | Language for the written analysis. Left out, the analysis comes back in English. |
The synchronous call attaches PDFs in resume_pdf or resume_pdfs. The asynchronous call accepts those same files, HTTPS resume_urls (one per line, or a JSON list), or both, up to 25 CVs. Send job_id from POST /jobs/ or inline job_details. Add an optional callback_url and we POST the result when it is ready. If you omit it, poll the task.
Translate
| Input | Required | Notes |
|---|---|---|
texts | Required | The items to translate, up to 200 items and 50,000 characters per request. Order is preserved. |
target_language | Required | The language to translate into. |
source_language | Optional | The language of the input. Left out, English is assumed. |
Translate uses the best route we have for the requested language pair. If a direct response includes recommended_async: true, use POST /translate/async for production traffic on that pair.
Detect language
| Input | Required | Notes |
|---|---|---|
text | Required | The text to inspect, up to 50,000 characters. |
default_language | Optional | What to return when the text is too short or too mixed to call. Defaults to English. |
Interview summary
| Input | Required | Notes |
|---|---|---|
interview_id | Required | Your own reference for the interview; it is echoed back so you can match the result to your record. |
media | One of these | Video or audio (mp4, mov, mkv, mp3, m4a, wav). We transcribe, then run the same AI analysis. Use this or transcript_text. |
transcript_text | One of these | Use instead of media if you already hold a transcript, up to 200,000 characters. One of the two is required. |
transcript_entries | Optional | The same transcript split into speaker turns. Supply it and you also get speaking-time analytics. |
language | Optional | Language for the summary. Defaults to English. |
Prompt / résumé assistant
| Input | Required | Notes |
|---|---|---|
prompt_text | Required | Your instruction or question in plain language, in any language. |
file | First call only | Attach the CV once to open the session. Later calls need no file. |
language | Optional | Set it to render the résumé in that language. This, rather than asking for a translation in the instruction, is how translation is requested. |
The interactive documentation lists exactly these inputs per capability, so the required set is visible, and testable, before anyone writes code.
Screening interview
Call POST https://api.curriculo.me/public/screening-interview. Send candidate email addresses, questions, job metadata and a callback URL. Curriculo emails each candidate a link to the interview. As each answer comes in, we POST it to your callback_url. A failed address does not cancel the others.
This is a composed hiring workflow, not a thin email wrapper. Curriculo handles invite delivery, browser recording, private media storage, transcription, translation-ready answer text, evaluation metadata and signed callbacks, so your ATS receives candidate evidence it can show directly to recruiters.
| Input | Required | Notes |
|---|---|---|
candidate_emails | Required | 1 to 50 plain email addresses. |
questions | Required | 1 to 10 questions. The candidate answers them in order. |
callback_url | Required | HTTPS URL. We POST each answer here. No user name, password, or hash in the URL. |
job_title | Optional | Shown in the invite. Defaults to Screening. |
company | Optional | Shown in the invite. Defaults to the hiring team. |
The call answers 202 with a screening_id, a callback_secret shown once, sent_count, and an invites list. Each invite is sent or failed. Screening interview is $0.02 per candidate invite sent; failed invites are not charged.
{
"candidate_emails": ["[email protected]"],
"questions": ["Tell us about a system you shipped."],
"callback_url": "https://example.com/screening",
"job_title": "Backend engineer"
}Each answer is one signed POST to your server. X-Curriculo-Signature is sha256= plus the HMAC-SHA256 of the raw body, using the secret from the 202. completed stays false until that candidate has a final answer for every question. question_index starts at 0.
{
"screening_id": "...",
"email": "[email protected]",
"question": "Tell us about a system you shipped.",
"question_index": 0,
"transcript": "I shipped the billing service.",
"recording_url": "https://api.curriculo.me/public/screening-interview/.../recording",
"media_kind": "video",
"duration_seconds": 142,
"completed": false
}The recording_url is a private Curriculo media link, not a raw S3 URL. It is meant for your ATS result page, where recruiters can watch the answer beside the transcript and evaluation context. If an old link expires, request the screening result again to receive a fresh media URL.
Languages #
Hiring is rarely monolingual, so language handling is built into every capability rather than sold as an add-on.
- Send CVs in any language. Parsing and evaluation read the document as written, whether that is Arabic, Korean, Japanese, Hindi, French, Portuguese or Russian, with no pre-processing on your side.
- Nothing is silently rewritten. Parsed values come back in the CV's own language and script, so a name or an employer is never transliterated into something the candidate would not recognise.
- Translation supports 200+ languages across European, Middle Eastern, South Asian, East and Southeast Asian, African and regional languages. The API selects the best available route for the requested source and target language pair.
- You choose the output language. Evaluation, interview summaries and the résumé assistant each accept a language setting, so an Arabic CV can be assessed in English, or an English CV rendered in Korean.
- Language detection lets you branch a workflow before any human reads the document, so you can assign the right recruiter or pick the right template first.
Limits & performance #
Measured on production, not projected. Plan against these and there are no surprises at go-live.
| What | Value | Why it matters |
|---|---|---|
| Document size | Up to 10 MB | Covers essentially every real CV, including scanned and design-heavy ones. |
| CV processing time | 40-90 seconds | Real AI analysis, not keyword matching. Treat it as a background job, not a page load. |
| Sustained throughput | 2-4 CVs / minute | Roughly 150-250 CVs per hour, unattended. This capacity is shared across the service, so plan against it rather than assuming it is reserved for you. |
| Documents in flight | 3 at a time | Send more than three and the extras wait their turn rather than failing, up to the request-rate limit below. Nothing is lost during a normal spike. |
| Request rate per key | 600 / minute | Well above what a document workload needs; exceeding it returns a rate-limit response rather than degrading everyone. |
| Translation in one call | 200 items / 50,000 chars | A full careers page or CV can be translated in a single request. |
| Interview transcript | 200,000 characters | Comfortably fits a long panel interview, verbatim. |
| Interview recording | Video or audio | Transcribed on our side, so no separate transcription vendor sits between the interview and the analysis. |
| Text for language detection | 50,000 characters | Plenty for a CV, a cover letter or an email. |
Large backlogs. Register the job once and submit your documents against it in lists. You collect the results as they complete rather than holding a connection open per CV. If you expect thousands of documents in a batch, tell us the shape of the workload and we will confirm the plan before you build.
Errors & reliability #
What to expect operationally.
- Each request stands alone. One document failing never affects another, and re-sending a single failed document is always safe, because it cannot create duplicates or half-finished records.
- A rejected request tells you why: file too large, wrong format, missing key, or processing took too long. Nothing fails silently.
- Batches degrade gracefully. In any list request, a single item failing returns that item's error while the remaining results come back normally, in the order you sent them.
- Rate limits behave the same way. Exceeding 600 requests per minute on a key returns a rate-limit response rather than degrading service for everyone.
API prices #
Published self-serve prices. No infrastructure formulas, multipliers, or hidden setup fees.
Self-serve: free credit, then pay as you go
| Item | Amount | How it works |
|---|---|---|
| One-time free credit | $5.00 | Granted on sign-up and drawn down before anything is charged. The console shows what is left and what you have used. |
| Detect language | $0.001 | Per call. |
| Parse, prompt, evaluate, translate | $0.01 | Per call, including a list of CVs. A prompt that includes a PDF is still $0.01. |
| Summarize a transcript | $0.01 | Per call, when you already have the transcript. |
| Transcribe | $0.002 | Per minute of audio. |
| Summarize a recording | $0.002 + $0.01 | Per minute of audio, plus $0.01 per call. |
| Screening interview | $0.02 | Per candidate invite sent. Failed invites are not charged. |
| Topping up | Automatic | You hold a credit balance. When it falls below your chosen threshold, your card is charged to top it back up, so calls never stop mid-workload. |
| Payment method | Card, via Stripe | Card details are entered on Stripe's own pages, never on a Curriculo ATS screen. |
| No subscription | Pay as you go | No monthly plan and no billing cycle to commit to. You pay for the calls you make, and nothing when you make none. |
A single key and a single balance cover every call. For parse and evaluate you can attach files, paste HTTPS résumé links, or send both. An async call can include a callback URL; we POST the result when it is ready, and polling still works if you omit the callback.
Usage visibility
The console shows calls, billable usage, errors and the estimated charge for the period, so you can reconcile before anything is charged. Issue separate keys per environment or team to keep usage attributable and keys independently revocable.
Partner and reseller pricing
For resale or committed volume we price per call under contract. Partner rates are contracted rather than self-serve and are confirmed per engagement. Tell us your expected monthly call volume and we will confirm the rate and the terms that go with it.
- The résumé assistant is $0.01 per call, including a call that attaches a PDF.
- All figures are USD and exclude local taxes. Local-currency invoicing is priced per engagement.
Data handling #
What we keep, what we do not, and what your key can reach.
| Capability | Retention | What that means |
|---|---|---|
| Parse CV | One-shot | Nothing you send is stored, and no information carries from one request to the next. |
| Evaluate candidate | One-shot | |
| Translate | One-shot | |
| Detect language | One-shot | |
| Interview summary | One-shot | |
| Prompt / résumé assistant | Session | Keeps a working copy of the CV so it can act on the same document across a session. |
| Screening interview | Async record | Keeps candidate responses and private media so your ATS can retrieve completed recordings and transcripts. |
- Your data stays yours. Outside prompt sessions and screening interview results, one-shot API calls do not retain the documents you send.
- A key is bound to your organisation and sees nothing else.
- Parsed output preserves the CV's own language and script, so no name or employer is transliterated without you asking for it.
- Revocation is immediate and self-serve. Revoke a compromised key in the console and issue a replacement; other keys are unaffected.
You remain the data controller. CVs and interview recordings are personal data. Confirm you have a lawful basis for processing candidate material and for sending it to a processor before you integrate. Local-currency invoicing is handled per engagement. Raise them with us before you build if they apply to you.
Terms of use #
The operating conditions that apply to every API key.
- Access. A Developer Console key activates the public API suite on one account and one balance. Keys are issued self-serve and may be revoked by you at any time.
- Charging. Each call is charged at the published price for that operation. The $5.00 sign-up credit is drawn down first. Beyond it, your stored card is charged to maintain your chosen balance threshold. There is no subscription and no minimum commitment.
- Fair use. Published throughput is shared service capacity, not reserved capacity. The 600-requests-per-minute limit per key is enforced; exceeding it returns a rate-limit response.
- Charging unit. One request is one charge. A list of ten CVs in one call is still $0.01.
- Taxes. All figures are USD and exclude local taxes.
- Partner terms. Resale and committed-volume pricing is contracted per engagement and is not the self-serve rate.
This page documents how the product operates. It is not a substitute for the Curriculo ATS Terms of Service, Privacy Policy or Data Processing Agreement. Request those from [email protected] before signing.
Curriculo ATS in Claude and ChatGPT (MCP) #
A separate product from the public API.
Different product, different authentication. MCP talks to the Curriculo ATS over OAuth, so the user signs in. A public API key_ does not reach these tools, and the public API does not reach your ATS. The two are bought and used separately.
For teams already on Curriculo ATS, the assistant can work the hiring pipeline in plain language. Adding the connector takes about a minute: paste one address, sign in, approve. It uses the Model Context Protocol, the open standard both assistants support, so there is nothing bespoke for your team to maintain.
https://mcp.curriculo.me/mcpYou sign in with your Curriculo ATS account and approve access, and every action stays scoped to your organisation.
| Ask it to… | And it will |
|---|---|
| Review the pipeline | List open jobs, show how many candidates sit at each stage, and report period-over-period movement. |
| Find people | Search your candidate pool in plain language and return ranked matches with the reasoning for each. |
| Advance candidates | Move applicants between stages, add notes and pass/fail decisions, and surface the AI evaluation for anyone. |
| Handle scheduling | Book interviews and, where a calendar is connected, send the invites and video links automatically. |
| Work the inbox | Read candidate email threads and send replies or bulk updates from your connected mailbox. |
Everything the assistant sees is limited to your own organisation, and it can read far more than it can change. No tool deletes your data. Actions with outside effects, such as sending email, booking an interview or closing a job, are confirmed with you before they run.
MCP tool catalogue #
Twenty-five tools. Access type tells you the risk.
READ only looks. WRITE changes ATS data. WRITE+ changes data and reaches outside, so an email leaves, an invite is sent, or an AI job starts. Seventeen of the twenty-five are read-only; the six WRITE+ tools are confirmed with you before use.
| Tool | Access | What it does |
|---|---|---|
| Account | ||
whoami | Read | Confirms which user and organisation the assistant is acting as. Worth running first in any session. |
| Jobs | ||
list_jobs | Read | Lists jobs, filtered by status, most recently updated first. |
get_job | Read | Full detail for one job, including its funnel stages and applicant count. |
create_job | Write | Creates a job with the default stages (New → First Interview → Second Interview → Offer). Only a title is required; it opens immediately. |
update_job_status | Write+ | Changes a job's status. Closing or pausing emails all candidates who have not been offered. |
list_job_automations | Read | Lists the automations configured on a job: email, interview scheduling, tagging and notifications. |
get_automation_executions | Read | Run history for an automation. |
| Overview | ||
get_dashboard | Read | Inbox plus a per-job funnel breakdown of everyone currently active. |
get_analytics | Read | Totals, period-over-period change, stage breakdown, top jobs and source mix. Last 30 days by default. |
| Candidates | ||
list_applicants | Read | Lists applicants, optionally for one job, with starred / rejected / archived filters. |
get_applicant | Read | One applicant in full: current stage, notes, and activity history. |
search_candidates | Read | Plain-language search across the whole candidate pool. Returns ranked matches with the CV passages and reasoning behind each. |
get_applicant_evaluation | Read | The AI assessment: suitability score, tags, summary and gaps. |
get_applicant_resume_text | Read | The parsed CV content as text and fields, with no file attached. |
add_applicant_note | Write | Adds a note, optionally tagged with a PASS or FAIL decision and the round it belongs to. Private by default. |
move_applicant_stage | Write+ | Moves someone to another stage. Triggers that stage's automations; reaching Offer may auto-close the job once headcount is met. |
reprocess_resume | Write+ | Re-runs the full AI pipeline on a CV: parse, evaluate and index. Runs in the background. |
| Interviews | ||
list_interviews | Read | Lists interviews by job, applicant, status, type or date range. |
schedule_interview | Write+ | Books the interview, adds interviewers, and creates feedback links. With a calendar connected it also creates the event, invites the candidate and generates the video link. The interview is saved either way. |
list_inbox_emails | Read | Lists inbound mail, filtered by job, status or text search. |
get_inbox_stats | Read | Unread counts and totals. |
get_applicant_email_thread | Read | The complete conversation with one candidate, both directions. |
reply_to_applicant_email | Write+ | Replies on the existing thread from your organisation's address. Needs a connected mailbox. |
send_bulk_email | Write+ | Sends one message to one or many candidates, for outreach or status updates. Needs a connected mailbox. |
| Imports | ||
get_import_batch | Read | Progress of a candidate import: per-file status and any errors. |
Mail tools require a connected mailbox. Interview scheduling does not. Without a connected calendar it still saves the interview and reports that invites were not sent.
Setup for Claude, ChatGPT and Cursor, authentication and scopes, example prompts and troubleshooting.
What is Curriculo ATS MCP? ↗The product overview: run hiring by typing, in the assistant you already use.
FAQ #
Do I need to talk to sales to get an API key?
No. Sign-up is self-serve at console.curriculo.me. Create an account, generate a key on the API Keys page, and a one-time $5.00 free credit covers your evaluation. No payment method is required to start.
Does one API key cover every capability?
Yes. A console key activates the public API suite immediately, on the same account and the same balance. There is no per-capability request and no onboarding call.
Does Curriculo ATS store the documents I send to the API?
Most capabilities are one-shot: nothing you send is stored, and no information carries from one request to the next. The résumé assistant keeps a working copy during its session. Screening interviews keep candidate responses and private media so your ATS can retrieve completed recordings.
Is the MCP server the same product as the public API?
No. They are separate products. The public API is authenticated with a Bearer key from the Developer Console. The Curriculo ATS MCP server is authenticated with OAuth, requires an existing Curriculo ATS account, and a public API key does not reach its tools. See the full MCP documentation.
Is there a subscription or a monthly minimum?
No. Self-serve billing is pay-as-you-go with no monthly plan and no billing cycle. You pay the published price for each call, and you pay nothing in a period where you make no calls.
How long does a CV take to process?
40-90 seconds. That is real AI analysis rather than keyword matching, so treat it as a background job rather than something that blocks a page load. Sustained throughput is 2-4 CVs per minute, roughly 150-250 per hour unattended.
What happens if one document in a batch fails?
The rest still come back. Each request stands alone, so one document failing never affects another, and re-sending a single failed document is always safe, because it cannot create duplicates or half-finished records.
Can I evaluate output quality before integrating?
Yes, and we recommend it. Open the interactive documentation, click Authorize, paste your key and use "Try it out" on any operation with a real CV. No code required.
Support #
Where to go next.
- The interactive API reference at api.curriculo.me/public/docs lists every operation and lets you test it in the browser. A Postman collection sits on the console docs page.
- The Developer Console at console.curriculo.me holds your keys, usage, balance and request templates.
- MCP setup, authentication and the full tool reference live at curriculo.me/docs/mcp/.
- For high-volume workloads, partner terms or legal documents, write to [email protected]. Tell us the shape of the workload and we will confirm the plan before you build.