Endpoint 1 – Get Application Screening Questions and Privacy Policies

GET /postings/:uuid/configuration

Use this endpoint to fetch a list of screening and diversity questions and privacy policies for a job. You must integrate these questions into your application experience and include the answers when creating a new candidate application. You must also present the privacy policy links to the user.

X-SmartToken HTTP header must be present in each request (Authentication).
The endpoint requires the Posting UUID as a path parameter. It is obtained from the Posting API.
The endpoint accepts a conditionalsIncluded query parameter, which determines whether conditional screening questions should be enabled. More information on Conditional Screening Question Section.
Accept-Language HTTP header controls the language of screening questions. By default, it’s English: en.

{
  "questions": [
    {
      "id": "string",
      "label": "string",
      "repeatable": boolean,
      "fields": [
        {
          "id": "string",
          "label": "string",
          "type": "string",
          "required": boolean,
          "complianceType": "string",
          "values": [
            {
              "id": "string",
              "label": "string"
            }
          ]
        }
      ]
    }
  ],
  "settings": {
    "avatarUploadAvailable": boolean,
    "conditionals": [
      {
        "parentQuestionId": "string",
        "fieldId": "string",
        "valueIds": ["string"],
        "conditionalQuestions": ["string"]
      }
    ]
  },
  "privacyPolicies": [
    {
      "url": "string",
      "orgName": "string"
    }
  ]
}

Glossary of properties

Property	Description
questions: Question[]	List of application questions to be presented to a candidate.
settings: ApplySettings	The object containing details of the application creation settings
privacyPolicies: PrivacyPolicy[]	The array of objects containing information about privacy policies

Question object

Property	Description
id: String	Unique identifier of a question
label: String	General label of the question block label
repeatable: Boolean	Indicates if a question has multiple answers (blocks), e.g. The language question is repeatable because a candidate can enter multiple languages
fields: Field[]	For simple questions `fields` property contains exactly one element, for complex questions two or more elements are expected

Field object

Property	Description
id: String	Identifier of a field within a question. It is unique within a question scope
label: String	Label displayed next to input field
type: String	Type of the input field. One of: `INPUT_TEXT`, `SINGLE_SELECT`, `MULTI_SELECT`, `RADIO`, `CHECKBOX`, `TEXTAREA`, `INFORMATION`
required: Boolean	Specifies if an answer is mandatory for a given field
complianceType: String	If present, then available values: `DIVERSITY`. Otherwise, the property is not present in the object
values: Value[]	List of possible answers. It’s used for the following question types: `SINGLE_SELECT`, `MULTI_SELECT`, `RADIO`, `CHECKBOX`

Value object

Property	Description
id: String	Option identifier (unique within the question field)
label: String	Option label to be displayed

ApplySettings object

Property	Description
avatarUploadAvailable: Boolean	Informs about access to the avatar upload feature. If set to `false` do not send the avatar when creating the application.
conditionals: ConditionalScreeningQuestion[]	Conditional screening question settings

PrivacyPolicy object

Property	Description
url: String	Url to the privacy policy
orgName: String	Name of the privacy policy's owner

ConditionalScreeningQuestion object

Property	Description
parentQuestionId: String	Identifier of a question that has a branching capability
fieldId: String	Identifier of a question's field that branching refers to
valueIds: String[]	Identifiers of a field's values that trigger branching. Currently, only one value is expected to be there.
conditionalQuestions: String[]	Identifiers of questions which should be presented to the candidate if branching has been triggered

Example response

