Skip to main content

​
Overview

A submission (also called a checklist log) is a completed instance of a template. The submission workflow follows these stages:

​
Submission States

StateDescription
draftIn progress, not yet submitted
submittedCompleted and submitted
pending_approvalAwaiting approval review
approvedApproved by reviewer
rejectedRejected by reviewer

​
Start a Submission

Create a new submission (draft) from a published template. 
curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/start" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "location-uuid",
    "assetId": "asset-uuid"
  }'
Request Body (Optional):
FieldTypeDescription
locationIdUUIDLocation where inspection is conducted
assetIdUUIDAsset being inspected (if applicable)
Response: 
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "submission-uuid",
    "checklistId": "template-uuid",
    "status": "draft",
    "score": null,
    "LocationId": "location-uuid",
    "AssetId": "asset-uuid",
    "CreatedById": "user-uuid",
    "sections": [
      {
        "id": "section-uuid",
        "title": "PPE Check",
        "items": [
          {
            "id": "item-uuid-1",
            "title": "Hard hat available?",
            "type": "yesNo",
            "required": true,
            "answer": null
          }
        ]
      }
    ],
    "createdAt": "2024-12-19T10:00:00Z"
  }
}
The response includes the full submission structure with all sections and items ready to be answered.

​
Get Submission Details

Retrieve a specific submission with all answers. 
curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/logs/{logId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"
Response: 
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "submission-uuid",
    "checklistId": "template-uuid",
    "checklistName": "Daily Safety Inspection",
    "status": "draft",
    "score": 85,
    "passingScore": 80,
    "passed": true,
    "LocationId": "location-uuid",
    "Location": {
      "id": "location-uuid",
      "name": "Building A"
    },
    "CreatedBy": {
      "id": "user-uuid",
      "fullName": "John Smith"
    },
    "sections": [
      {
        "id": "section-uuid",
        "title": "PPE Check",
        "items": [
          {
            "id": "item-uuid-1",
            "title": "Hard hat available?",
            "type": "yesNo",
            "answer": "yes",
            "answeredAt": "2024-12-19T10:05:00Z",
            "answeredBy": {
              "id": "user-uuid",
              "fullName": "John Smith"
            },
            "notes": [],
            "attachments": []
          }
        ]
      }
    ],
    "createdAt": "2024-12-19T10:00:00Z",
    "updatedAt": "2024-12-19T10:30:00Z"
  }
}

​
List Submissions

Get submissions for a specific template. 
curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/logs" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "submitted",
    "locationId": "location-uuid",
    "dateFrom": "2024-12-01",
    "dateTo": "2024-12-31",
    "page": 1,
    "perPage": 50
  }'
Filter Options:
FieldTypeDescription
statusstringFilter by status: draft, submitted, approved
locationIdUUIDFilter by location
assetIdUUIDFilter by asset
createdByIdUUIDFilter by creator
dateFromstringStart date (YYYY-MM-DD)
dateTostringEnd date (YYYY-MM-DD)
pagenumberPage number
perPagenumberItems per page

​
Answer Questions

​
Answer Single Question

Update a single item’s answer in the submission. 
curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-logs/{logId}/items/{itemId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": "yes"
  }'
Request Body:
FieldTypeDescription
answervariesAnswer value (type depends on question)
optionIdUUIDSelected option ID (for multipleChoice)
attachmentsstring[]URLs of attached files/photos
flaggedbooleanManually flag this item
flagNotestringNote explaining the flag
Response: 
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "item-uuid",
    "answer": "yes",
    "answeredAt": "2024-12-19T10:05:00Z",
    "score": 10,
    "flagged": false
  }
}

​
Answer Multiple Questions (Batch)

Update multiple items at once for efficiency. 
curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-logs/{logId}/items" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "itemId": "item-uuid-1",
        "answer": "yes"
      },
      {
        "itemId": "item-uuid-2",
        "answer": "Good",
        "optionId": "option-uuid"
      },
      {
        "itemId": "item-uuid-3",
        "answer": 72.5
      },
      {
        "itemId": "item-uuid-4",
        "answer": "no",
        "flagged": true,
        "flagNote": "Needs immediate attention"
      }
    ]
  }'
Use batch updates when answering multiple questions together. This reduces API calls and ensures atomic updates.

​
Add Notes

​
Add Note to Item

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-logs/{logId}/items/{itemId}/notes" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Observed minor rust on exterior. Scheduled for maintenance next week.",
    "attachments": ["https://storage.example.com/photos/rust-detail.jpg"]
  }'
Response: 
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "note-uuid",
    "content": "Observed minor rust on exterior. Scheduled for maintenance next week.",
    "attachments": ["https://storage.example.com/photos/rust-detail.jpg"],
    "CreatedBy": {
      "id": "user-uuid",
      "fullName": "John Smith"
    },
    "createdAt": "2024-12-19T10:10:00Z"
  }
}

​
Update Note

curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-logs/{logId}/items/{itemId}/notes/{noteId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated note: Maintenance completed on Dec 20."
  }'

​
Delete Note

curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-logs/{logId}/items/{itemId}/notes/{noteId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

​
Add Note to Entire Submission

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-logs/{logId}/notes" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Overall inspection completed. Building is in good condition with minor issues noted."
  }'

​
Submit Submission

Mark the submission as complete and trigger any configured workflows. 
curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/logs/{logId}/submit" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"
Response: 
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "submission-uuid",
    "status": "submitted",
    "score": 92,
    "passingScore": 80,
    "passed": true,
    "submittedAt": "2024-12-19T10:30:00Z",
    "approvalRequired": true,
    "approvalStatus": "pending"
  },
  "message": "Submission completed successfully"
}
Submitting a submission is final. Ensure all required questions are answered before submitting. If approval workflows are configured, the submission will enter a review queue.

​
Delete Submissions

Delete one or more submissions. 
curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/delete-logs" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "logIds": ["submission-uuid-1", "submission-uuid-2"]
  }'

​
Get Submission Count

Get the count of submissions for a template. 
curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/logs-count" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"
Response: 
{
  "status": "success",
  "code": 200,
  "data": {
    "total": 150,
    "draft": 5,
    "submitted": 130,
    "pending_approval": 10,
    "approved": 5
  }
}

​
Get Submission History

View the audit trail of changes to a submission. 
curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-logs/{logId}/history" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"
Response: 
{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "history-uuid-1",
      "action": "created",
      "timestamp": "2024-12-19T10:00:00Z",
      "user": {
        "id": "user-uuid",
        "fullName": "John Smith"
      }
    },
    {
      "id": "history-uuid-2",
      "action": "item_answered",
      "itemId": "item-uuid-1",
      "itemTitle": "Hard hat available?",
      "oldValue": null,
      "newValue": "yes",
      "timestamp": "2024-12-19T10:05:00Z",
      "user": {
        "id": "user-uuid",
        "fullName": "John Smith"
      }
    },
    {
      "id": "history-uuid-3",
      "action": "submitted",
      "timestamp": "2024-12-19T10:30:00Z",
      "user": {
        "id": "user-uuid",
        "fullName": "John Smith"
      }
    }
  ]
}

​
Common Workflows

​
Complete Inspection Flow

​
Batch Answer Workflow

For efficiency when answering many questions at once: 
# Start submission
LOG_ID=$(curl -X POST ".../checklists/{checklistId}/start" | jq -r '.data.id')

# Answer all questions in one request
curl -X PUT ".../checklist-logs/${LOG_ID}/items" \
  -d '{
    "items": [
      {"itemId": "item-1", "answer": "yes"},
      {"itemId": "item-2", "answer": "Good"},
      {"itemId": "item-3", "answer": 25.5},
      {"itemId": "item-4", "answer": "All clear"}
    ]
  }'

# Submit
curl -X PUT ".../logs/${LOG_ID}/submit"

​
Sync Inspection Data from Mobile

When syncing offline inspections: 
# Create submission with full data
curl -X POST ".../checklists/{checklistId}/start" \
  -d '{
    "locationId": "location-uuid",
    "offlineId": "mobile-device-uuid-123",
    "startedAt": "2024-12-19T09:00:00Z"
  }'

# Batch update all answers captured offline
curl -X PUT ".../checklist-logs/{logId}/items" \
  -d '{
    "items": [
      {
        "itemId": "item-1",
        "answer": "yes",
        "answeredAt": "2024-12-19T09:05:00Z"
      },
      {
        "itemId": "item-2",
        "answer": "no",
        "answeredAt": "2024-12-19T09:06:00Z",
        "attachments": ["https://storage.example.com/offline-photo-1.jpg"]
      }
    ]
  }'

# Submit with original completion time
curl -X PUT ".../logs/{logId}/submit"

​
Best Practices

When answering multiple questions, use the batch endpoint (PUT /checklist-logs/{id}/items) to reduce API calls.
Always specify locationId and assetId when starting submissions. This enables better reporting and filtering.
When flagging issues, attach photos to provide visual documentation. This helps reviewers and creates a clear audit trail.
Check that all required questions are answered before calling the submit endpoint to avoid validation errors.
For mobile apps, queue submissions locally and sync when online. Include timestamps to preserve accurate inspection times.

​
Error Handling

Error CodeMessageResolution
400”Required questions not answered”Answer all required items before submitting
400”Submission already submitted”Cannot modify a submitted submission
403”Cannot start submission”Check template is published and user has access
404”Checklist not found”Verify template ID exists
404”Submission not found”Verify submission ID exists