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

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