Submission Exports

Overview

Xenia gives you several ways to pull submission (checklist log) data out for reporting:

PDF reports — formatted inspection reports (single, merged, or one file per submission)
Excel exports — tabular submission data, generated asynchronously and delivered by notification
Spreadsheet link — a ready-to-download spreadsheet URL
Public PDF — a PDF for a submission whose public report is enabled
Submission records & counts — raw records and status counts for BI tools

All of these are reachable with a client key (x-client-key / x-client-secret). Base URL is https://api.xenia.team and every path starts with /api/v1. The workspace is derived from your key; where an unscoped /api/v1/ops/... path is shown, an equivalent /api/v1/ops/workspaces/{workspaceId}/... form also works.

Standard responses use the { data, meta } envelope. There is no status/statusCode/success field on those. The PDF endpoints are the exception — they respond with a raw { status, code, message, data } body and HTTP 202 while generation runs in the background. Long-running exports are generated out-of-band; the API returns immediately. Requests are bounded by an ALB timeout of roughly 60 seconds.

PDF Export

Generate a PDF for one or more submissions (checklist logs) of a template. Generation is asynchronous — the API accepts the request and the finished PDF is delivered by notification (a download:ready socket event / in-app notification). Endpoint: POST /api/v1/ops/checklists/{checklistId}/logs-pdf

curl -X POST "https://api.xenia.team/api/v1/ops/checklists/{checklistId}/logs-pdf" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "logIds": ["submission-uuid-1", "submission-uuid-2"],
    "separateFiles": false
  }'

Request Body:

Field	Type	Default	Description
`logIds`	string[]	—	Submission (checklist log) IDs to render
`separateFiles`	boolean	`false`	`false` = one merged PDF; `true` = one file per submission

Response (HTTP 202):

{
  "status": true,
  "code": 202,
  "message": "PDF generation in progress.",
  "data": {
    "requestIds": ["request-uuid"],
    "logIds": ["submission-uuid-1", "submission-uuid-2"]
  }
}

If a single requested submission already has a rendered PDF, the API emits the ready event immediately and returns 202 with data.requestIds: []. If none of the submissions are accessible, it returns 400 with "You don't have permission to download PDF for this submission."

Excel Export

Kick off an Excel export of a template’s submissions. The report is generated in the background; the requester is notified when it’s ready (optionally emailed to recipientEmails). Endpoint: POST /api/v1/ops/checklists/{checklistId}/logs-excel

curl -X POST "https://api.xenia.team/api/v1/ops/checklists/{checklistId}/logs-excel" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmails": ["ops@company.com"],
    "searchString": "",
    "advanceFilters": null,
    "advanceItemFilters": null
  }'

Request Body (all optional):

Field	Type	Default	Description
`recipientEmails`	string[]	`[]`	Emails to send the finished file to (each must be a valid address, else `400`)
`searchString`	string	—	Free-text filter
`advanceFilters`	object	—	Submission-level advanced filter tree
`advanceItemFilters`	object	—	Item-level advanced filter tree
`autoFailed`	boolean	—	Filter by auto-fail state (tri-state)

Response:

{
  "data": {
    "message": "Your report is being generated, you will receive notification once it is ready."
  },
  "meta": {}
}

Spreadsheet Link

Get a ready-to-download spreadsheet of submissions. This one is synchronous — it returns a download URL directly. Endpoint: POST /api/v1/ops/checklists/submissions-spreadsheet

curl -X POST "https://api.xenia.team/api/v1/ops/checklists/submissions-spreadsheet" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "advanceFilters": {
      "checklists": ["template-uuid"],
      "dateRange": ["2024-12-01", "2024-12-31"]
    }
  }'

Request Body:

Field	Type	Description
`advanceFilters`	object	Advanced filter tree scoping which submissions are included

Response:

{
  "data": { "spreadsheetFileDownloadLink": "https://storage.xenia.team/reports/submissions.xlsx" },
  "meta": {}
}

Public PDF

