> ## Documentation Index
> Fetch the complete documentation index at: https://claimsdesk-871aefc7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Welcome to the Claims Desk API documentation and integration reference.

> [!NOTE]
>
> **Demo Environment Notice**: This public API reference represents a demonstration deployment of ClaimsDesk. The solution is architected and built to be deployed **on-premises** within the client's private infrastructure rather than as a multi-tenant public SaaS application.

## Overview

The **ClaimsDesk API** provides a complete suite of enterprise RESTful services powering:

* **Web Portals**: Claims adjusters, underwriters, branch supervisors, and administrative operational consoles.
* **Mobile Applications**: Field staff, loss assessors, investigators, and member self-service mobile portals.
* **Third-Party Vendors & Integration Partners**: External automotive repair facilities, medical assessment panels, legal partners, and core insurance enterprise systems.

All endpoints adhere strictly to REST principles, accepting and returning standard JSON payloads with comprehensive validation, status codes, and deterministic error structures.

***

## Base URL & Interactive Testing

The API server target for this demonstration is:

```http theme={null}
http://claimsdesk.runasp.net/api/v1
```

All requests in the documentation's interactive playground can be executed directly against this endpoint.

***

## Authentication & Security

ClaimsDesk supports multi-tier authentication depending on the client consumer:

### 1. Staff & Customer JWT Bearer Tokens

User sessions initiated through web portals and mobile applications utilize JWT Bearer tokens:

```http theme={null}
Authorization: Bearer <jwt-token>
```

Authentication and session lifecycle operations are located under **Authentication & Identity**, supporting username/password logins, customer portal logins, and full **Two-Factor Authentication (2FA)** via Authenticator Apps (TOTP), SMS, or Email OTP verification.

### 2. Tenant Machine-to-Machine Integration (API Keys)

External vendors, microservices, and automated partner systems authenticate via dedicated HTTP headers:

```http theme={null}
X-App-Id: <your-application-id>
X-Api-Key: <your-secret-api-key>
```

> **Interactive API Playground**
>
> Test every request directly within this documentation using the built-in request runner.

> **Role-Based Security & Approvals**
>
> Fine-grained role permissions, operational scopes, and configurable approval limits applied to all claims and actions.

***

## Logical API Domains

The API reference covers **131 distinct operations** across **24 backend controllers**, organized into the following 11 logical enterprise domains:

1. **Authentication & Identity**: Staff login, customer portal login, 2FA challenge/setup/verification, profile management, and session logout (`AuthController`).
2. **Claims Management**: First Notice of Loss (FNOL) submission, claim adjustments, loss investigations, claims approval flow, and claim deletion/withdrawal (`ClaimsController`).
3. **Workflow Automation**: Dynamic state machine definitions, stage transitions, rule duplicating, execution instance tracking, pause/resume, and execution audit logs (`WorkflowsController`, `WorkflowInstancesController`).
4. **Insurance & Underwriting**: Complete insurance policy lifecycle management, entitlement and coverage status verification, and premium contribution payment receipts (`PoliciesController`, `PolicyContributionsController`).
5. **Policyholders & Members**: Customer master records, policyholder profiles, covered members, dependents, and beneficiary allocations (`CustomersController`, `MembersController`).
6. **Tenants & Multi-Branch**: Multi-tenant organization boundaries, corporate structures, and regional branch office management (`OrganizationsController`, `BranchesController`).
7. **User & Access Management**: Internal staff user administration, system role tiers (Roles 1–6), platform permissions, and capability assignment matrices (`UsersController`, `RolesController`, `PermissionsController`, `RolePermissionsController`).
8. **Subscriptions & Licensing**: SaaS/on-prem subscription tiers, organization license quota allocations, and individual user seat licensing (`SubscriptionsController`, `LicensePoolsController`, `UserLicensesController`).
9. **Communications & Alerts**: Real-time user notification inboxes, unread counters, transactional email dispatch (SMTP), and SMS notifications via Africa's Talking gateway (`NotificationsController`, `EmailsController`, `SmsController`).
10. **Analytics & Reporting**: Parameterized report calculations, live dataset previews without persisting, batch report generation, and formatted exports in PDF and Excel/CSV (`ReportsController`).
11. **Configuration & System**: Enterprise system configuration keys, user preferences, batch setting updates, machine integration keys, and regulatory audit trail logs (`SettingsController`, `ApiKeysController`, `AuditTrailsController`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.