← Resources

Resource

Generate Reports With The MOS API

Production reporting in MOS gives developers a direct way to retrieve structured report data for tenant workflows, operational monitoring, and downstream analytics. This guide walks through discovering available reports, generating Bank Statement Analysis output, applying filters, and exporting report rows for your own systems.

Use the MOS reporting API when you need machine-readable report data for dashboards, operational exports, or partner workflows. The reporting endpoints return JSON, so your integration can save the raw response, transform it to CSV, or load it into your own reporting system.

This guide focuses on the catalog-driven report flow:

  1. List the reports available to your tenant.
  2. Request data for a report by reportName.
  3. Use the report's column definitions to render or export the rows.

Prerequisites

You need:

  • Your production MOS API base URL.
  • Your tenant id.
  • Your production API credentials.
  • Your client secret.

Keep production credentials and client secrets on your backend or gateway. Do not expose them in browser JavaScript, mobile apps, logs, issue trackers, or client-side configuration.

For the examples below:

export BASE_URL="https://api.example.mos.true.ai/api/v1"
export MOS_API_KEY="<api-key>"
export MOS_TENANT_ID="<tenant-id>"
export MOS_CLIENT_SECRET="<client-secret>"

Your production base URL and credential requirements may differ by tenant configuration. Use the values provided during onboarding.

Step 1: List Available Reports

Call GET /reports to discover which reports are enabled for your tenant.

curl -fsS "$BASE_URL/reports" \
  -H "x-api-key: $MOS_API_KEY" \
  -H "tenant-id: $MOS_TENANT_ID" \
  -H "x-tyk-mos-client-secret: $MOS_CLIENT_SECRET"

The response includes report metadata and column definitions:

{
  "data": [
    {
      "id": "cm-example-report-id",
      "reportName": "Bank Statement Analysis",
      "columnDefinitions": [
        { "key": "loanNumber", "label": "Loan", "type": "text" },
        { "key": "externalLoanId", "label": "External Loan Id", "type": "text" },
        { "key": "bankStatementFileName", "label": "Bank Statement File Name", "type": "text" },
        { "key": "accountNumber", "label": "Account Number", "type": "text" },
        { "key": "depositAmount", "label": "Deposit Amount", "type": "number" },
        { "key": "checksumValidation", "label": "Checksum Validation", "type": "text" },
        { "key": "largeDepositValidation", "label": "Large Deposit Validation", "type": "text" }
      ],
      "active": true
    }
  ]
}

Use reportName as the stable value when requesting report data. Use columnDefinitions to decide column order and labels in your UI or CSV export.

Step 2: Generate Report Data

Call GET /reports/data with the report name. The initial catalog report is Bank Statement Analysis.

curl -fsS "$BASE_URL/reports/data?reportName=Bank%20Statement%20Analysis" \
  -H "x-api-key: $MOS_API_KEY" \
  -H "tenant-id: $MOS_TENANT_ID" \
  -H "x-tyk-mos-client-secret: $MOS_CLIENT_SECRET"

The response body returns rows under data:

{
  "data": [
    {
      "loanNumber": "100001",
      "externalLoanId": "encompass-guid-or-partner-id",
      "loanLink": "/loan/cm-example-loan-id",
      "docLink": "/loan/cm-example-loan-id/extraction/cm-example-document-id",
      "bankStatementFileName": "borrower-bank-statement.pdf",
      "accountNumber": "1234",
      "depositAmount": 2500,
      "depositDescription": "Payroll deposit",
      "checksumValidation": "Valid",
      "largeDepositValidation": "Large Deposits"
    }
  ]
}

Bank Statement Analysis reads Bank Statement documents, account rows, checksum fields, and transaction rows. For each account, MOS returns the largest deposit found for that account and whether it meets the configured large-deposit threshold.

Step 3: Filter By Date Or Loan Number

GET /reports/data supports optional filters:

  • dateFrom: ISO 8601 date or datetime.
  • dateTo: ISO 8601 date or datetime.
  • loanNumbers: comma-separated loan numbers.

Example:

