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 should be added to each request.
- This endpoint accepts the Posting UUID as a path parameter.
- The endpoint only allows adding candidates in the “New” status.
- The only required fields are first name, last name, email, and required screening questions.
- The “internal” flag should be used to mark “internal” (employee) applications so they are marked as such for recruiters
- The “createJoinLink” flag should be used for creating of SmartR join link, which will be provided in response as the “smartrJoinUrl” property
- There are two interchangeable properties – “consent” (sunsetting) and “consentDecisions” (preferred) – that maybe used to indicate that consent to process personal data was collected from the candidate and that the candidate has accepted SmartRecruiters and company’s Privacy Policies (available Privacy Policies are exposed via GET /postings/:uuid/configuration).
- The endpoint accepts answers to screening questions.
- The model for Screening Question attempts to cover simple & complex questions.
- The answer for a given screening question is an array which in most cases would be a single element array containing the value as String e.g. Date in ISO format. Drop-down questions would contain a list of options.
- The text, textarea, and currency formats use UTF-8 encoding. These fields accept a maximum of 4000 bytes, which corresponds to 1000 to 4000 characters depending on the characters used. For simplicity, you can limit candidate input to 1000 characters for these questions.
- For complex questions, a single answer object will contain single attribute for every field defined in a complex question. E.g. “Language” and “Level” for “Languages” question. The “answers” is kept as an array to handle “repeatable” question for which more than a single answer is provided.
- The order of an array determines the answer order given by the candidate.
- The endpoint also accepts an array of candidate attachments in base64 format that are added to the candidate profile. Examples of such attachments include a resume, or cover letter. Current limit is 2MB per file. Accepted files are: PDF, DOC(X), RTF, JPG, PNG
- As a response, the endpoint will return a confirmation that has been created.
- Some errors that can be returned:
- Answers to Screening Questions might be required, but answers are not provided in the body. The endpoint will return errors:
- “The following screening questions are required: <sqId1, sqId2, …>.”
- “Values for the following screening questions’ answers are incorrect: <answer1ToSQ1, answer2ToSQ2, …>”
- We will also validate for any required fields and the entered data format.
Glossary of a “consent” and “consentDecision” properties
In SmartRecruiters, the customers have a choice between two consent models (more info: https://help.smartrecruiters.com/Compliance_and_GDPR/Compliance_and_GDPR_Tools_for_Companies).
Depending on the configured consent model, one should send “consentDecisions” map:
a. With one (and only one) entry in case of the Single Consent model:
[ "SINGLE" : true/false ]
b. With up to 4 entries in case of the Separated Consent model:
[ "SMART_RECRUIT" : true/false, "SMART_CRM" : true/false, "SMART_MESSAGE_SMS" : true/false, "SMART_MESSAGE_WHATSAPP" : true/false ]
In payload, if you miss any of the currently configured data scopes for the company, the decisions regarding these data scopes will default to “false”
Before we introduced the Separate Consent model, we allowed to send single “consent” property within the request. The “consent” is still supported but we consider it as a legacy approach and recommend to switch to the usage of “consentDecisions”. For companies operating on the Separated Consent model, if you sent only the “consent” property, the consent decision will be reflected for one (SmartRecruit) data scope, other consent data scopes will default to “false”. In case of sending both “consent” and “consentDecisions” properties within one request body, only “consentDecisions” will be taken into consideration.
Glossary of a single answer object properties
Answer Object
| Property | Description |
|---|---|
| id | Identifier of a question for which this is an answer for |
| records[Record] | Each record is a candidate answer for a repeatable question |
Record Object
| Property | Description |
|---|---|
| fields: FieldContainer | This is a component of a repeatable question: field-answer pairs |
FieldContainer Object
| Property | Description |
|---|---|
| $fieldId[…] | List of text answers for a given question. It may be a text, option, radio or checkbox identifier. Can contain multiple values. |
Example Answer for a Question:
Example Question object returned from the configuration endpoint:
{ "id": "languages#5122449", "label": ..., "repeatable": true, "fields": [ { "id": "language", "label": ..., "type": "SINGLE_SELECT" "required": ..., "complianceType": ..., "values": [ { "id": "Polish", "label": ... }, { "id": "English", "label": ... } ] }, { "id": "level", "label": ..., "type": "SINGLE_SELECT" "required": ..., "complianceType": ..., "values": [ { "id": "40291412", "label": ... }, { "id": "982423423", "label": ... } ] }, { "id": "note", "label": ..., "type": "INPUT_TEXT" "required": ..., "complianceType": ..., "values": [] } ] } |
Example Answer object for the Question:
{ "id": "languages#5122449", "records": [ { "fields": { "language": ["Polish"], "level": ["40291412"], "note": ["4 years in high school"] } }, { "fields": { "language": ["English"], "level": ["982423423"], "note": ["Native"] } } ] } |
The above is an example answer a repeatable question.id = “languages#5122449” for which a candidate gave 2 answers aka records. Each record contains 3 fields: “language”, “label” and “note”. The first two are of type SINGLE_SELECT and the last one is an INPUT_TEXT. In all cases, each field value is an array of strings.
Endpoint accepts the following example body:
{ "firstName": "string", "lastName": "string", "email": "string", "createJoinLink": true, "consent": true, "phoneNumber": "string", "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 question answer "id": "firstName#21124141", "records": [ { "fields": { "value": ["John"] } } ] }, { // 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"] // option identifier } } ] }, { // Simple multi select question answer "id": "custom#51202421" "records": [ "fields": { "value": ["20194214124", "429412049124", "93193012312"] // option identifier } ] }, { // Simple date question answer "id": "dateOfBirth#5122449" "records": [ { "fields": { "value": ["2016-07-27"] } } ] }, { // 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 } } ] } ] } |
Endpoint returns the following:
{ "id": "string", "createdOn": "string", "candidatePortalUrl": "string", "smartrJoinUrl": "string" } |