This endpoint creates a new inspection from a specified template ID. Each successful request returns the full inspection body.
To simply create an inspection without pre-filling any responses send only the template_id in the request body as shown in the examples of this section.
The type of inspection items that can be pre-filled at inspection creation time at present are: text, textsingle, address, datetime, question, list, checkbox, slider and switch.
Pre-fill responses by copying an existing inspection
The easiest way to construct pre-filled item responses is by retrieving the information of an existing inspection which has populated responses for the items to be pre-filled, copying the item(s) of interest and modifying their responses as desired before executing the start inspection request. See Get an inspection (legacy) for how to retrieve inspection information. Tip: It is often enough to copy the entire inspection information returned this way into the start inspection request body as any unsupported JSON properties will be ignored. In some cases, however, you may need to remove the responses property from datetime items where the responses.datetime property is null.
Pre-fill by adding item responses one by one
To pre-fill inspection responses one by one, add one or more items to the header_items and/or items array. The JSON content of the pre-filled items should be as described in Inspection Format but only the item_id, type, label and responses fields are required to be present for pre-fill to work. Any additional properties of the items present in the request will be ignored.
For example, to start an inspection with a pre-filled Conducted on header item only, add the item to the header_items array, set its responses property to the desired value (an ISO8601 timestamp) and ensure its item_id matches the corresponding item on the template. An example request body for this is included in the examples of this section.
More items can be added the same way to the header_items and/or items array property of the start inspection request.
The format of the pre-filled response of each item must be valid for the type of the particular item e.g. a single line of text should be provided for items of textsingle type (otherwise newlines will be converted to spaces), a valid ISO8601 timestamp should be given for items of datetime type etc.
- The
item_idof standard header items are always the same across all templates.- Providing a different
labelwill not override the label value set in the template.
Pre-fill multiple-choice item responses
Multi-choice (question or list) item responses can be of different types. Only text and response-set responses are supported at this stage.
See Template Data for more on response-set responses.
To add a text-type response simply populate the responses.text property of the item with the desired response text.
To add one or more response-set responses you will need to provide the ID of each response-set response. An example of this is included in the request examples of this section. You can discover the ID of available responses-set responses by Get an inspection (legacy) created against the same template and copying the id of the desired response-set response from the available response sets in the Template Data. The safest way to ensure the right response IDs are added to the request, prefer to pre-fill responses by copying an existing inspection that you know has the desired responses filled in as appropriate.
Notes on inspection creation
The created_at, modified_at, audit_data.date_started, and audit_data.date_modified properties of each new inspection are set and managed by SafetyCulture. The Conducted on header item can be pre-filled by providing a UTC ISO8601 timestamp for it in the start inspection request body as shown in the examples of this section or changed later via editing the inspection. Please note that it's up to the caller of the API to convert timestamp responses to UTC before making the request.
The owner and author of the created inspection will be the user who is making the API request. Note: the author will change automatically the next time the inspection is edited and saved by another user.
Limits apply to the size of pre-fill responses provided with the request. For instance, text responses cannot be more than 3000 characters long.
Malformed responses will typically cause the request to fail with a relevant error message. In some cases, however, malformed responses such as when the type property of the item is missing from the request body may simply cause the pre-fill responses to be ignored. Check the information of the created inspection in the response to ensure all responses have been successfully pre-filled.