> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Submission Workflow

> Complete the full inspection lifecycle from start to submit

## Overview

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

```mermaid theme={null}
graph LR
    A[Start Draft] --> B[Answer Questions]
    B --> C[Add Notes/Photos]
    C --> D[Submit]
    D --> E{Approval Required?}
    E -->|Yes| F[Pending Review]
    E -->|No| G[Completed]
    F --> G
```

***

## Submission States

| State              | Description                    |
| ------------------ | ------------------------------ |
| `draft`            | In progress, not yet submitted |
| `submitted`        | Completed and submitted        |
| `pending_approval` | Awaiting approval review       |
| `approved`         | Approved by reviewer           |
| `rejected`         | Rejected by reviewer           |

***

## Start a Submission

Create a new submission (draft) from a published template.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

**Request Body (Optional):**

| Field        | Type | Description                            |
| ------------ | ---- | -------------------------------------- |
| `locationId` | UUID | Location where inspection is conducted |
| `assetId`    | UUID | Asset being inspected (if applicable)  |

**Response:**

```json theme={null}
{
  "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"
  }
}
```

<Note>
  The response includes the full submission structure with all sections and items ready to be answered.
</Note>

***

## Get Submission Details

Retrieve a specific submission with all answers.

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

**Filter Options:**

| Field         | Type   | Description                                        |
| ------------- | ------ | -------------------------------------------------- |
| `status`      | string | Filter by status: `draft`, `submitted`, `approved` |
| `locationId`  | UUID   | Filter by location                                 |
| `assetId`     | UUID   | Filter by asset                                    |
| `createdById` | UUID   | Filter by creator                                  |
| `dateFrom`    | string | Start date (YYYY-MM-DD)                            |
| `dateTo`      | string | End date (YYYY-MM-DD)                              |
| `page`        | number | Page number                                        |
| `perPage`     | number | Items per page                                     |

***

## Answer Questions

### Answer Single Question

Update a single item's answer in the submission.

<CodeGroup>
  ```bash cURL (Yes/No Question) theme={null}
  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"
    }'
  ```

  ```bash cURL (Multiple Choice) theme={null}
  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": "Good",
      "optionId": "option-uuid"
    }'
  ```

  ```bash cURL (Text Response) theme={null}
  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": "Equipment is functioning normally with no visible damage."
    }'
  ```

  ```bash cURL (Number Response) theme={null}
  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": 72.5
    }'
  ```

  ```bash cURL (With Attachments) theme={null}
  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": "no",
      "attachments": [
        "https://storage.example.com/photos/damage-photo.jpg"
      ]
    }'
  ```
</CodeGroup>

**Request Body:**

| Field         | Type      | Description                             |
| ------------- | --------- | --------------------------------------- |
| `answer`      | varies    | Answer value (type depends on question) |
| `optionId`    | UUID      | Selected option ID (for multipleChoice) |
| `attachments` | string\[] | URLs of attached files/photos           |
| `flagged`     | boolean   | Manually flag this item                 |
| `flagNote`    | string    | Note explaining the flag                |

**Response:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
        }
      ]
    }'
  ```
</CodeGroup>

<Tip>
  Use batch updates when answering multiple questions together. This reduces API calls and ensures atomic updates.
</Tip>

***

## Add Notes

### Add Note to Item

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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."
    }'
  ```
</CodeGroup>

### Delete Note

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

### Add Note to Entire Submission

<CodeGroup>
  ```bash cURL theme={null}
  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."
    }'
  ```
</CodeGroup>

***

## Submit Submission

Mark the submission as complete and trigger any configured workflows.

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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"
}
```

<Warning>
  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.
</Warning>

***

## Delete Submissions

Delete one or more submissions.

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

***

## Get Submission Count

Get the count of submissions for a template.

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

```mermaid theme={null}
sequenceDiagram
    participant Client as Your System
    participant API as Xenia API

    Client->>API: 1. POST /checklists/{id}/start
    Note right of Client: Create draft submission
    API-->>Client: Submission created (draft)

    loop For each question
        Client->>API: 2. PUT /checklist-logs/{id}/items/{itemId}
        Note right of Client: Answer question
        API-->>Client: Answer saved
    end

    Client->>API: 3. POST /checklist-logs/{id}/items/{itemId}/notes
    Note right of Client: Add notes/photos
    API-->>Client: Note added

    Client->>API: 4. PUT /logs/{id}/submit
    Note right of Client: Submit completed inspection
    API-->>Client: Submission complete
```

### Batch Answer Workflow

For efficiency when answering many questions at once:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Use batch updates for efficiency">
    When answering multiple questions, use the batch endpoint (`PUT /checklist-logs/{id}/items`) to reduce API calls.
  </Accordion>

  <Accordion title="Include location and asset context">
    Always specify `locationId` and `assetId` when starting submissions. This enables better reporting and filtering.
  </Accordion>

  <Accordion title="Add photos for flagged items">
    When flagging issues, attach photos to provide visual documentation. This helps reviewers and creates a clear audit trail.
  </Accordion>

  <Accordion title="Validate before submitting">
    Check that all required questions are answered before calling the submit endpoint to avoid validation errors.
  </Accordion>

  <Accordion title="Handle offline scenarios">
    For mobile apps, queue submissions locally and sync when online. Include timestamps to preserve accurate inspection times.
  </Accordion>
</AccordionGroup>

***

## Error Handling

| Error Code | Message                           | Resolution                                      |
| ---------- | --------------------------------- | ----------------------------------------------- |
| 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                     |

***

## Related Guides

* [Template Management](/guides/workflows/template-management) - Create and configure templates
* [Submission Exports](/guides/workflows/submission-exports) - Export submission data
* [Submission Approvals](/guides/workflows/submission-approvals) - Configure approval workflows