Generate a PDF for a submission whose public report has been enabled. This endpoint is public — it does not use client-key auth. Instead it requires an anonymousid request header, and the submission must have a public URL (public sharing turned on). Endpoint: POST /api/v1/ops/public/submissions/{submissionId}/pdf

curl -X POST "https://api.xenia.team/api/v1/ops/public/submissions/{submissionId}/pdf" \
  -H "anonymousid: <anonymous-id>" \
  -H "Content-Type: application/json"

Response (ready — HTTP 200):

{
  "status": true,
  "code": 200,
  "message": "PDF is ready.",
  "data": { "pdfUrl": "https://storage.xenia.team/reports/submission.pdf", "submissionId": "submission-uuid" }
}

Response (generating — HTTP 202):

{
  "status": true,
  "code": 202,
  "message": "PDF generation in progress. Use the polling endpoint to check status.",
  "data": { "requestIds": ["request-uuid"], "submissionId": "submission-uuid" }
}

Poll for completion with the matching status endpoint (same public auth):

curl -X GET "https://api.xenia.team/api/v1/ops/public/submissions/{submissionId}/pdf-status" \
  -H "anonymousid: <anonymous-id>"

{ "data": { "pdfUrl": "https://storage.xenia.team/reports/submission.pdf", "submissionId": "submission-uuid", "ready": true } }

Submission Records

Pull raw submission records for reporting/BI. Every field is optional; without a date filter it returns all matching submissions (up to a very large default limit — always paginate). Endpoint: POST /api/v1/ops/template-submissions

curl -X POST "https://api.xenia.team/api/v1/ops/template-submissions" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "fromDate": "2024-12-01",
    "toDate": "2024-12-31",
    "checklists": ["template-uuid"],
    "statuses": ["submitted", "Approved"],
    "locations": ["location-uuid"],
    "offset": 0,
    "limit": 500,
    "includeItems": false
  }'

Request Body (all optional):

Field	Type	Default	Description
`fromDate` / `toDate`	string	—	Date range (both required for it to apply)
`checklists`	string[]	—	Filter by template (ChecklistId)
`statuses`	string[]	—	Filter by submission status
`locations`	string[]	—	Filter by location IDs
`users`	string[]	—	Filter by submitter user IDs
`searchText`	string	—	Free-text search
`offset`	number	`0`	Rows to skip
`limit`	number	`1000000`	Page size — always set a real page size
`includeItems`	boolean	`true`	Include submitted item/section answers per record

Response:

{
  "data": [
    {
      "id": "submission-uuid",
      "name": "Daily Safety Inspection",
      "status": "Approved",
      "progress": 100,
      "createdAt": "2024-12-15T10:30:00Z",
      "updatedAt": "2024-12-15T11:00:00Z",
      "ChecklistId": "template-uuid",
      "DefaultLocationId": "location-uuid",
      "Task": { "id": "task-uuid", "taskNumber": 1234, "title": "Daily Safety Inspection" },
      "Checklist": { "id": "template-uuid", "isScoring": true },
      "SubmissionApproval": { "id": "approval-uuid", "status": "Approved", "totalSteps": 1, "currentStep": 1 }
    }
  ],
  "meta": {
    "totalCount": 150,
    "count": {
      "submitted": 120,
      "Pending Approval": 8,
      "Changes Requested": 2,
      "Approved": 18,
      "Rejected": 2,
      "total": 150
    }
  }
}

meta.count is an object (a per-status breakdown), not a number. meta.totalCount is the total number of matching records — page against it using your offset/limit.

Submission Count by Status

Get submission counts grouped by status, with the same filters as submission records. Endpoint: POST /api/v1/ops/submissions-count-by-status

curl -X POST "https://api.xenia.team/api/v1/ops/submissions-count-by-status" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "checklists": ["template-uuid"],
    "fromDate": "2024-12-01",
    "toDate": "2024-12-31",
    "locations": ["location-uuid"]
  }'

Request Body (all optional): checklists, fromDate, toDate, users, lastItemUpdatedBy, statuses, locations, searchText. Response:

