> ## 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 Approvals

> Configure approval workflows and manage submission reviews

## Overview

Approval workflows add a review step to submissions before they are considered complete. This is essential for:

* **Quality control**: Ensure submissions meet standards
* **Compliance**: Require supervisor sign-off on inspections
* **Escalation**: Route critical findings to appropriate reviewers
* **Audit trails**: Document who approved what and when

***

## Approval Flow

```mermaid theme={null}
graph LR
    A[Submitted] --> B{Approval Required?}
    B -->|No| C[Completed]
    B -->|Yes| D[Pending Approval]
    D --> E{Reviewer Decision}
    E -->|Approve| F[Approved]
    E -->|Reject| G[Rejected]
    G --> H[Revision Requested]
    H --> A
```

***

## Configure Template Approvals

### Create Approval Flow

Add an approval workflow to a template.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approval" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Safety Review Approval",
      "description": "Requires safety manager approval for all safety inspections",
      "isActive": true,
      "conditions": {
        "triggerOn": "submission",
        "scoreThreshold": null,
        "flaggedItemRequired": false
      },
      "approvers": [
        {
          "type": "role",
          "roleId": "safety-manager-role-uuid"
        }
      ],
      "settings": {
        "requireComment": true,
        "notifySubmitter": true,
        "autoApproveAfterDays": null
      }
    }'
  ```
</CodeGroup>

**Request Body:**

| Field         | Type    | Required | Description                             |
| ------------- | ------- | -------- | --------------------------------------- |
| `name`        | string  | Yes      | Approval workflow name                  |
| `description` | string  | No       | Workflow description                    |
| `isActive`    | boolean | No       | Enable/disable workflow (default: true) |
| `conditions`  | object  | No       | When to trigger approval                |
| `approvers`   | array   | Yes      | Who can approve                         |
| `settings`    | object  | No       | Additional settings                     |

**Condition Options:**

| Field                 | Type    | Description                                     |
| --------------------- | ------- | ----------------------------------------------- |
| `triggerOn`           | string  | `"submission"` (all), `"score"`, or `"flagged"` |
| `scoreThreshold`      | number  | Trigger when score below this value             |
| `flaggedItemRequired` | boolean | Trigger only when items are flagged             |

**Approver Types:**

| Type                | Description                    |
| ------------------- | ------------------------------ |
| `user`              | Specific user by ID            |
| `role`              | Anyone with specified role     |
| `submitter_manager` | Submitter's direct manager     |
| `location_manager`  | Manager of submission location |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "approval-uuid",
    "name": "Safety Review Approval",
    "checklistId": "template-uuid",
    "isActive": true,
    "isPublished": false,
    "createdAt": "2024-12-19T10:00:00Z"
  }
}
```

<Note>
  **Permission Required:** `CAN_MANAGE_APPROVALS`
</Note>

### List Approval Configurations

Get all approval workflows for your workspace.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/approvals" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Get Approval Configuration

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Update Approval Configuration

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Safety Review",
      "conditions": {
        "triggerOn": "score",
        "scoreThreshold": 80
      }
    }'
  ```
</CodeGroup>

### Delete Approval Configuration

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Publish Approval Flow

Approval configurations must be published to take effect.

### Publish

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}/publish" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Unpublish

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}/unpublish" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Multi-Step Approval Workflows

Create approval workflows with multiple sequential steps.

### Add Workflow Step

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}/workflow" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Manager Review",
      "order": 1,
      "approvers": [
        {
          "type": "submitter_manager"
        }
      ],
      "settings": {
        "requireComment": false
      }
    }'
  ```

  ```bash cURL (Second Step) theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}/workflow" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Director Final Approval",
      "order": 2,
      "approvers": [
        {
          "type": "role",
          "roleId": "director-role-uuid"
        }
      ],
      "settings": {
        "requireComment": true
      }
    }'
  ```
</CodeGroup>

**Multi-Step Flow Example:**

```
Step 1: Manager Review (order: 1)
    ↓ Approved
Step 2: Director Approval (order: 2)
    ↓ Approved
Submission Complete
```

### List Workflow Steps

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}/workflows" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Update Workflow Step

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}/workflow/{workflowId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Step Name",
      "order": 2
    }'
  ```
</CodeGroup>

### Delete Workflow Step

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/{approvalId}/workflow/{workflowId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## View Submission Approvals

### List Pending Approvals

Get all submissions awaiting approval.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/submission-approvals?status=pending" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Query Parameters:**

| Parameter     | Type   | Description                       |
| ------------- | ------ | --------------------------------- |
| `status`      | string | `pending`, `approved`, `rejected` |
| `checklistId` | UUID   | Filter by template                |
| `locationId`  | UUID   | Filter by location                |
| `dateFrom`    | string | Start date                        |
| `dateTo`      | string | End date                          |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "submission-approval-uuid",
      "submissionId": "submission-uuid",
      "checklistName": "Daily Safety Inspection",
      "submitter": {
        "id": "user-uuid",
        "fullName": "John Smith"
      },
      "location": {
        "id": "location-uuid",
        "name": "Building A"
      },
      "submittedAt": "2024-12-19T10:30:00Z",
      "score": 85,
      "status": "pending",
      "currentStep": 1,
      "totalSteps": 2,
      "approvalWorkflow": {
        "id": "approval-uuid",
        "name": "Safety Review Approval"
      }
    }
  ]
}
```

