rt_create_candidate
Create a candidate and assign them to a role with a two-step preview-then-confirm process that checks for duplicates before saving.
Instructions
Create a candidate in Recruitee/Tellent AND place them on a role, in one call. Works entirely from what you are told here — nothing has to exist anywhere else first.
WHAT YOU NEED. Required: the role (its title is enough, e.g. "VP of Customer Success") and the person's full name. Strongly recommended, because a record without them is close to useless to a recruiter: email, and either a LinkedIn URL or a CV file. Optional: phone, tags, a coverLetter block for their background and why they are worth a look, and where they came from. If the user has not given you the recommended fields, ASK for them before creating — the preview call lists exactly what is missing.
TWO-CALL GATE, ALWAYS. The first call (confirm omitted or false) returns what would be created, what is missing, and any existing candidates with the same name — and writes nothing. Show that to the user. Only call again with confirm true once they have approved THIS person for THIS role. One person per confirmation.
THIS CREATES A REAL RECORD FOR A REAL PERSON, visible to the whole hiring team and counted in reporting. The preview always runs a duplicate check; if it finds a match, resolve that with the user rather than creating a second record that splits their history.
DO NOT INVENT DETAILS. An empty field beats a guessed one.
STAGE. Defaults to "Sourced", which is right for anyone we went looking for. Pass stage: "Applied" only for someone who genuinely applied. Recruitee's create endpoint has no stage parameter, so this moves them immediately after creation and tells you if that did not take.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| asCv | No | Treat the attached file as their CV rather than a plain attachment. Default true when attachFile is a CV. | |
| name | Yes | Full name. | |
| tags | No | ||
| No | Strongly recommended — without it nobody can contact them from the ATS. | ||
| links | No | Profile URLs, e.g. their LinkedIn. | |
| offer | Yes | Role title or offer id, e.g. "VP of Customer Success" or 2683651. | |
| phone | No | ||
| stage | No | Stage name. Default "Sourced". | |
| confirm | No | False/absent = preview only. | |
| sources | No | Where they came from, e.g. ["LinkedIn"]. | |
| attachFile | No | Absolute path to a local file to attach — a CV, or a summary document. | |
| coverLetter | No | Free text: their background, and why they are worth looking at. |