Post an Application
Endpoint 2 – Create a New Candidate Application
POST /postings/:uuid/candidates
Use this endpoint to create a new candidate application in SmartRecruiters for a specific job.
X-SmartToken
HTTP header must be present in each request (Authentication).- The endpoint requires the Posting UUID as a path parameter. It is obtained from Posting API
- The endpoint only allows adding candidates in the
New
status. - The
consentDecisions
field should be used to declare the candidate's choice regarding processing personal data and acceptance of the company's and SmartRecruiter's privacy policies. See more in GDPR compliance section - The
answers
field can be used to pass answers to screening questions. See more in Screening answer section.
Candidate information
- The only required fields are:
firstName
,lastName
,email
andanswers
(if there are required screening questions) - The
internal
flag should be used to mark internal (employee) applications so they are visible as such for recruiters. - The endpoint accepts an array of candidate attachments that will be added to the candidate's profile. Examples of such attachments include a resume, or cover letter. They must be encoded in Base64 format. The current limit is 2 MB per file. The accepted files are PDF, DOC(X), RTF, JPG, and PNG.
GDPR Compliance
consentDecisions
property
consentDecisions
propertyIn SmartRecruiters, the customers have a choice between two consent models (more info). Depending on which model has been chosen, consentDecisions
can take two forms:
- Single consent: one (and only one) entry:
[
"SINGLE" : true/false
]
- Separated Consent: up to 4 entries. If any key of configured data scopes is missing, then the decision defaults to false:
[
"SMART_RECRUIT" : true/false,
"SMART_CRM" : true/false,
"SMART_MESSAGE_SMS" : true/false,
"SMART_MESSAGE_WHATSAPP" : true/false
]
Legacy method: consent
property
consent
propertyBefore the introduction of the Separate Consent model, our system allowed the inclusion of a single, boolean, consent
property within the request. While this property is still supported, it is now considered a legacy approach. We strongly recommend transitioning to the use of consentDecisions
.
For organizations operating under the Separate Consent model, if you only include the consent
property in your request, the consent decision will only apply to the SmartRecruit data scope, and other consent data scopes will default to false
. If both consent
and consentDecisions
properties are included in the same request body, only the consentDecisions
will be considered.
Answering Screening Questions
Any posting can have screening questions configured or not, each question can be required or not required depending on the configurations done by the company. For each required question, an answer is expected and should follow the structure specific to the question type.
Limitations:
INPUT_TEXT
andTEXTAREA
question types accept answers encoded in UTF-8 with sizes up to 4 kB – that means 1000–4000 characters depending on the characters used.
Glossary of an Answer object properties
Answer object
Property | Description |
---|---|
id | Identifier of a question being answered by that object |
records: Record[] | Each record is a candidate's answer to a question. Repeatable questions accept multiple records. Non-repeatable ones expect a single object in the array. |
Record object
Property | Description |
---|---|
fields: FieldContainer[] | An array containing objects with answers to particular fields of a question. Repeatable questions expect as many objects in the array as sub-questions are configured. Non-repeatable questions expect a single object in the array. |
FieldContainer object
Property | Description |
---|---|
<questions[].fields[].id>: String[] | The property name is the ID of a question's field, to which the provided value is answered. Single-choice questions expect the array to contain a single-string value. Multi-choice questions accept multiple string values in the array. |
Examples
CHECKBOX
question
CHECKBOX
question{
"questions": [
{
"id": "c7896b0d-b8e6-48fb-9d38-3a9c3c2fb920",
"label": "Do you acknowledge you'll be required to participate in newcomers training?",
"repeatable": false,
"fields": [
{
"id": "confirm",
"label": "Do you acknowledge you'll be required to participate in newcomers training?",
"type": "CHECKBOX",
"required": false,
"values": [
{
"id": "1",
"label": "Confirmed"
}
]
}
]
}
]
}
If the candidate leaves the checkbox unchecked, the answer object must not be present in the answers
array. Below is an example of a request that will be interpreted as an unchecked checkbox.
{
"answers": [ ]
}
In case of candidate marking the checkbox answers
array should contain an answer object with property records.fields.confirm
equal ["1"]
.
{
"answers": [
{
"id": "c7896b0d-b8e6-48fb-9d38-3a9c3c2fb920",
"records": [
{
"fields": {
"confirm": ["1"]
}
}
]
}
]
}
RADIO
question
RADIO
question{
"questions": [
{
"id": "8fe4cfaf-7d0b-4224-998b-14a3085537bb",
"label": "Have you ever been terminated from or asked to leave any previous position?",
"repeatable": false,
"fields": [
{
"id": "value",
"label": "Value",
"type": "RADIO",
"required": false,
"values": [
{
"id": "1",
"label": "Yes"
},
{
"id": "0",
"label": "No"
}
]
}
]
}
]
}
Expected answers
object format in the request body.
{
"answers": [
{
"id": "8fe4cfaf-7d0b-4224-998b-14a3085537bb",
"records": [
{
"fields": {
"value": ["0"]
}
}
]
}
]
}
SINGLE_SELECT
question
SINGLE_SELECT
question{
"questions": [
{
"id": "492a8f13-e420-410e-9ff8-3e915558b7fe",
"label": "Which colour do you prefer?",
"repeatable": false,
"fields": [
{
"id": "value",
"label": "Value",
"type": "SINGLE_SELECT",
"required": false,
"values": [
{
"id": "8ae663b0-d5bf-49bf-9389-5ea7a439c2a6",
"label": "Red"
},
{
"id": "0e73a753-c59f-4ab3-b990-e1f53dffaf9d",
"label": "Green"
},
{
"id": "ddeebfa8-068d-44f3-976a-47264bde3d35",
"label": "Blue"
}
]
}
]
}
]
}
Expected answers
object format in the request body:
{
"answers": [
{
"id": "492a8f13-e420-410e-9ff8-3e915558b7fe",
"records": [
{
"fields": {
"value": ["0e73a753-c59f-4ab3-b990-e1f53dffaf9d"]
}
}
]
}
]
}
MULTI_SELECT
question
MULTI_SELECT
question{
"questions": [
{
"id": "721ee956-0669-494e-8a46-756b4c2bd8bd",
"label": "Which countries have you visited last year?",
"repeatable": false,
"fields": [
{
"id": "value",
"label": "Value",
"type": "MULTI_SELECT",
"required": false,
"values": [
{
"id": "f4eb09eb-148b-4a21-b8fa-a32d60dffb94",
"label": "Portugal"
},
{
"id": "0d421fb9-f664-486d-81f3-d932db9cb88b",
"label": "Austria"
},
{
"id": "2209bd17-2a7a-4309-bce2-b82d19c1f92f",
"label": "Peru"
}
]
}
]
}
]
}
Expected answers
object format in the request body:
{
"answers": [
{
"id": "721ee956-0669-494e-8a46-756b4c2bd8bd",
"records": [
{
"fields": {
"value": [
"f4eb09eb-148b-4a21-b8fa-a32d60dffb94",
"2209bd17-2a7a-4309-bce2-b82d19c1f92f"
]
}
}
]
}
]
}
INFORMATION
question
INFORMATION
questionNo answer is expected to the INFORMATION
question type. This is a static text presented to the candidate.
{
"questions": [
{
"id": "03bf8a6a-ba81-479f-8048-05ce9ef083c0",
"label": "Enter the following questions:",
"repeatable": false,
"fields": [
{
"id": "03bf8a6a-ba81-479f-8048-05ce9ef083c0",
"type": "INFORMATION",
"required": false,
"values": []
}
]
}
]
}
INPUT_TEXT
question
INPUT_TEXT
question{
"questions": [
{
"id": "03bf8a6a-ba81-479f-8048-05ce9ef083c0",
"label": "What's your favorite book?",
"repeatable": false,
"fields": [
{
"id": "value",
"type": "INPUT_TEXT",
"required": true,
"values": []
}
]
}
]
}
Expected answers
object format in the request body:
{
"answers": [
{
"id": "03bf8a6a-ba81-479f-8048-05ce9ef083c0",
"records": [
{
"fields": {
"value": ["The Hitchhiker's Guide to the Galaxy"]
}
}
]
}
]
}
TEXTAREA
question
TEXTAREA
question{
"questions": [
{
"id": "03bf8a6a-ba81-479f-8048-05ce9ef083c0",
"label": "Describe your favorite book?",
"repeatable": false,
"fields": [
{
"id": "value",
"type": "TEXTAREA",
"required": true,
"values": []
}
]
}
]
}
Expected answers
object format in the request body:
{
"answers": [
{
"id": "03bf8a6a-ba81-479f-8048-05ce9ef083c0",
"records": [
{
"fields": {
"value": ["The Hitchhiker's Guide to the Galaxy"]
}
}
]
}
]
}
Currency question
It is possible to configure questions intended specifically for asking about currency amounts, e.g. salary expectations (see Customer Documentation). They are of type INPUT_TEXT
.
{
"questions": [
{
"id": "d825ef05-b38b-4e88-8b1d-601292460dd1",
"label": "What is your expected salary? (EUR)",
"repeatable": false,
"fields": [
{
"id": "amount",
"label": "Value",
"type": "INPUT_TEXT",
"required": false,
"values": []
}
]
}
]
}
Expected answers
object format in the request body. Note that the candidate's response is in the fields.amount
property instead of fields.value
.
{
"answers": [
{
"id": "0a33249e-9d23-4958-b78b-3744217c6203",
"records": [
{
"fields": {
"amount": ["10000"]
}
}
]
}
]
}
Repeatable question
Below is an example of a repeatable question – it accepts multiple answers. The language question is an example of that. A candidate is asked what languages they know and their proficiency level. In this example, a candidate responds that they know two languages.
{
"questions" : [
{
"id": "b7f7039c-a4cb-43fa-9251-25c03ab48974",
"label": "What languages do you speak?",
"description": "List the languages that you are at least conversational in ",
"repeatable": true,
"fields": [
{
"id": "lang",
"label": "Language",
"type": "INPUT_TEXT",
"required": false,
"values": []
},
{
"id": "level",
"label": "Level",
"type": "SINGLE_SELECT",
"required": false,
"values": [
{
"id": "1",
"label": "Basic"
},
{
"id": "2",
"label": "Advanced"
},
{
"id": "3",
"label": "Fluent"
}
]
}
]
}
]
}
Expected answers
object format in the request body:
{
"answers": [
{
"id": "b7f7039c-a4cb-43fa-9251-25c03ab48974",
"records": [
{
"fields": {
"lang": ["Polish"],
"level": ["3"]
}
},
{
"fields": {
"lang": ["English"],
"level": ["2"]
}
}
]
}
]
}
Note: since the question is marked repeatable: true
then records
array contains multiple objects.
Conditional question
Conditional question feature is an opt-in feature. If consumers of the API want to support answering conditional questions, they must pass conditionalsIncluded
set to true
.
Implications
conditionalsIncluded
set tofalse
or not set at all- The API will reject any answers to questions being displayed under a certain condition
conditionalsIncluded
set totrue
- Answers to conditional questions must be put in the
answers
array, alongside other answers. - The API will validate the answers for all the questions, including conditional ones.
- Answers to conditional questions must be put in the
For more details on how conditional questions are structured, please refer to Get Application Screening Questions and Privacy Policies
Complete Request payload
{
"firstName": "Joe",
"lastName": "Doe",
"email": "[email protected]",
"consent": true,
"phoneNumber": "+22222222",
"location": {
"country": "string",
"countryCode": "string",
"regionCode": "string",
"region": "string",
"city": "string",
"lat": 0,
"lng": 0
},
"web": {
"skype": "string",
"linkedIn": "string",
"facebook": "string",
"twitter": "string",
"website": "string"
},
"tags": [
"string","string","string"
],
"education": [
{
"institution": "string",
"degree": "string",
"major": "string",
"current": true,
"location": "string",
"startDate": "string",
"endDate": "string",
"description": "string"
}
],
"experience": [
{
"title": "string",
"company": "string",
"current": true,
"startDate": "string",
"endDate": "string",
"location": "string",
"description": "string"
}
],
"sourceDetails": {
"sourceTypeId": "string",
"sourceSubTypeId" : "string",
"sourceId": "string"
},
"avatar": {
"fileName": "jakub_lazinski_photo.jpg",
"mimeType": "image/jpeg",
"fileContent": "{base64 encoded file content}"
},
"resume": {
"fileName": "cv_jakub_lazinski_photo.pdf",
"mimeType": "application/pdf",
"fileContent": "{base64 encoded file content}"
},
"attachments": [
{
"fileName": "cover_letter.pdf", // display name
"mimeType": "application/pdf",
"fileContent": "{base64 encoded file content}"
}
],
"messageToHiringManager": "string",
"answers": [
{
// Simple currency question answer
"id": "currency#8264685",
"records": [
{
"fields": {
"amount": ["100"]
}
}
]
},
{
// Simple yes/no (radio) question answer
"id": "yesNo#68518625",
"records": [
{
"fields": {
"value": ["0"]
}
}
]
},
{
// Simple checkbox question answer
"id": "checkbox#7812565",
"records": [
{
"fields": {
"confirm": ["1"]
}
}
]
},
{
// Simple single select question answer
"id": "custom#51202421",
"records": [
{
"fields": {
"value": ["20194214124"]
}
}
]
},
{
// Simple multi select question answer
"id": "custom#51202421"
"records": [
"fields": {
"value": ["20194214124", "429412049124", "93193012312"]
}
]
},
{
// Complex repeatable question,
"id": "languages#5122449",
"records": [
{
"fields": {
"language": ["Polish"],
"level": ["40291412"] // drop down option identifier
},
},
{
"fields" :{
"language": ["English"],
"level": ["982423423"] // drop down option identifier
}
}
]
}
]
}
Response object
{
"id": "string",
"createdOn": "string"
}
Response object glossary
Property | Description |
---|---|
id: String | ID of created candidate |
createdOn: String | Application creation date. ISO8601 format |
Updated 3 months ago