--- name: "hiring_record_screening" area: "hiring" title: "Save a screening" price: "$0.01" method: "POST" url: "https://api.conecto.chat/v1/tools/hiring_record_screening" mcp_server: "https://api.conecto.chat/mcp/hiring" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/hiring/hiring_record_screening" --- # Save a screening (`hiring_record_screening`) Saves a review of one application: strong, partial or weak, a summary, and each criterion with its evidence. Save your review of one application: strong, partial or weak match, a short summary, and for each of the job's criteria whether the application shows it, with the words that show it. Its match score is the weighted share of the criteria it shows (unclear counts as not shown). When the job has a filter and the application passes it, the hiring team hears about it once, with your summary: by email and as the event hiring.candidate_passed. It moves nobody: decide with hiring_move_applicant. Price: $0.01 a call. A call that fails costs nothing. ## Use it when After reading an application from hiring_screen_queue. It moves nobody. ## Say this to your agent > Maria is a strong match: six years in bike shops, and she builds wheels for a cyclocross team. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `applicant_id` | integer | yes | At least 1. | | | | `match` | string | yes | | `"strong"`, `"partial"`, `"weak"` | | | `summary` | string | yes | 1 to 2,000 characters. | | | | `criteria` | array of objects | no | [{"id": "c1", "met": true\|false\|null, "evidence": "Led a team of four at ..."}] (up to 10 items) | | | ## Example Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. MCP: call `hiring_record_screening` on the MCP server `https://api.conecto.chat/mcp/hiring` with these arguments: ```json { "applicant_id": 4101, "match": "strong", "summary": "Six years as a shop mechanic, the last two also building wheels for a cyclocross team.", "criteria": [ { "id": "c1", "met": true, "evidence": "Six years at a bike shop in Eugene" }, { "id": "c2", "met": true, "evidence": "Builds the wheels for a cyclocross team" } ] } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/hiring_record_screening \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"applicant_id": 4101, "match": "strong", "summary": "Six years as a shop mechanic, the last two also building wheels for a cyclocross team.", "criteria": [{"id": "c1", "met": true, "evidence": "Six years at a bike shop in Eugene"}, {"id": "c2", "met": true, "evidence": "Builds the wheels for a cyclocross team"}]}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "hiring_record_screening", "status": "succeeded", "replayed": false, "cost_usd": "$0.01", "balance_usd": "$19.75", "result": { "applicant": { "applicant_id": 4101, "job": "bike-mechanic", "name": "Maria Santos", "email": "maria.santos@example.com", "phone": "+1 503 555 0130", "stage": "Applied", "rating": null, "source": "careers", "applied_at": "2026-10-14T08:00:00+00:00", "updated_at": "2026-10-14T08:00:00+00:00", "has_resume": true, "flags": [], "screened": "strong", "stage_since": "2026-10-14T08:00:00+00:00", "stages_reached": [ "Applied" ], "assessments": [], "interview": null, "next_step": { "step": "decide", "label": "Screened, decide", "waiting_on": "you", "at": "2026-10-14T08:00:00+00:00", "overdue": false }, "match_score": 100, "screening_summary": "Six years as a shop mechanic, the last two also building wheels for a cyclocross team.", "passed_filter_at": null, "risk": "high", "signals": { "risk": "high", "high": [ { "code": "shared_phone", "applicant_ids": [ 2 ], "text": "The same phone number is on 1 other application under another email address." } ], "minor": [], "authentic": [ { "code": "name_in_email", "text": "Their name is in their email address." } ], "checked_at": "2026-10-14T08:00:00+00:00" }, "spam": false, "links": [], "cover_letter": "I have worked in bike shops for six years, the last two also building wheels for a cyclocross team.", "answers": [ { "question": "How many years have you worked as a bike mechanic?", "answer": 6 }, { "question": "Can you lift 50 lb?", "answer": true } ], "screening": { "match": "strong", "summary": "Six years as a shop mechanic, the last two also building wheels for a cyclocross team.", "criteria": [ { "id": "c1", "text": "Two years as a mechanic in a bike shop", "met": true, "evidence": "Six years at a bike shop in Eugene" }, { "id": "c2", "text": "Has built wheels", "met": true, "evidence": "Builds the wheels for a cyclocross team" } ], "by": "Pip", "at": "2026-10-14T08:00:00+00:00", "required_not_shown": [] }, "notes": [], "history": [ { "at": "2026-10-14T08:00:00+00:00", "change": "Applied" }, { "at": "2026-10-14T08:00:00+00:00", "change": "Screened: strong match", "by": "Pip" } ], "interview_invite": null, "resume": { "file_id": "e5606982-1055-4e0f-9b9a-4cb87560afe9", "name": "Résumé Maria Santos.pdf", "content_type": "application/pdf", "size": "1.1 KB", "size_bytes": 1153, "sha256": "6b65acac1ceea7ed3492428300b2b14437c63d6d3c622e96f0d76366e03b0fb9", "created_at": "2026-10-14T08:00:00+00:00", "download_url": "https://cncto.co/d/e5606982-1055-4e0f-9b9a-4cb87560afe9?t=eyJmIjoiZTU2MDY5ODItMTA1NS00ZTBmLTliOWEtNGNiODc1NjBhZmU5IiwiZXhwIjoxNzkyNTAyMjA4fQ:1xInEO:xpOvIt4iJCsKvKLKpZciLO9wukZ6PpV7dbAEEGMPh-U", "link_expires_in_hours": 24 } } } } ``` `result`: applicant: the application with the screening saved, its match_score (the weighted share of the job's criteria it shows) and passed_filter_at once it passes the job's filter, when the hiring team is told (email and hiring.candidate_passed). ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | No applicant of the business has that applicant_id. | Find them with hiring_list_applicants. | | `payment_required` | 402 | The application came in while the balance could not pay its fee, so it is held. | Top up; the application opens once its fee is paid. | | `ai_review_off` | 409 | Candidates were not told that AI may help review applications. | Run hiring_setup_careers with ai_review: true first. | | `invalid_input` | 400 | match or a criterion is not in the right shape. | Use the criterion ids from the job, and met as true, false or null. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [hiring_setup_careers](https://conecto.chat/tools/hiring/hiring_setup_careers.md): Sets up the careers page at cncto.co/j/: its name, intro, website, reply-to address and who hears about applications. $0.001 a call. - [hiring_design_careers](https://conecto.chat/tools/hiring/hiring_design_careers.md): Gives the careers and job pages the business's own look: colours, a font, corners, a cover, a headline and its own CSS. $0.001 a call. - [hiring_create_job](https://conecto.chat/tools/hiring/hiring_create_job.md): Posts a job with its own page and application form on the careers page. $0.01 a call. - [hiring_update_job](https://conecto.chat/tools/hiring/hiring_update_job.md): Changes a job's details, its criteria and filter, or opens or closes it. $0.01 a call. - [hiring_list_jobs](https://conecto.chat/tools/hiring/hiring_list_jobs.md): The business's jobs with their status, page and applicants per stage. Free up to 1,000,000 reads a month. - [hiring_list_applicants](https://conecto.chat/tools/hiring/hiring_list_applicants.md): Applicants, newest or best match first: for one job or all, by stage, screening, risk, name or email, or the ones kept as spam. Free up to 1,000,000 reads a month. - [hiring_get_applicant](https://conecto.chat/tools/hiring/hiring_get_applicant.md): One application in full: answers, résumé link, screening and match score, the checks on who sent it, notes and history. Free up to 1,000,000 reads a month. - [hiring_screen_queue](https://conecto.chat/tools/hiring/hiring_screen_queue.md): The next applications nobody has screened, with the job's criteria and the résumé as text, blind by default. Free up to 1,000,000 reads a month. - [hiring_mark_spam](https://conecto.chat/tools/hiring/hiring_mark_spam.md): Moves one application to spam or back, and can block the network and email domain it came from. $0.001 a call. - [hiring_get_blocklist](https://conecto.chat/tools/hiring/hiring_get_blocklist.md): The networks and email domains whose applications are kept as spam. Free up to 1,000,000 reads a month. - [hiring_update_blocklist](https://conecto.chat/tools/hiring/hiring_update_blocklist.md): Blocks or unblocks networks and email domains; what comes from them is kept as spam, with no fee and no emails. $0.001 a call. - [hiring_move_applicant](https://conecto.chat/tools/hiring/hiring_move_applicant.md): Moves an applicant to another stage of their job, with a note; the candidate is not told. $0.01 a call. - [hiring_hire_applicant](https://conecto.chat/tools/hiring/hiring_hire_applicant.md): Hires an applicant in one call: Hired in hiring, a person in HR with their résumé on file, and their onboarding checklist started. $0.25 a call. - [hiring_note](https://conecto.chat/tools/hiring/hiring_note.md): Adds a note to an applicant, rates them 1 to 5, or both. $0.01 a call. - [hiring_email_applicant](https://conecto.chat/tools/hiring/hiring_email_applicant.md): Emails an applicant in the business's name; replies go to the careers page's reply-to address. $0.02 a call. - [hiring_invite_to_interview](https://conecto.chat/tools/hiring/hiring_invite_to_interview.md): Emails an applicant a link to book an interview on one of the calendar's meeting types, and can move them to a stage. $0.05 a call. - [hiring_save_assessment](https://conecto.chat/tools/hiring/hiring_save_assessment.md): Writes a skills test or changes one: questions scored on their own, written answers to mark, a time limit and shuffling. $0.01 a call. - [hiring_list_assessments](https://conecto.chat/tools/hiring/hiring_list_assessments.md): The business's skills tests: title, questions, time limit, and how many were sent and completed. Free up to 1,000,000 reads a month. - [hiring_send_assessment](https://conecto.chat/tools/hiring/hiring_send_assessment.md): Emails an applicant their own link to a skills test. $0.02 a call. - [hiring_assessment_results](https://conecto.chat/tools/hiring/hiring_assessment_results.md): An applicant's tests: status, score, each answer against the expected one, answers to mark, time taken and how often they left the page. Free up to 1,000,000 reads a month. - [hiring_mark_assessment](https://conecto.chat/tools/hiring/hiring_mark_assessment.md): Gives points to the written answers of a completed test. $0.01 a call. - [hiring_delete_assessment](https://conecto.chat/tools/hiring/hiring_delete_assessment.md): Deletes a skills test with every candidate's answers to it. Free. - [hiring_delete_applicant](https://conecto.chat/tools/hiring/hiring_delete_applicant.md): Deletes an applicant and their résumé for good. Free. - [hiring_dashboard_link](https://conecto.chat/tools/hiring/hiring_dashboard_link.md): A one-time link to hiring at a glance: each applicant's stage and next step, the tests and interviews waiting, and the open jobs. Free up to 1,000,000 reads a month.