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 “consent” property must be used to indicate that a 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
- When not specified the “consent” property defaults to “false”
- 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 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", "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" } |