This API endpoint allows you to create an inspection based on a specific template. When a request is successful, the API returns the newly generated inspection and all its data.

To create an inspection without filling in any responses, include the template_id in the request body. This is the only required field to create a blank inspection. The team_id is optional and will be automatically derived from the template if not provided.

Optionally, you can also create a task linked to the inspection in the same request by including the task property in your payload. This allows you to assign work related to the inspection to specific team members without making a separate API call.

Create an inspection by copying an existing inspection

To populate responses, utilize an existing inspection as a template. This method involves accessing the details of an existing inspection, which already contains data for the items you intend to populate. Copy the relevant item(s) and adjust their responses before initiating the create request. Refer to the Get a list of inspections section for guidance on retrieving inspection details.

Request Payload

Required Fields

• template_id (Guid, required): The unique identifier of the template to use for creating the inspection. This is the only required field.

Optional Fields

• team_id (Guid, optional): The team ID for the inspection. If not provided, it will be automatically derived from the template. If provided, it must match the template's team.

• name (string, optional): The title or name of the inspection. If not provided, a default name will be generated using the template name and a timestamp.

• status (string, optional): The initial status of the inspection. Values are case-insensitive. Valid values are:

  • "new" (default)
  • "in_progress"
  • "completed"
  • "canceled"

• description (string, optional): A description or notes for the inspection.

• created_by (string, optional): The email address of the user who should be set as the creator of the inspection.

  • Must be a member of the organization
  • Must have access to the team associated with the template
  • If not provided or invalid, the API key owner will be used as the creator
  • Invalid emails generate warnings but don't fail the request

• custom_fields (array, optional): An array of object(s) containing custom fields associated with the inspection, with the following structure:

{
  "name": "Field Name",
  "value": "Field Value"
}

• data (object, optional): Inspection data containing question responses. See the "Inspection Data Structure" section below for details.

• locations (array, optional): An array of object(s) containing location object(s) for the inspection. This information is crucial for verifying the inspection-conducting site and generating KYPiT reports.

• task (object, optional): Task creation details. See the "Optional Task Creation" section below for complete details.

Inspection Data Structure

The data object has the following structure:

{
  "item_type": "question_response",
  "items": [
    {
      "field_id": "string (optional)",
      "template_control_id": "guid (optional)",
      "response": {
        "value": "response value"
      }
    }
  ]
}

• item_type: Must be "question_response" (currently the only supported type).

• items: An array of inspection data items. Each item must have either field_id or template_control_id (or both, but template_control_id takes precedence).

  • field_id: The unique Id of the field, which is available in our template builder's side panel in the Web App (ReportPlaceholderName from the template control - string identifier).
  • template_control_id: The unique identifier (Guid) of the template control.
  • response: An object containing the response data for the control. The object must have a value key that contains the actual response value. See the "Valid Responses for Control" section below for valid response formats for the value property.

Optional Task Creation

As an optional feature, you can create a task linked to the inspection in the same request. When you include the task property in your request payload, a task will be automatically created and linked to the newly designed inspection. This allows you to assign inspection-related work to specific team members.

Task Properties

The task object supports the following optional properties:

• title (string, optional): The title of the task. If not provided, the task will use the inspection title as its name.

• instructions (string, optional): Detailed instructions or description for the task. Can be left empty if not needed.

• priority (string, optional): The priority level of the task. The value is case-insensitive. Must be one of:

  • "high": High priority task
  • "medium": Medium priority task (default if not specified)
  • "low": Low-priority task

• due_date_time (string, optional): The due date and time for the task. Supports ISO 8601 format with timezone information. Examples:

  • "2024-04-17T20:30:00Z" (UTC)
  • "2024-04-17T20:30:00-05:00" (with timezone offset)
  • "2024-04-17 20:30:00" (without timezone, uses organization default)
    It's strongly recommended to use the ISO 8601 format with a timezone for consistency.

• assignee (array of strings, optional): An array of email addresses for users to assign to the task.

  • Maximum 50 assignees allowed per task
  • All assignees must be members of the organization
  • If not provided or empty, the task will be assigned to the inspection creator (the user associated with the API key or the created_by user if specified)
  • Invalid email addresses or users not in the organization will generate warnings, but won't prevent task creation

Task Assignee Logic

• If no assignees are provided in the assignee array, the task is automatically assigned to the inspection creator (either the API key owner or the user specified in created_by in the inspection object).

• If assignees are provided, the system validates that each email address:

  • Exists in the system
  • Is a member of the organization
  • Has not been deleted

• Invalid or unauthorized assignee emails generate warnings in the response but don't cause the request to fail. The task is still created with valid assignees.

• If all provided assignees are invalid, the task falls back to being assigned to the inspection creator.

Valid Responses for Control