curl -fsS "$BASE_URL/reports/data?reportName=Bank%20Statement%20Analysis&dateFrom=2026-06-01&dateTo=2026-06-30&loanNumbers=100001,100002" \
  -H "x-api-key: $MOS_API_KEY" \
  -H "tenant-id: $MOS_TENANT_ID" \
  -H "x-tyk-mos-client-secret: $MOS_CLIENT_SECRET"

Date-only filters are interpreted as full UTC days. For example, dateFrom=2026-06-01 starts at the beginning of June 1, 2026 UTC, and dateTo=2026-06-30 includes the full UTC day.

Step 4: Export To CSV

If you want a CSV export, pipe the JSON response through jq:

curl -fsS "$BASE_URL/reports/data?reportName=Bank%20Statement%20Analysis&dateFrom=2026-06-01&dateTo=2026-06-30" \
  -H "x-api-key: $MOS_API_KEY" \
  -H "tenant-id: $MOS_TENANT_ID" \
  -H "x-tyk-mos-client-secret: $MOS_CLIENT_SECRET" \
| jq -r '
  ["loanNumber","externalLoanId","bankStatementFileName","accountNumber","depositAmount","depositDescription","checksumValidation","largeDepositValidation"],
  (.data[] | [
    .loanNumber,
    .externalLoanId,
    .bankStatementFileName,
    .accountNumber,
    .depositAmount,
    .depositDescription,
    .checksumValidation,
    .largeDepositValidation
  ])
  | @csv
'

For production jobs, save the raw JSON response first, then transform it. That gives you a replayable source artifact if downstream CSV generation needs to change.

Other Report Endpoints

MOS also exposes direct reporting endpoints that do not use the report catalog.

Loan Processing Metrics

Use GET /reports/loan-processing to measure processing time from source file pickup to document push into Encompass.

curl -fsS "$BASE_URL/reports/loan-processing?dateFrom=2026-06-01&dateTo=2026-06-30&limit=100" \
  -H "x-api-key: $MOS_API_KEY" \
  -H "tenant-id: $MOS_TENANT_ID" \
  -H "x-tyk-mos-client-secret: $MOS_CLIENT_SECRET"

The response includes data.summary, data.rows, and data.meta.nextCursor. If nextCursor is not null, request the next page with cursor=<nextCursor>.

AI Performance Report

Use GET /reports/ai-performance to export document by extraction-field performance rows.

curl -fsS "$BASE_URL/reports/ai-performance?dateFrom=2026-06-01&dateTo=2026-06-30&limit=100" \
  -H "x-api-key: $MOS_API_KEY" \
  -H "tenant-id: $MOS_TENANT_ID" \
  -H "x-tyk-mos-client-secret: $MOS_CLIENT_SECRET"

This endpoint paginates by distinct document, not by returned row count. A single document can return many extraction-field rows. Use meta.nextCursor until it is null.

Integration Notes

  • Treat reportName as case-sensitive.
  • URL-encode report names with spaces, such as Bank%20Statement%20Analysis.
  • Keep production credentials and client secrets server-side.
  • Follow nextCursor for direct report endpoints that return paginated data.
  • Prefer ISO date strings for all date filters.
  • Store MOS loanNumber, externalLoanId, and document links with exported rows so operations teams can trace a report row back to a loan and document.

More Resources

Resource

How MOS classifies documents: confidence thresholds and the processing

A technical walkthrough of the eight-stage processing pipeline&mdash;from SPLITTER through EXPORT&mdash;covering the document status lifecycle, classification and extraction confidence scores, review task triggers, and how to build reliable automation around the analytics event stream.

Read more →
Resource

Setting up Income Clarity

Check which documents are income-eligible, trigger the Candor calculation, poll for results, and re-run after new documents arrive — with a full audit trail of every calculation run available via the history endpoint.

Read more →
Resource

Building the Loan Setup integration

Walk through the complete Loan Setup pipeline — upload source files, poll processingStatus, fetch extracted field data with confidence scores, handle corrections, and monitor per-loan processing events via the analytics timeline endpoint.

Read more →