Talroo Apply Integration Testing

Application Questions JSON Testing

To help with the current and future development of Application Questions JSONs we have created the POST /applications/questions/validate endpoint to validate Application Question JSONs.

You will need to create an App Client to access and utilize the API. When using the API, you should ensure the POST body payload used with the API is the same value that will be returned by the URL found in the <custom_question> nodes within your Talroo Apply feed.

Usage Example

Below is an example request to the POST /applications/questions/validate endpoint that uses the full Application Question JSON example:

curl -X 'POST' \
  'https://api.talroo.com/v5/applications/questions/validate' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ***' \
  -H 'Content-Type: application/json' \
  -d '[
    {
        "id": "page1_open",
        "type": "pagebreak"
    },
    {
        "id": "previous_company",
        "limit": 100,
        "question": "What company did you work for previously?",
        "required": true,
        "type": "text"
    },
    {
        "id": "currently_work_here",
        "question": "I currently work here",
        "required": false,
        "type": "select",
        "options": [
            {
                "label": "No",
                "value": "0"
            },
            {
                "label": "Yes",
                "value": "1"
            }
        ]
    },
    ...
    {
        "id": "information_question",
        "text": "While it is not strictly necessary, it is highly recommended to provide a cover letter details and highlight into highlight the reasons on why you would make a great candidate for this position.",
        "type": "information"
    },
    {
        "id": "recent_example_work",
        "question": "Please attach a cover letter.",
        "required": false,
        "type": "file"
    },
    {
        "id": "page7_close",
        "type": "pagebreak"
    }
]'

When a valid Application Question JSON is sent you should receive a 200 with the following response body:

{
  "valid": true
}

Debugging Errors

If an invalid Application Question JSON is provided, you should receive a 422 status with a response body containing an errors field detailing the issues with the Application Question JSON. Examples of this error response bodies can be found below:

Missing ID field for question

{
  "type": "/errors/unprocessable-entity",
  "title": "Unprocessable entity",
  "status": 422,
  "instance": "https://api.talroo.com/v5/logs/201edc5e-82ce-419b-b9b8-d5678822120b",
  "valid": false,
  "message": "A validation error occurred. Please check the error message for more details",
  "errors": [
    {
      "message": "Questions must have the \"id\" property",
      "property": "id"
    }
  ]
}

Missing Type field for question

{
  "type": "/errors/unprocessable-entity",
  "title": "Unprocessable entity",
  "status": 422,
  "instance": "https://api.talroo.com/v5/logs/e848a11a-959e-4e20-9945-b1f94d2bcc9f",
  "valid": false,
  "message": "A validation error occurred. Please check the error message for more details",
  "errors": [
    {
      "message": "Questions must have the \"type\" property, and \"type\" must be one of the following: textarea, text, select, hierarchical, multiselect, date, file, information, pagebreak",
      "property": "type",
      "questionId": "recent_example_work",
      "type": null
    }
  ]
}

End to End Testing

Once you have created a dedicated Talroo Apply XML Job Feed, you should work with your Talroo POC to conduct a full end-to-end test of the integration. This requires an XML feed containing jobs with <custom_question> values pointing to valid Application Question JSONs, and <postUrl> values containing live POST endpoints where application data can be sent to and correctly processed by your system for your confirmation.

Jobs included in this feed will not be advertised, so it is okay for them to contain actual job info.

To ensure success of the integration, it is imperative we confirm application data is properly processed by your system before going live.