{
  "questions": [
    {
      "id": "03bf8a6a-ba81-479f-8048-05ce9ef083c0",
      "label": "What's your favourite book?",
      "repeatable": false,
      "fields": [
        {
          "id": "value",
          "label": "Value",
          "type": "INPUT_TEXT",
          "required": false,
          "values": []
        }
      ]
    },
    {
      "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": []
        }
      ]
    },
    {
      "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"
            }
          ]
        }
      ]
    },
    {
      "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"
            }
          ]
        }
      ]
    },
    {
      "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"
            }
          ]
        }
      ]
    },
    {
      "id": "3253b8f13-42e0-410e-9ff8-3e915634df12",
      "label": "Which shade of green do you prefer?",
      "repeatable": false,
      "fields": [
        {
          "id": "value",
          "label": "Value",
          "type": "SINGLE_SELECT",
          "required": false,
          "values": [
            {
              "id": "485b4be3-5ca7-4310-9d21-7e94eb76f5ea",
              "label": "Bottle green"
            },
            {
              "id": "c98a4607-e559-42de-8b21-00b6971ce18a",
              "label": "Emerald green"
            },
            {
              "id": "619f6439-c2ca-4197-a4cf-66bed72fe120",
              "label": "Forest green"
            }
          ]
        }
      ]
    },
    {
      "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": "03b569ca-5601-442d-a679-cb2edc9fcf81",
              "label": "Nepal"
            },
            {
              "id": "6b1f17cb-6533-4bf1-af79-d2600049297d",
              "label": "Italy"
            },
            {
              "id": "f4eb09eb-148b-4a21-b8fa-a32d60dffb94",
              "label": "Portugal"
            },
            {
              "id": "0d421fb9-f664-486d-81f3-d932db9cb88b",
              "label": "Austria"
            },
            {
              "id": "3b5eaf6f-3967-4d82-93b9-e5e2d6bd08b4",
              "label": "Canada"
            },
            {
              "id": "2209bd17-2a7a-4309-bce2-b82d19c1f92f",
              "label": "Peru"
            }
          ]
        }
      ]
    },
    {
      "id": "eb12b8d8-4292-447a-b737-5f78af4faff4",
      "label": "Thank you for applying to us.",
      "repeatable": false,
      "fields": [
        {
          "id": "eb12b8d8-4292-447a-b737-5f78af4faff4",
          "type": "INFORMATION",
          "required": false,
          "values": []
        }
      ]
    },
    {
      "id": "b7f7039c-a4cb-43fa-9251-25c03ab48974",
      "label": "Languages",
      "repeatable": true,
      "fields": [
        {
          "id": "lang",
          "label": "Please type in a language that you speak",
          "type": "INPUT_TEXT",
          "required": false,
          "values": []
        },
        {
          "id": "level",
          "label": "Select your level",
          "type": "SINGLE_SELECT",
          "required": false,
          "values": [
            {
              "id": "0",
              "label": "Beginner"
            },
            {
              "id": "1",
              "label": "Intermediate"
            },
            {
              "id": "2",
              "label": "Advanced"
            },
            {
              "id": "3",
              "label": "Fluent"
            },
            {
              "id": "4",
              "label": "Native"
            }
          ]
        }
      ]
    }
  ],
  "settings": {
    "avatarUploadAvailable": false,
    "conditionals": [
      {
        "parentQuestionId": "492a8f13-e420-410e-9ff8-3e915558b7fe",
        "fieldId": "value",
        "valueIds": ["0e73a753-c59f-4ab3-b990-e1f53dffaf9d"],
        "conditionalQuestions": ["3253b8f13-42e0-410e-9ff8-3e915634df12"]
      }
    ]
  },
  "privacyPolicies": [
    {
      "url": "https://www.smartrecruiters.com/privacy-policy/?",
      "orgName": "SmartRecruiters"
    },
    {
      "url": "https://www.smartrecruiters.com/legal/privacy-policy/chocolate-factory-inc/",
      "orgName": "Chocolate Factory Inc."
    }
  ]
}

Conditional Screening Questions

A conditional screening question is a question that is displayed only when particular questions are answered in a certain way.

How to enable?

The Conditional Screening Questions is an opt-in feature. To use it, the API clients need to send conditionalsIncludedrequest parameter set to true.

API impact

When the value of the request parameterconditionalsIncluded is set to true, the response payload will have the following changes:

questions array will be enhanced with conditional screening questions
settings.conditionalswill be present and contain all the rules on how conditional question hierarchy can be built

🚧
It's up to the API client to built the model how to show the conditionals questions based on the given rules.

Limitations

There's only one level of conditional screening questions
Only the SINGLE_SELECT type of question can be a parent of conditional screening questions
Diversity questions can not be displayed conditionally

Example

Given the following scenario, the company wants to build conditional screening questions based on the following ones:

Q1: Do you have a driving license? (SINGLE_SELECT)
- A1: I do have one
- A2: I do not possess one
Q2: When is the driving license issued? (TEXT)
Q3: When is the driving license expiring? (TEXT)

The company wants to display Q2 and Q3 only when a candidate has answered A1 as an answer for Q1.

If a candidate answers A2 for Q1 no follow-up questions should be displayed!

Having that in mind, the API response would look as follows:

{
  "questions": [
    {
      "id": "bde691db-cd72-4902-9312-e10f2dd99730",
      "label": "Do you have a driving licence?",
      "repeatable": false,
      "fields": [
        {
          "id": "value",
          "label": "Value",
          "type": "SINGLE_SELECT",
          "required": true,
          "values": [
            {
              "id": "a80eb4ea-ac95-4c85-bed8-474d251f77ac",
              "label": "Yes, I do have one"
            },
            {
              "id": "517b009d-4a8c-4ee5-bf9e-2c77847e4ea9",
              "label": "No I don't have"
            }
          ]
        }
      ]
    },
    {
      "id": "373cde47-28d3-49d9-9a8e-34e19de8fd82",
      "label": "When is the licence issued?",
      "repeatable": false,
      "fields": [
        {
          "id": "value",
          "label": "Value",
          "type": "TEXT",
          "required": true,
          "values": []
        }
      ]
    },
   {
      "id": "2b117cc2-ab33-44e4-8b1a-20171e67ee86",
      "label": "When is the licence expiring?",
      "repeatable": false,
      "fields": [
        {
          "id": "value",
          "label": "Value",
          "type": "TEXT",
          "required": true,
          "values": []
        }
      ]
    }
  ],
  "settings": {
    "avatarUploadAvailable": false,
    "conditionals": [
      {
        "parentQuestionId": "bde691db-cd72-4902-9312-e10f2dd99730",
        "fieldId": "value",
        "valueIds": ["a80eb4ea-ac95-4c85-bed8-474d251f77ac],
        "conditionalQuestions": ["373cde47-28d3-49d9-9a8e-34e19de8fd82",
                     "2b117cc2-ab33-44e4-8b1a-20171e67ee86"
         ]
      }
    ]
  },
  "privacyPolicies": [
    {
      "url": "https://www.smartrecruiters.com/privacy-policy/?",
      "orgName": "SmartRecruiters"
    },
    {
      "url": "https://www.smartrecruiters.com/legal/privacy-policy/chocolate-factory-inc/",
      "orgName": "Chocolate Factory Inc."
    }
  ]
}

Having that in mind, the API response would look as follows:

{
  "questions": [
    {
      "id": "bde691db-cd72-4902-9312-e10f2dd99730",
      "label": "Do you have a driving licence?",
      "repeatable": false,
      "fields": [
        {
          "id": "value",
          "label": "Value",
          "type": "SINGLE_SELECT",
          "required": true,
          "values": [
            {
              "id": "a80eb4ea-ac95-4c85-bed8-474d251f77ac",
              "label": "Yes, I do have one"
            },
            {
              "id": "517b009d-4a8c-4ee5-bf9e-2c77847e4ea9",
              "label": "No I don't have"
            }
          ]
        }
      ]
    },
    {
      "id": "373cde47-28d3-49d9-9a8e-34e19de8fd82",
      "label": "When is the licence issued?",
      "repeatable": false,
      "fields": [
        {
          "id": "value",
          "label": "Value",
          "type": "TEXT",
          "required": true,
          "values": []
        }
      ]
    },
   {
      "id": "2b117cc2-ab33-44e4-8b1a-20171e67ee86",
      "label": "When is the licence expiring?",
      "repeatable": false,
      "fields": [
        {
          "id": "value",
          "label": "Value",
          "type": "TEXT",
          "required": true,
          "values": []
        }
      ]
    }
  ],
  "settings": {
    "avatarUploadAvailable": false,
    "conditionals": [
      {
        "parentQuestionId": "bde691db-cd72-4902-9312-e10f2dd99730",
        "fieldId": "value",
        "valueIds": ["a80eb4ea-ac95-4c85-bed8-474d251f77ac],
        "conditionalQuestions": ["373cde47-28d3-49d9-9a8e-34e19de8fd82",
                     "2b117cc2-ab33-44e4-8b1a-20171e67ee86"
         ]
      }
    ]
  },
  "privacyPolicies": [
    {
      "url": "https://www.smartrecruiters.com/privacy-policy/?",
      "orgName": "SmartRecruiters"
    },
    {
      "url": "https://www.smartrecruiters.com/legal/privacy-policy/chocolate-factory-inc/",
      "orgName": "Chocolate Factory Inc."
    }
  ]
}

Endpoint 1 – Get Application Screening Questions and Privacy Policies

Glossary of properties

Question object

Field object

Value object

ApplySettings object

PrivacyPolicy object

ConditionalScreeningQuestion object

Example response

Conditional Screening Questions

How to enable?

API impact

🚧It's up to the API client to built the model how to show the conditionals questions based on the given rules.

Limitations

Example

🚧
It's up to the API client to built the model how to show the conditionals questions based on the given rules.