To understand the valid or acceptable responses for a specific control type, please refer to the table below:

Response Structure

The API returns different response formats depending on whether a task was created or warnings were generated.

Simple Response

When no task is created, and there are no warnings, the response contains the inspection object directly:

{
  "id": "guid",
  "name": "Inspection Name",
  "status": "new",
  "description": "Inspection description",
  "created_at": "2024-04-17T20:30:00Z",
  "created_by": { /* user object */ },
  "updated_at": "2024-04-17T20:30:00Z",
  "updated_by": { /* user object */ },
  "timezone": "America/New_York",
  "custom_fields": [ /* custom fields array */ ],
  "custom_fields_count": 0,
  "team": { /* team object */ },
  "template": { /* template object */ },
  "locations": [ /* locations array */ ],
  "shared_with_users": [ /* shared users array */ ],
  "shared_with_users_count": 0,
  "data": { /* inspection data object */ }
}

Extended Response

When a task is created or warnings are generated, the response includes additional fields:

{
  "inspection": {
    /* full inspection object as shown above */
  },
  "task_id": "guid-or-null",
  "warnings": ["warning message 1", "warning message 2"] // or null if no warnings
}

• inspection: The complete inspection object (same structure as simple response).
• task_id: The unique identifier of the created task, or null if task creation failed or was not attempted.
• warnings: An array of warning messages, or null if there are no warnings. Common warnings include:
  • Invalid assignee emails
  • Invalid created_by email
  • Task creation failures
  • Other non-fatal issues

Field Validation and Limits

The API enforces the following validation rules and limits:

• Task Assignees: Maximum 50 assignees per task. If more than 50 are provided, the request will fail with a 400 Bad Request error.

• Inspection Data Items: Maximum 1000 inspection_data items per request. Exceeding this limit will result in a validation error.

• Assignee Emails: All assignee emails must:

  • Be valid email addresses
  • Belong to users who are members of the organization
  • Not deleted users

• Created By Email: The created_by email must:

  • Be a valid email address
  • Belong to a user who is a member of the organization
  • Have access to the team associated with the template

• Priority: Must be one of: "high", "medium", or "low" (case-insensitive). Invalid values default to "medium".

• Template ID: Must be a valid Guid and reference a template that:

  • Exists in the organization
  • Is published
  • Is not disabled

• Team ID: If provided, must match the team associated with the template.

Error Handling and Warnings

Warnings (Non-Fatal)

Warnings are included in the response, but don't cause the request to fail. The inspection is still created successfully. Common warning scenarios:

• Invalid Assignee Emails: If some assignee emails are invalid or the users are not organization members:

  • Warning: "Invalid or unauthorized assignee emails: [email protected], [email protected]"
  • Task is still created with valid assignees, or assigned to the creator if no valid assignees are found

• Invalid Created By Email: If the created_by email is invalid or the user doesn't have team access:

  • Warning: "Invalid created_by email: [email protected]." or "Creator user: [email protected] is not part of the organization."
  • Falls back to using the API key owner as creator

• Task Creation Failures: If task creation fails for any reason:

  • Warning: "Task creation failed: [reason]."
  • Inspection is still created successfully

• No Valid Assignees: If no valid assignees are found:

  • Warning: "No valid assignee users found in organization. Using the default assignee."
  • The task is assigned to the inspection creator

Errors (Fatal)

These errors cause the request to fail with an appropriate HTTP status code:

400 Bad Request:

• Missing template_id
• Invalid template_id format (not a valid Guid)
• More than 50 task assignees
• More than 1000 inspection_data items
• Invalid data.item_type (must be "question_response")
• Missing both field_id and template_control_id in inspection data items

404 Not Found:

• Template not found
• Template not published
• Template is disabled
• Template not in the organization
• Team ID provided, but doesn't match the template's team

401 Unauthorized:

• API key is invalid
• The API key doesn't have access to the organization
• The organization doesn't have the Public API feature enabled

500 Internal Server Error:

• Unexpected server errors during inspection or task creation
• Database transaction failures

Examples

Example 1: Basic Inspection Creation (Minimal Payload)

Create a blank inspection with only the required field:

Request:

