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 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 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.
      • 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 object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
      "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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "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 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:

1
2
3
"id": "string"
"createdOn": "string"
"candidatePortalUrl": "string"