Get Application Screening Questions and Privacy Policies
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, privacy policies, company imprint and consent configuration for a job. Questions must be integrated into your application experience and the answers must be included when creating a new candidate application. You must also present the privacy policy links and imprint to the candidate and ask for a consent according to consent configuration.
- One of authorization headers must be present in each request (Authentication).
- If you are using OAuth 2.0 authentication then
candidate_applications_manage
scope is required
- If you are using OAuth 2.0 authentication then
- 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 and consent scope text statements. 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"
}
],
"consentDetails": {
"scopes": [
{
"scope": String,
"required": boolean,
"label": String
}
]
},
"companyImprintUrl": 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 |
consentSettings: ConsentSettings | The object containing details of consent settings |
companyImprintUrl: String | The company imprint url or null if not declared |
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 |
ConsentSettings object
Property | Description |
---|---|
scopes: ConsentScopeDetails[] | List of defined consent scopes. If there is no defined company's privacy policy, the list will be empty |
ConsentScopeDetails object
Property | Description |
---|---|
scope: ConsentScope | Scope of the consent |
required: boolean | If required, the candidate needs to accept this scope to proceed further |
label: String | Consent scope text statement |
Possible consent scope values depends of company configuration (more info)
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."
}
],
"consentDetails": {
"scopes": [
{
"scope": "SINGLE",
"required": true,
"label": "By checking this box, you will declare that you read and understand the privacy policy of Chocolate Factory Inc."
}
]
},
"companyImprintUrl": "https://www./chocolate-factory-inc.com/legal/imprint"
}
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 conditionalsIncluded
request 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 questionssettings.conditionals
will 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-474d251f77a"],
"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."
}
],
"consentDetails": {
"scopes": [
{
"scope": "SINGLE",
"required": true,
"label": "By checking this box, you will declare that you read and understand the privacy policy of Chocolate Factory Inc."
}
]
},
"companyImprintUrl": "https://www./chocolate-factory-inc.com/legal/imprint"
}
Example Response
{
"questions" [
{
// Simple question of input type string with a required value.
// Simple questions contain a single field with a "value" id and no Field label.
"id": "faveritebook#12312312",
"question": "What's your favorite book?",
"description": "used to store candidate's first name information",
"repeatable": false,
"fields": [{
"id": "value",
"type": "INPUT_TEXT",
"required": true,
"values": []
}]
},
{
// Simple question of type single select with a required answer
"id": "tennisrating#531424214"
"question": "How good are you at tennis?"
"description": "custom question"
"repeatable": false
"fields": [
{
"id": "value",
"type": "SINGLE_SELECT",
"required": true,
"values": [
{
"id": "custom521512",
"label": "Pro"
},
{
"id": "custom5121204",
"label": "Amateur"
}
]
}
]
},
{
// Complex question: languages
// "repeatable" means it is possible to provide multiple field-group answers
"id": "lang#12312312",
"label": "What languages do you speak?",
"description": "List the languages that you are at least conversational in ",
"repeatable": true,
"fields": [
{
"id": "lang",
"label": "Language",
"type": "INPUT_TEXT",
"required": false,
"values": []
},
{
"id": "level",
"label": "Level",
"type": "SINGLE_SELECT",
"required": false,
"values": [
{
"id": "294102193",
"label": "Basic"
},
{
"id": "294102193",
"label": "Advanced"
},
{
"id": "294102193",
"label": "Fluent"
}
]
}
]
}
]
"settings": {
"avatarUploadAvailable": true
},
"privacyPolicies": [
{
"url": "https://www.smartrecruiters.com/privacy-policy/?",
"orgName": "SmartRecruiters"
}
{
"url": "https://www.smartrecruiters.com/CustomerPrivacyPolicy/?",
"orgName": "CustomerPrivacyPolicy"
}
],
"consentDetails": {
"scopes": [
{
"scope": "SINGLE",
"required": true,
"label": "By checking this box, you will declare that you read and understand the privacy policy of Chocolate Factory Inc."
}
]
},
"companyImprintUrl": "https://www./chocolate-factory-inc.com/legal/imprint"
}
Updated 22 days ago