{
  "template_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response:

{
  "id": "789e4567-e89b-12d3-a456-426614174001",
  "name": "Template Name - 1713385800",
  "status": "new",
  "created_at": "2024-04-17T20:30:00Z",
  "created_by": { /* user object */ },
  "team": { /* team object */ },
  "template": { /* template object */ },
  /* ... other inspection fields ... */
}

Example 2: Inspection with Task Creation

Create an inspection with a task assigned to specific users:

Request:

{
  "template_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Monthly Safety Inspection",
  "status": "new",
  "description": "April 2024 safety inspection",
  "task": {
    "title": "Review and Complete Safety Inspection",
    "instructions": "Please review the inspection and address any issues found.",
    "priority": "high",
    "due_date_time": "2024-04-20T17:00:00-05:00",
    "assignee": [
      "[email protected]",
      "[email protected]"
    ]
  }
}

Response:

{
  "inspection": {
    "id": "789e4567-e89b-12d3-a456-426614174001",
    "name": "Monthly Safety Inspection",
    "status": "new",
    /* ... other inspection fields ... */
  },
  "task_id": "456e4567-e89b-12d3-a456-426614174002",
  "warnings": null
}

Example 3: Inspection with Task and Multiple Assignees

Create an inspection with a task assigned to multiple team members:

Request:

{
  "template_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Site Inspection - Building A",
  "task": {
    "title": "Complete Site Inspection",
    "instructions": "Inspect all areas and document findings",
    "priority": "medium",
    "due_date_time": "2024-04-25T23:59:59Z",
    "assignee": [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ]
  }
}

Example 4: Inspection with Custom Creator

Create an inspection specifying a different creator:

Request:

{
  "template_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Field Inspection Report",
  "created_by": "[email protected]",
  "task": {
    "title": "Follow up on inspection findings",
    "priority": "high",
    "assignee": ["[email protected]"]
  }
}

Response (if created_by user is invalid):

{
  "inspection": {
    "id": "789e4567-e89b-12d3-a456-426614174001",
    "name": "Field Inspection Report",
    "created_by": { /* API key owner user object */ },
    /* ... other fields ... */
  },
  "task_id": "456e4567-e89b-12d3-a456-426614174002",
  "warnings": [
    "Invalid created_by email: [email protected]."
  ]
}

Example 5: Inspection with Data Responses

Create an inspection with pre-filled question responses:

Request:

{
  "template_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Equipment Inspection",
  "status": "in_progress",
  "data": {
    "item_type": "question_response",
    "items": [
      {
        "field_id": "equipment_name",
        "response": {
          "value": "Generator Unit 5"
        }
      },
      {
        "template_control_id": "789e4567-e89b-12d3-a456-426614174003",
        "response": {
          "value": "Operational"
        }
      },
      {
        "field_id": "last_maintenance_date",
        "response": {
          "value": "2024-04-01"
        }
      },
      {
        "field_id": "issues_found",
        "response": {
          "value": ["Oil leak", "Loose belt"]
        }
      }
    ]
  },
  "task": {
    "title": "Fix Equipment Issues",
    "instructions": "Address the issues found during inspection",
    "priority": "high",
    "due_date_time": "2024-04-18T12:00:00Z",
    "assignee": ["[email protected]"]
  }
}

Notes on Inspection Creation

• Currently, it's only possible to create template-based inspections; free-form inspections cannot be created.

• The type of inspection question_responses that can be populated at inspection creation time are: text, number, radio (single-choice), checkbox (multi-choice), dropdown (single-choice and multi-choice), date, and checkIn/location.

• Additionally, setting or adding files as well as notes is not supported in the current version of the API.

• The owner of the created inspection will be the user linked to the API key that was used to initiate the API call, unless a created_by email is provided and is valid.

• During inspection creation, it's not possible to set shares, meaning you cannot share the inspection with other users. However, you can utilize the "Share an Inspection" endpoint to share an inspection after it has been created.

• If the question_responses or any other data are malformed, the request will likely succeed, typically resulting in a common message and a "200" status code. Check the information of the created inspection in the response to ensure all data has been successfully populated, and also check the response for warnings.

Best Practices

General Best Practices

• Template Control Identification: When providing inspection data, you can use either field_id (unique Id of the field, which is available in our template builder's side panel in the Web App) or template_control_id (Guid). The template_control_id takes precedence if both are provided.

• Team ID: The team_id can be safely omitted as it's automatically derived from the template. Only provide it if you need to validate that the inspection is created for a specific team.

• Response Warnings: Always check the warnings array in the response (when present) to identify any issues that occurred during creation, even if the request was successful.

• Error Handling: Implement proper error handling in your application to catch and handle different HTTP status codes appropriately.

• Rate Limiting: Be aware of API rate limits and implement appropriate retry logic with exponential backoff for transient failures.

Task Creation Best Practices

• Task Creation: Task creation is optional and happens automatically when the task property is provided. You don't need to make a separate API call to create a task.

• Date/Time Format: Always use ISO 8601 format for due_date_time with timezone information to avoid ambiguity. For example: "2024-04-17T20:30:00-05:00" or "2024-04-17T20:30:00Z".

• Task Assignees: Verify that assignee email addresses belong to organization members before making the API call. Invalid assignees will generate warnings but won't prevent task creation.

• Task ID: The presence of task_id in the response indicates successful task creation. If task_id is null but a task was requested, check the warnings array for details.