{
  "data": {
    "submitted": { "count": 120 },
    "Pending Approval": { "count": 8 },
    "Approved": { "count": 18 },
    "Rejected": { "count": 2 },
    "total": 148
  },
  "meta": {}
}

Submission Attachments

List the photos/videos/files attached across submissions — handy for pulling captured media. Endpoint: POST /api/v1/ops/checklists/logs/attachments

curl -X POST "https://api.xenia.team/api/v1/ops/checklists/logs/attachments" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 0,
    "limit": 20,
    "sortBy": "newest",
    "isPicture": true,
    "isVideo": false,
    "isFile": false
  }'

Request Body (all optional):

Field	Type	Default	Description
`offset`	number	`0`	Rows to skip
`limit`	number	`20`	Page size
`sortBy`	string	`"newest"`	Sort order
`groupBy`	string	—	`"location"` returns media grouped by location
`locationId`	string	—	Filter by a single location
`searchTerm`	string	`""`	Free-text filter
`isPicture` / `isVideo` / `isFile`	boolean	`true`/`false`/`false`	Which media types to include
`advanceFilters` / `globalFilters`	object	—	Advanced filter trees

Response:

{
  "data": {
    "attachments": [ { "url": "https://storage.xenia.team/photo.jpg", "createdAt": "2024-12-15T10:30:00Z" } ],
    "totalLogs": 42,
    "totalAttachments": 130,
    "currentPage": 1,
    "totalPages": 7
  },
  "meta": {}
}

With groupBy: "location" the payload is

{ "data": { "locations": { "<locationId>": { "attachments": [...], "totalAttachments": 12, "page": 1, "totalPages": 1 } } }, "meta": {} }

Common Workflow

Automate a daily report and follow up on results:

#!/bin/bash
CHECKLIST_ID="daily-safety-template-uuid"
TODAY=$(date +%Y-%m-%d)

# 1. Kick off yesterday's Excel export (delivered by notification / email)
curl -s -X POST "https://api.xenia.team/api/v1/ops/checklists/${CHECKLIST_ID}/logs-excel" \
  -H "x-client-key: YOUR_KEY" -H "x-client-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d "{\"recipientEmails\":[\"ops@company.com\"]}"

# 2. Pull the raw records for your own dashboards
curl -s -X POST "https://api.xenia.team/api/v1/ops/template-submissions" \
  -H "x-client-key: YOUR_KEY" -H "x-client-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d "{\"checklists\":[\"${CHECKLIST_ID}\"],\"fromDate\":\"${TODAY}\",\"toDate\":\"${TODAY}\",\"limit\":1000,\"includeItems\":false}" \
  | jq '.data[] | { id, status, DefaultLocationId }'

Best Practices

Use date filters to limit volume

Always specify fromDate/toDate and an explicit limit. The submission-records default limit is very large; unbounded pulls risk hitting the ~60s timeout.

PDF and Excel are asynchronous

The PDF (202) and Excel endpoints return immediately and finish in the background. Wait for the delivery notification / email rather than expecting a file in the HTTP response.

Public links bypass client-key auth

The public PDF endpoint uses an anonymousid header and only works when the submission’s public report is enabled. Enable public sharing sparingly.

Data Extraction & Reporting — analytics, grid reports, scheduled reports, and BI integration
Task Management — read and write tasks and work orders

Getting Started

Workflows

Integrations

Overview

PDF Export

Excel Export

Spreadsheet Link

Public PDF

Submission Records

Submission Count by Status

Submission Attachments

Common Workflow

Best Practices

​Overview

​PDF Export

​Excel Export

​Spreadsheet Link

​Public PDF

​Submission Records

​Submission Count by Status

​Submission Attachments

​Common Workflow

​Best Practices

​Related Guides

Overview

PDF Export

Excel Export

Spreadsheet Link

Public PDF

Submission Records

Submission Count by Status

Submission Attachments

Common Workflow

Best Practices

Related Guides