Endpoint 2 – Create a New Candidate Application

Use this endpoint to create a new candidate application in SmartRecruiters for a specific job.

One of authorization headers must be present in each request (Authentication).
- If you are using OAuth 2.0 authentication then candidate_applications_manage scope is required
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 and answers (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

In 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

Before 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 and TEXTAREA 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

{
  "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

{
  "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

{
  "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

{
  "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

No 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

{
  "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

{
  "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 to false or not set at all
- The API will reject any answers to questions being displayed under a certain condition
conditionalsIncluded set to true
- 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.

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 the created candidate
applicationId: String	ID of the created application
createdOn: String	Application creation date. ISO8601 format

Endpoint 2 – Create a New Candidate Application

Candidate information

GDPR Compliance

consentDecisions property

Legacy method: consent property

Answering Screening Questions

Limitations:

Glossary of an Answer object properties

Answer object

Record object

FieldContainer object

Examples

CHECKBOX question

RADIO question

SINGLE_SELECT question

MULTI_SELECT question

INFORMATION question

INPUT_TEXT question

TEXTAREA question

Currency question

Repeatable question

Conditional question

Implications

Complete Request payload

Response object

Response object glossary

`consentDecisions` property

Legacy method: `consent` property

`CHECKBOX` question

`RADIO` question

`SINGLE_SELECT` question

`MULTI_SELECT` question

`INFORMATION` question

`INPUT_TEXT` question

`TEXTAREA` question