Name: Claims Readiness API: Insurance Claim Completeness Check
Brand: kaps-codes-2
SKU: api-kaps-codes-2-claims-readiness-api
Availability: InStock
Author: API Market

Kapil Aryan

# Claims Readiness API

## Overview

The Claims Readiness API checks whether an insurance claim submission is complete before it goes to a claims handler. You send the claim's details and the list of documents received, and `POST /v1/claims/validate` returns a status, the required fields and documents that are missing, warnings, and a validation ID you can look up later. It has 6 endpoints: claim validation, validation lookup, the list of rule sets, usage, service info and a health check.

It is built for insurers, third-party administrators, brokers and claims intake software that want to catch missing paperwork early and route only complete claims to review. It checks completeness only: it does not approve, price or detect fraud in a claim. The rule sets returned today are demo rules for motor and health claims. In our test a motor claim with a claim form, policy copy and repair estimate came back as `ready_for_review` with nothing missing in about 1.2 seconds.

## Features

*   **6 endpoints**: Validate a claim, fetch a validation, list rule sets, usage, service info and health.
*   **Missing items**: Lists missing required fields and missing documents separately.
*   **Claim types**: Rule sets for `motor` and `health` claims.
*   **Stored results**: Each validation gets a `validation_id` you can fetch again.
*   **Clear scope**: Every result states it is a completeness check, not an insurance decision.
*   **Rate limit**: 2 requests per second on every plan.

## Use Cases

*   **Claims intake**: Check a new claim on submission and ask the claimant for missing documents.
*   **Triage**: Send only complete claims to a claims handler.
*   **Broker portals**: Show brokers what is missing before they submit.
*   **Audit trails**: Store the `validation_id` with each claim.
*   **Process metrics**: Track how many claims arrive incomplete.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/kaps-codes-2/claims-readiness-api
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Validate a claim

Checks one claim against the rule set for its `claim_type` and returns what is missing.

**Method:** `POST`

**Endpoint:** `/v1/claims/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `claim_id` | body | Your reference for the claim. | string | Yes | - | - |
| `claim_type` | body | Claim type: `motor` or `health`. | string | Yes | - | - |
| `incident_date` | body | Date of the incident (YYYY-MM-DD). | string | Yes | - | - |
| `submission_date` | body | Date the claim was submitted (YYYY-MM-DD). | string | Yes | - | - |
| `policy_reference` | body | Policy number or reference. | string | Yes | - | - |
| `documents` | body | Documents received, each with `type` and `received`. | array | No | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/kaps-codes-2/claims-readiness-api/v1/claims/validate" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "claim_id": "DEMO-1002",
    "claim_type": "motor",
    "incident_date": "2026-10-01",
    "submission_date": "2026-10-10",
    "policy_reference": "POLICY-DEMO-55",
    "documents": [
      { "type": "claim_form", "received": true },
      { "type": "policy_copy", "received": true },
      { "type": "repair_estimate", "received": true }
    ]
  }'
```

**Example Response (200 OK):**

```json
{
  "claim_id": "DEMO-1002",
  "rule_set_id": "demo_motor_v1",
  "rule_version": "1.0.0",
  "status": "ready_for_review",
  "missing_fields": [],
  "missing_documents": [],
  "warnings": [],
  "decision_note": "Completeness checks only; not an insurance approval, coverage, payout, or fraud decision.",
  "validation_id": "8f7d3b63-fc43-447a-9bd5-d5d5611a1d80"
}
```

#### 2. Get a validation

Returns a stored validation by the ID that `POST /v1/claims/validate` returned.

**Method:** `GET`

**Endpoint:** `/v1/validations/{validation_id}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `validation_id` | path | ID returned by `POST /v1/claims/validate`. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/kaps-codes-2/claims-readiness-api/v1/validations/8f7d3b63-fc43-447a-9bd5-d5d5611a1d80" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "validation_id": "8f7d3b63-fc43-447a-9bd5-d5d5611a1d80",
  "claim_id": "DEMO-1002",
  "rule_set_id": "demo_motor_v1",
  "rule_version": "1.0.0",
  "status": "ready_for_review",
  "created_at": "2026-10-24 12:19:18"
}
```

#### 3. List rule sets

Returns the rule sets you can validate against.

**Method:** `GET`

**Endpoint:** `/v1/rules`

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/kaps-codes-2/claims-readiness-api/v1/rules" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "rules": [
    { "claim_type": "health", "rule_set_id": "demo_health_v1", "version": "1.0.0", "description": "Synthetic demo rules only; replace with customer-approved checklist." },
    { "claim_type": "motor", "rule_set_id": "demo_motor_v1", "version": "1.0.0", "description": "Synthetic demo rules only; replace with customer-approved checklist." }
  ]
}
```

#### 4. Usage

Returns usage recorded by the provider's backend. Your API.market plan allowance is shown in your API.market dashboard.

**Method:** `GET`

**Endpoint:** `/v1/usage`

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/kaps-codes-2/claims-readiness-api/v1/usage" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "usage_scope": "backend_tenant",
  "tenant_id": "pilot-demo",
  "used_this_month": 23,
  "quota_enforced_by_backend": false,
  "message": "Backend usage only. Your marketplace subscription allowance and remaining units are managed by your API marketplace."
}
```

#### 5. Service info

**Method:** `GET`

**Endpoint:** `/`

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/kaps-codes-2/claims-readiness-api/" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "service": "Claims Readiness API",
  "version": "2.2.0",
  "status": "running",
  "scope": "Completeness checks only"
}
```

#### 6. Health check

**Method:** `GET`

**Endpoint:** `/health`

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/kaps-codes-2/claims-readiness-api/health" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "status": "ok"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded. |
| 400 | Bad Request | The body is not valid JSON. |
| 401 | Unauthorized | The `x-api-market-key` header is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | No validation exists with that ID (`validation_not_found`), or the path does not exist. |
| 422 | Unprocessable Entity | A required field is missing or has the wrong format. |
| 429 | Too Many Requests | You sent more than 2 requests per second, or you used all 100 calls of the Free plan. |
| 500 | Internal Server Error | Something failed on the provider side. Retry after a short delay. |

## Rate Limits

Every plan allows 2 requests per second. The Free plan includes 100 calls in total over a 7-day trial, Pro 1,000 calls a month, Pro+ 2,500 and Enterprise 15,000. Free, Pro and Pro+ limits are hard, so requests past the limit return `429 Too Many Requests`; Enterprise bills each extra call at $0.05. Back off before retrying and honour any `Retry-After` header.

## FAQ

**Does it approve or reject claims?**

No. It checks whether the claim has the required fields and documents. The `decision_note` in every response says so.

**Which claim types are supported?**

`motor` and `health`. Call `/v1/rules` to see the current rule sets.

**Are the rules final?**

The current rule sets are demo rules. Contact the provider through the chat if you need a checklist that matches your own process.

**Can I look a result up later?**

Yes. Store the `validation_id` and call `/v1/validations/{validation_id}`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Check insurance claim submissions for missing fields and documents before review. Motor and health rule sets, stored results, JSON responses.

Claims Readiness API: Insurance Claim Completeness Check

Free