### Get Specific Approval

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/submission-approvals/{approvalId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Export Approvals as Spreadsheet

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/submission-approvals/spreadsheet?status=approved&dateFrom=2024-12-01&dateTo=2024-12-31" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Process Approvals

### Approve Submission

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/submission-approval-workflows/{workflowId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "approve",
      "comment": "Inspection meets all safety requirements. Approved."
    }'
  ```
</CodeGroup>

**Request Body:**

| Field     | Type   | Required    | Description                          |
| --------- | ------ | ----------- | ------------------------------------ |
| `action`  | string | Yes         | `"approve"` or `"reject"`            |
| `comment` | string | Conditional | Required if `requireComment` is true |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "workflow-uuid",
    "status": "approved",
    "approvedBy": {
      "id": "user-uuid",
      "fullName": "Safety Manager"
    },
    "approvedAt": "2024-12-19T14:00:00Z",
    "comment": "Inspection meets all safety requirements. Approved.",
    "submissionStatus": "approved"
  },
  "message": "Submission approved successfully"
}
```

### Reject Submission

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/submission-approval-workflows/{workflowId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "reject",
      "comment": "Missing photos for flagged items. Please re-submit with documentation."
    }'
  ```
</CodeGroup>

***

## Approval Audit Trail

### View Approval Logs

Get the complete audit trail for approvals.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/submission-approval-logs?submissionId={submissionId}" \
    -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": "log-uuid-1",
      "action": "submitted",
      "user": {
        "id": "user-uuid",
        "fullName": "John Smith"
      },
      "timestamp": "2024-12-19T10:30:00Z",
      "details": {
        "score": 85
      }
    },
    {
      "id": "log-uuid-2",
      "action": "approval_requested",
      "step": 1,
      "stepName": "Manager Review",
      "timestamp": "2024-12-19T10:30:01Z"
    },
    {
      "id": "log-uuid-3",
      "action": "approved",
      "step": 1,
      "stepName": "Manager Review",
      "user": {
        "id": "manager-uuid",
        "fullName": "Manager Name"
      },
      "timestamp": "2024-12-19T12:00:00Z",
      "comment": "Looks good"
    },
    {
      "id": "log-uuid-4",
      "action": "approval_requested",
      "step": 2,
      "stepName": "Director Final Approval",
      "timestamp": "2024-12-19T12:00:01Z"
    }
  ]
}
```

***

## Batch Operations

Perform batch operations on multiple approval configurations.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/approvals/batch-operations" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "operation": "publish",
      "approvalIds": ["approval-uuid-1", "approval-uuid-2"]
    }'
  ```
</CodeGroup>

**Operations:**

* `publish` - Publish multiple approval configurations
* `unpublish` - Unpublish multiple approval configurations
* `delete` - Delete multiple approval configurations

***

## Common Workflows

### Setup Conditional Approval

Create approval that only triggers for low scores:

```bash theme={null}
# Create approval that triggers when score < 80
curl -X POST ".../checklists/{checklistId}/approval" \
  -d '{
    "name": "Low Score Review",
    "conditions": {
      "triggerOn": "score",
      "scoreThreshold": 80
    },
    "approvers": [
      {"type": "role", "roleId": "quality-manager-uuid"}
    ]
  }'

# Publish to activate
curl -X POST ".../checklists/{checklistId}/approvals/{approvalId}/publish"
```

### Setup Flagged Item Escalation

Create approval that triggers only when items are flagged:

```bash theme={null}
curl -X POST ".../checklists/{checklistId}/approval" \
  -d '{
    "name": "Flagged Item Review",
    "conditions": {
      "triggerOn": "flagged",
      "flaggedItemRequired": true
    },
    "approvers": [
      {"type": "submitter_manager"}
    ],
    "settings": {
      "requireComment": true,
      "notifySubmitter": true
    }
  }'
```

### Multi-Level Approval Chain

```mermaid theme={null}
sequenceDiagram
    participant Sub as Submitter
    participant API as Xenia API
    participant Mgr as Manager
    participant Dir as Director

    Sub->>API: Submit inspection (score: 75)
    API-->>API: Score < 80, trigger approval

    API->>Mgr: Step 1: Request approval
    Mgr->>API: Approve with comment

    API->>Dir: Step 2: Request final approval
    Dir->>API: Approve with comment

    API->>Sub: Notification: Approved
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use conditional triggers wisely">
    Don't require approval for every submission. Use score thresholds or flagged item triggers to focus reviewer attention on submissions that need it.
  </Accordion>

  <Accordion title="Keep approval chains short">
    Long approval chains create bottlenecks. Limit to 2-3 steps maximum for most workflows.
  </Accordion>

  <Accordion title="Require comments for rejections">
    Always require comments when rejecting submissions. This provides clear feedback for the submitter.
  </Accordion>

  <Accordion title="Use role-based approvers">
    Prefer role-based approvers over specific users. This ensures continuity when team members change.
  </Accordion>

  <Accordion title="Monitor approval queues">
    Regularly review pending approvals to prevent backlog. Consider auto-approval after X days for non-critical workflows.
  </Accordion>

  <Accordion title="Test before publishing">
    Create test submissions to verify approval workflows before publishing to production.
  </Accordion>
</AccordionGroup>

***

## Error Handling

| Error Code | Message                     | Resolution                                          |
| ---------- | --------------------------- | --------------------------------------------------- |
| 400        | "Comment required"          | Provide comment when required by workflow settings  |
| 403        | "Not authorized to approve" | User doesn't have approval permission for this step |
| 404        | "Approval not found"        | Verify approval ID exists                           |
| 409        | "Already processed"         | This approval step was already actioned             |

***

## Related Guides

* [Template Management](/guides/workflows/template-management) - Configure templates
* [Submission Workflow](/guides/workflows/submission-workflow) - Complete submissions
* [Submission Exports](/guides/workflows/submission-exports) - Export submission data