# Finding the Questions

Once a job post has been "mined", its questions can be retrieved from the database with the following API call. The jobPostId must be the same value as the jobPostId used when initially mining the job post questions.

The response returned depends upon the status of the mining job. It may be queued, processing, failed, or will return the complete list of questions when complete, as shown in the example below.

Mining jobs with answers / questions include succeededAt, whereas jobs that return failed indicate that they reached a final state. When status is failed, jobs should be recreated manually (possibly with new parameters), as the mining service does not have a mechanism for auto-retry.

Also included in the response are the answers used when mining the job post. This can be useful when preparing test applications.

Each question will have a corresponding inputType based on the mined form, as below. Please note that different question types may have a different expected format for the value field. See making a job post application for more details.

# Input Types

inputType Description Expected Value Type
Text A text input field. String
TextArea A multiple-line text input field. String
TextLiteral Important text, often with indicative HTML tags on a key of value. String
SelectOne Includes available answers on a key of options, with any conditional questions on conditionalQuestions. String (selected option)
SelectMultiple Includes available answers on a key of options, with any conditional questions on conditionalQuestions. Array of Strings (selected options)
Date A date input field. String (ISO 8601 format)
Boolean A boolean input field. Boolean
File A file upload field. File object
ArrayOfObjects An array of objects relating to repeatable questions on the job post, e.g., a list of previous experience, each with repeatable questions. Example: "Please list your previous job experiences, including job title, company, and duration." Array of Objects
FragmentedQuestion Similar to ArrayOfObjects, but only expects one set of answers. Example: "What is your availability for the next month? Please specify days and times." Object

# Headers

Name Type Required Description
Authorization string See Authentication

Example:

Authorization: Basic <credentials>

# Query Parameters

Parameter Type Required Description
jobPostId string The unique identifier of the job post.

# Code Sample

To retrieve the questions for a specific job post, use the following API call:

GET /v2/recruitment/job-posts/find/

curl -X GET 'https://services.automation.cloud/v2/recruitment/job-posts/find/' \
    -H 'Authorization: Basic <credentials>' \
    -L \
    -G \
    -d 'jobPostId=example123' 

# Success Responses

# Status: queued

{
  "status": "queued"
}

# Status: processing

{
  "status": "processing"
}

Mining failed

{
 "status": "failed",
 "errorCode": "GenericWebsiteError"
} 

ℹ️ If mining fails, the error code may help to troubleshoot. Note that any code in failedPayload data is temporary and shouldn't be used for production rules.

Response when mined questions are found:

{
  "jobPostId": "example123",
  "answers": [
    {
      "value": "Yes",
      "id": "do-you-have-right-to-work-in-the-uk"
    },
    {
      "value": "No",
      "id": "are-you-resident-in-the-uk"
    },
    {
      "value": "No",
      "id": "do-you-have-a-car-that-you-can-use-for-w"
    },
    "...",
    {
      "value": "90210",
      "id": "what-is-your-postcode"
    }
  ],
  "questions": [
    {
      "question": "Do you have 'right to work' in the UK?",
      "id": "do-you-have-right-to-work-in-the-uk",
      "inputType": "SelectOne",
      "options": [
        {
          "answer": "Yes",
          "conditionalQuestions": []
        },
        {
          "answer": "No",
          "conditionalQuestions": []
        }
      ],
      "label": "Apply now",
      "mandatory": true
    },
    {
      "question": "Are you resident in the UK?",
      "id": "are-you-resident-in-the-uk",
      "inputType": "SelectOne",
      "options": [
        {
          "answer": "Yes",
          "conditionalQuestions": []
        },
        {
          "answer": "No",
          "conditionalQuestions": []
        }
      ],
      "label": "Apply now",
      "mandatory": true,
      "category": "country"
    },
    {
      "question": "Do you have a car that you can use for work?",
      "id": "do-you-have-a-car-that-you-can-use-for-w",
      "inputType": "SelectOne",
      "options": [
        {
          "answer": "Yes",
          "conditionalQuestions": []
        },
        {
          "answer": "No",
          "conditionalQuestions": []
        }
      ],
      "label": "Apply now",
      "mandatory": true
    },
    {
      "question": "What is your postcode?",
      "id": "what-is-your-postcode",
      "inputType": "Text",
      "label": "New form",
      "mandatory": true,
      "category": "zip"
    }
  ],
  "succeededAt": 1721315141741
}

# Error Handling

When working with the API, you may encounter various errors. Here are some common error responses and their meanings:

Status Code Error Message Description
400 Bad Request The request was invalid. Check the parameters and try again.
401 Unauthorized Invalid or missing API key. Ensure your credentials are correct.
404 Not Found The specified jobPostId does not exist or is invalid.
500 Internal Server Error An unexpected error occurred on the server. Try again later.

# Example Error Response

{
  "error": "Unauthorized",
  "message": "Invalid API key."
}