To create a requisition you must send a JSON:API spec JSON object. The list of attributes and relationships can be found in the Body Params.

🚧

Warning

requisitions created through the API currently do not trigger sign-off workflows and are created as already approved.

The requisitions created through the API are not able to be used to extend the headcount of jobs.

Required Associations

When creating requisitions, you must have a relationship to a requisition_template. All of the required requisition_template_fields of the chosen template, must have requisition_details created for them which answer the fields' questions. All of the details must provide the correct value inline with the field's question type, eg, boolean_value for booleans and integer_value for integer fields.

You can check a requisition_template's fields and their types and if they are required by fetching the desired requisition_template and including its requisition_template_fields. More information about fetching Requisition Templates here.

👍

How to construct relationship data in the request body

1. List Requisition Templates and pick the id of the requisition_template which you want to use to create a new Requisition.
2. Using Fetch Requisition Template fetch the desired requisition_template whilst also including its requisition_template_fields.
3. Use the requisition_template's id in the relationships.requisition_template in the request body for requisition creation.
4. For each requisition_template_fields add a requisition_details entries in the relationships.requisition_details and included section of the request body

In the below example, we provide a name and identifier for the new requisition as well as define the relationships to the requisition_template and to any requisition_details that may be needed. Here the only field is a headcount field. We provide a temp-id to the requisition_detail that we want to create in the relationships section which matches the temp-id of the corresponding requisition_detail in the included section. The attributes of the new detail should be provided in the included section.

Example Request Body

{
  "data": {
    "type": "requisitions",
    "attributes": {
      "name": "api test",
      "identifier": "example"
    },
    "relationships": {
      "requisition_template": {
        "data": {
          "type": "requisition_templates",
          "id": "2"
        }
      },
      "requisition_details": {
        "data": [
          {
            "type": "requisition_details",
            "method": "create",
            "temp-id": "temp-id-1"
            }
          ]
      }
    }
  },
   "included": [
    {
      "type": "requisition_details",
      "temp-id": "temp-id-1",
      "attributes": {
        "integer_value": "3"
      },
      "relationships": {
        "requisition_template_field": {
          "data": {
            "type": "requisition_template_fields",
            "id": "5"
          }
        }
      }
    }
   ]
}

Requisition creator

You can provide the email of the requisition creator to assign that user as the creator. If this isn't provided the API will use your company's system_user as the creator.

In order to assign a creator add creator_email to the request.

Relationship Error Handling

If a required field is not answered you will receive an error feedback informing you of which field was missing.

If when creating the requisition_detail, the wrong value_type input is provided (i.e. integer instead of text), the wrong data type is input into the correct value_type (i.e. "hello world" into a boolean_value) or is left blank, you will also receive an error feedback explaining that the necessary value_type is blank or the wrong type of data.

Notes

📘

Important

The requisition_details should also be added to the included section of the JSON.

To see an example, select the basic option from the drop down on the top-right corner of the example code that is labelled 'EXAMPLES'.

📘

Important

All requisitions created through the API will automatically be approved and ready for use to create new jobs.