Submission Approvals

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

Configure Template Approvals

Create Approval Flow

Add an approval workflow to a template.

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
    }
  }'

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:

{
  "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"
  }
}

Permission Required: CAN_MANAGE_APPROVALS

List Approval Configurations

Get all approval workflows for your workspace.

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}"

Get Approval Configuration

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}"

Update Approval Configuration

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
    }
  }'

Delete Approval Configuration

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}"

Publish Approval Flow

Approval configurations must be published to take effect.

Publish

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}"

Unpublish

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}"

Multi-Step Approval Workflows

Create approval workflows with multiple sequential steps.

Add Workflow Step

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
    }
  }'

Multi-Step Flow Example:

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

List Workflow Steps

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}"

Update Workflow Step

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
  }'

Delete Workflow Step

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}"

View Submission Approvals

List Pending Approvals

Get all submissions awaiting approval.

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}"

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:

{
  "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

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}"

Export Approvals as Spreadsheet

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}"

Process Approvals

Approve Submission

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."
  }'

Request Body:

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

Response:

{
  "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

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."
  }'

Approval Audit Trail

View Approval Logs

Get the complete audit trail for approvals.

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}"

Response:

{
  "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.

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"]
  }'

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:

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

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

Best Practices

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.

Keep approval chains short

Long approval chains create bottlenecks. Limit to 2-3 steps maximum for most workflows.

Require comments for rejections

Always require comments when rejecting submissions. This provides clear feedback for the submitter.

Use role-based approvers

Prefer role-based approvers over specific users. This ensures continuity when team members change.

Monitor approval queues

Regularly review pending approvals to prevent backlog. Consider auto-approval after X days for non-critical workflows.

Test before publishing

Create test submissions to verify approval workflows before publishing to production.

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

Template Management - Configure templates
Submission Workflow - Complete submissions
Submission Exports - Export submission data

Getting Started

Workflows

Integrations

Overview

Approval Flow

Configure Template Approvals

Create Approval Flow

List Approval Configurations

Get Approval Configuration

Update Approval Configuration

Delete Approval Configuration

Publish Approval Flow

Publish

Unpublish

Multi-Step Approval Workflows

Add Workflow Step

List Workflow Steps

Update Workflow Step

Delete Workflow Step

View Submission Approvals

List Pending Approvals

Get Specific Approval

Export Approvals as Spreadsheet

Process Approvals

Approve Submission

Reject Submission

Approval Audit Trail

View Approval Logs

Batch Operations

Common Workflows

Setup Conditional Approval

Setup Flagged Item Escalation

Multi-Level Approval Chain

Best Practices

Error Handling

Getting Started

Workflows

Integrations

​Overview

​Approval Flow

​Configure Template Approvals

​Create Approval Flow

​List Approval Configurations

​Get Approval Configuration

​Update Approval Configuration

​Delete Approval Configuration

​Publish Approval Flow

​Publish

​Unpublish

​Multi-Step Approval Workflows

​Add Workflow Step

​List Workflow Steps

​Update Workflow Step

​Delete Workflow Step

​View Submission Approvals

​List Pending Approvals

​Get Specific Approval

​Export Approvals as Spreadsheet

​Process Approvals

​Approve Submission

​Reject Submission

​Approval Audit Trail

​View Approval Logs

​Batch Operations

​Common Workflows

​Setup Conditional Approval

​Setup Flagged Item Escalation

​Multi-Level Approval Chain

​Best Practices

​Error Handling

​Related Guides

Overview

Approval Flow

Configure Template Approvals

Create Approval Flow

List Approval Configurations

Get Approval Configuration

Update Approval Configuration

Delete Approval Configuration

Publish Approval Flow

Publish

Unpublish

Multi-Step Approval Workflows

Add Workflow Step

List Workflow Steps

Update Workflow Step

Delete Workflow Step

View Submission Approvals

List Pending Approvals

Get Specific Approval

Export Approvals as Spreadsheet

Process Approvals

Approve Submission

Reject Submission

Approval Audit Trail

View Approval Logs

Batch Operations

Common Workflows

Setup Conditional Approval

Setup Flagged Item Escalation

Multi-Level Approval Chain

Best Practices

Error Handling

Related Guides