--- updatedAt: 2026-02-06T12:14:48.000Z --- Fetch the complete documentation index at: https://docs.recruitee.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # /offers/:offer_slug/candidates Apply for the job offer (create candidate). By default, these fields are required: ```name```, ```phone```, ```email```, ```cv```. However, you can turn off the requirements for all of them (besides ```name``` and ```email```) in the offer's settings for the application form. API also allows answering the job’s questions. You just need to attach a list of answers to the request. **Note:** you need to replace `yourcompany` with the subdomain of your company's careers site. If you want to try out this endpoint, please type the subdomain in the **Base URL** (right sidebar). ## Screening questions You can create screening questions in Web Application and use them in creating candidates via Careers Site API.\ Screening questions, if they're set up for the offer, can be found in **GET /offers** endpoint response: ```json Example JSON "open_questions": [ { "id": 286356, "kind": "string", "required": true, "position": 1, "body": "Desired Salary", "open_question_options": [] }, { "id": 286357, "kind": "string", "required": true, "position": 2, "body": "Native Language", "open_question_options": [] } ] ``` When answering a screening question, provide the ID of the question (in the *open\_question\_id* field) and the answer (in the *content*/*multi\_content*/*file*/*flag* field). Use *content* for questions with *kind*: *string*, *text*, *single\_choice*, *date*, *salary*, and *number*; Use *multi\_content* for questions with *kind*: *multi\_choice*; Use *file* for questions with *kind*: *file*; Use *flag* for questions with *kind*: *boolean* and *legal*: ```Text Singe-line candidate[open_question_answers_attributes][0][open_question_id]=232583 candidate[open_question_answers_attributes][0][content]=I found it on Linkedin ``` ```Text Multi-line candidate[open_question_answers_attributes][0][open_question_id]: 256390 candidate[open_question_answers_attributes][0][content]: Information provided by the candidate ``` ```Text Single choice candidate[open_question_answers_attributes][0][open_question_id]: 256390 candidate[open_question_answers_attributes][0][content]: ``` ```Text Date candidate[open_question_answers_attributes][0][open_question_id]: 256390 candidate[open_question_answers_attributes][0][content]: YYYY-MM-DD ``` ```Text Salary candidate[open_question_answers_attributes][0][open_question_id]: 256390 candidate[open_question_answers_attributes][0][content]: ``` ```Text Number candidate[open_question_answers_attributes][0][open_question_id]: 256390 candidate[open_question_answers_attributes][0][content]: ``` ```Text Multiple choice candidate[open_question_answers_attributes][0][open_question_id]: 256390 candidate[open_question_answers_attributes][0][multi_content][0]: candidate[open_question_answers_attributes][0][multi_content][1]: candidate[open_question_answers_attributes][0][multi_content][2]: ``` ```Text File candidate[open_question_answers_attributes][0][open_question_id]: 256390 candidate[open_question_answers_attributes][0][file]: @/path/to/file.jpg ``` ```Text Yes/no candidate[open_question_answers_attributes][0][open_question_id]: 256390 candidate[open_question_answers_attributes][0][flag]: ``` ```Text Legal candidate[open_question_answers_attributes][0][open_question_id]: 256390 candidate[open_question_answers_attributes][0][flag]: ```
You can find full example requests on the right side. > 📘 No application form > > You can omit the questions by not passing them in payload at all, even if some of them are required.\ > However, if you pass them with empty values (`null` or `""`), you will receive validation errors for required questions in response. ## Other > 📘 Uploading files > > If you use form-data request, do not forget to escape `[` with `%5B` and `]` with `%5D`. > > If you create candidates with heavy media files e.g. PDFs, add `async=true` parameter in the request URL to ensure that file upload finishes before candidate is created. > 🚧 Confirmation email > > Please note, that creating a candidate using this endpoint WILL trigger sending a confirmation email - exactly like when candidate applies for your offer. # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "careers-site-api", "version": "1.0" }, "servers": [ { "url": "https://{yourcompany}.recruitee.com/api", "variables": { "yourcompany": { "default": "yourcompany" } } } ], "security": [ {} ], "paths": { "/offers/{offer_slug}/candidates": { "post": { "summary": "/offers/:offer_slug/candidates", "description": "Apply for the job offer (create candidate). By default, these fields are required: ```name```, ```phone```, ```email```, ```cv```. However, you can turn off the requirements for all of them (besides ```name``` and ```email```) in the offer's settings for the application form.\n\nAPI also allows answering the job’s questions. You just need to attach a list of answers to the request.", "operationId": "offersoffer_idcandidates", "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string", "default": "application/json" } }, { "in": "path", "name": "offer_slug", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "candidate": { "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "remote_cv_url": { "type": "string", "description": "Link to file saved on some external website. You can use candidate[cv] instead if you want to upload a file - see examples." }, "referrer": { "type": "string", "description": "Source of candidate. Shown as candidate's 'source' in the app" } }, "required": [ "name", "email" ], "type": "object" } } } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "examples": { "Created (With CV upload)": { "value": "{\n \"candidate\": {\n \"id\": 7928068,\n \"name\": \"John Smith\",\n \"emails\": [\n \"john@example.com\"\n ],\n \"phones\": [\n \"123123123\"\n ],\n \"created_at\": \"2019-01-08T12:09:08.000000Z\",\n \"updated_at\": \"2019-01-08T12:09:09.000000Z\",\n \"photo_url\": \"https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7928068/normal_photo_1546949348.png\",\n \"photo_thumb_url\": \"https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7928068/thumb_photo_1546949348.png\",\n \"cv_url\": \"https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7928068/cv_1546949348.png\",\n \"cv_pdf_url\": \"https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7928068/pdf_cv_1546949348.pdf\",\n \"open_question_answers\": []\n }\n}" }, "Created (with remote CV)": { "value": "{\n \"candidate\": {\n \"id\": 7929046,\n \"name\": \"John Smith\",\n \"emails\": [\n \"john.smith@example.com\"\n ],\n \"phones\": [\n \"123123123\"\n ],\n \"created_at\": \"2019-01-08T12:36:55.000000Z\",\n \"updated_at\": \"2019-01-08T12:36:56.000000Z\",\n \"photo_url\": \"https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7929046/normal_photo_1546951015.png\",\n \"photo_thumb_url\": \"https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7929046/thumb_photo_1546951015.png\",\n \"cv_url\": \"https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7929046/cv_1546951015.pdf\",\n \"cv_pdf_url\": \"https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7929046/pdf_cv_1546951015.pdf\",\n \"open_question_answers\": []\n }\n}" } }, "schema": { "oneOf": [ { "title": "Created (With CV upload)", "type": "object", "properties": { "candidate": { "type": "object", "properties": { "id": { "type": "integer", "example": 7928068, "default": 0 }, "name": { "type": "string", "example": "John Smith" }, "emails": { "type": "array", "items": { "type": "string", "example": "john@example.com" } }, "phones": { "type": "array", "items": { "type": "string", "example": "123123123" } }, "created_at": { "type": "string", "example": "2019-01-08T12:09:08.000000Z" }, "updated_at": { "type": "string", "example": "2019-01-08T12:09:09.000000Z" }, "photo_url": { "type": "string", "example": "https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7928068/normal_photo_1546949348.png" }, "photo_thumb_url": { "type": "string", "example": "https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7928068/thumb_photo_1546949348.png" }, "cv_url": { "type": "string", "example": "https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7928068/cv_1546949348.png" }, "cv_pdf_url": { "type": "string", "example": "https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7928068/pdf_cv_1546949348.pdf" }, "open_question_answers": { "type": "array" } } } } }, { "title": "Created (with remote CV)", "type": "object", "properties": { "candidate": { "type": "object", "properties": { "id": { "type": "integer", "example": 7929046, "default": 0 }, "name": { "type": "string", "example": "John Smith" }, "emails": { "type": "array", "items": { "type": "string", "example": "john.smith@example.com" } }, "phones": { "type": "array", "items": { "type": "string", "example": "123123123" } }, "created_at": { "type": "string", "example": "2019-01-08T12:36:55.000000Z" }, "updated_at": { "type": "string", "example": "2019-01-08T12:36:56.000000Z" }, "photo_url": { "type": "string", "example": "https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7929046/normal_photo_1546951015.png" }, "photo_thumb_url": { "type": "string", "example": "https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7929046/thumb_photo_1546951015.png" }, "cv_url": { "type": "string", "example": "https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7929046/cv_1546951015.pdf" }, "cv_pdf_url": { "type": "string", "example": "https://recruitee.s3.eu-central-1.amazonaws.com/candidates/7929046/pdf_cv_1546951015.pdf" }, "open_question_answers": { "type": "array" } } } } } ] } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": "" } } } } }, "422": { "description": "422", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"error\": [\n \"Name can't be blank\",\n \"Email can't be blank\",\n \"Email is invalid\",\n \"Cv can't be blank\",\n \"Phone can't be blank\"\n ],\n \"error_fields\": {\n \"name\": [\n \"can't be blank\"\n ],\n \"email\": [\n \"can't be blank\",\n \"is invalid\"\n ],\n \"cv\": [\n \"can't be blank\"\n ],\n \"phone\": [\n \"can't be blank\"\n ]\n }\n}" } }, "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string", "example": "Name can't be blank" } }, "error_fields": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string", "example": "can't be blank" } }, "email": { "type": "array", "items": { "type": "string", "example": "can't be blank" } }, "cv": { "type": "array", "items": { "type": "string", "example": "can't be blank" } }, "phone": { "type": "array", "items": { "type": "string", "example": "can't be blank" } } } } } } } } } }, "deprecated": false, "security": [], "x-readme": { "code-samples": [ { "language": "curl", "code": "curl -X POST 'https://{yourcompany}.recruitee.com/api/offers/{offer_slug}/candidates' \\\n -H 'content-type: multipart/form-data' \\\n -F 'candidate[name]=John Smith' \\\n -F 'candidate[email]=john@example.com' \\\n -F 'candidate[phone]=123123123' \\\n -F 'candidate[photo]=@/path/to/photo.jpg' \\\n -F 'candidate[cover_letter]=Example cover letter' \\\n -F 'candidate[cv]=@/path/to/cv.pdf'", "name": "With CV upload (form-data)" }, { "language": "curl", "code": "curl -X POST 'https://{yourcompany}.recruitee.com/api/offers/{offer_slug}/candidates'\\\n -H 'content-type: application/json' \\\n -d '{\n \"candidate\": {\n \"name\": \"John Smith\",\n \"email\": \"john.smith@example.com\",\n \"phone\": \"123123123\",\n \"cover_letter\": \"Example cover letter\",\n \"remote_photo_url\": \"https://site.example.com/images/myimage.jpeg\",\n \"remote_cv_url\": \"https://example.com/CV.pdf\",\n \"open_question_answers_attributes\": [\n {\n \"open_question_id\": 5,\n \"content\": \"Yes\"\n },\n {\n \"open_question_id\": 8,\n \"content\": \"Responsibility\"\n },\n {\n \"open_question_id\": 9,\n \"content\": \"Blue\"\n },\n {\n \"open_question_id\": 10,\n \"multi_content\": [\"Pizza\", \"Hamburger\"]\n },\n {\n \"open_question_id\": 11,\n \"remote_file_url\": \"https://site.example.com/files/additional_file.jpg\"\n }\n ]\n }\n}'", "name": "With remote CV link" }, { "language": "curl", "code": "curl -X POST 'https://{yourcompany}.recruitee.com/api/offers/{offer_slug}/candidates' \\\n-H 'content-type: multipart/form-data' \\\n-F 'candidate[name]=Jane Doe' \\\n-F 'candidate[email]=jane@example.com' \\\n-F 'candidate[cover_letter]=Example cover letter' \\\n-F 'candidate[cv]=@/path/to/cv.pdf' \\\n-F 'candidate[open_question_answers_attributes][0][open_question_id]=941744' \\\n-F 'candidate[open_question_answers_attributes][0][content]=Example answer - text (single line) type' \\\n-F 'candidate[open_question_answers_attributes][1][open_question_id]=941745' \\\n-F 'candidate[open_question_answers_attributes][1][content]=Example answer - text (multiple lines) type' \\\n-F 'candidate[open_question_answers_attributes][2][open_question_id]=941746' \\\n-F 'candidate[open_question_answers_attributes][2][flag]=true' \\\n-F 'candidate[open_question_answers_attributes][3][open_question_id]=941747' \\\n-F 'candidate[open_question_answers_attributes][3][content]=Example answer - single choice type' \\\n-F 'candidate[open_question_answers_attributes][4][open_question_id]=941751' \\\n-F 'candidate[open_question_answers_attributes][4][multi_content][]=First answer - multiple choice type' \\\n-F 'candidate[open_question_answers_attributes][4][multi_content][]=Second answer - multiple choice type' \\\n-F 'candidate[open_question_answers_attributes][6][open_question_id]=941753' \\\n-F 'candidate[open_question_answers_attributes][6][file]=@/path/to/file.jpg' \\\n-F 'candidate[open_question_answers_attributes][7][open_question_id]=941754' \\\n-F 'candidate[open_question_answers_attributes][7][flag]=true'", "name": "With screening questions" } ], "samples-languages": [ "curl" ] } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ````