API Reference — ClearCycle Developer Docs

Overview

The ClearCycle REST API lets you embed claim intelligence into your existing hospital information system (HIS) or billing software. The primary use case is pre-submission risk scoring: before sending a claim to a TPA portal, your system calls /claims/pre-check and receives a per-line deduction probability, expected INR deduction, and suggested corrective action.

Authentication

Bearer JWT

Content-Type

application/json

Response format

JSON

Authentication

Every API request must include a short-lived JWT in the Authorization header. Obtain a token by posting your credentials to POST /auth/login. Tokens expire after 24 hours.

curl -X POST https://api.clearcycle.in/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "billing@yourhospital.com",
    "password": "••••••••"
  }'

Security note: Never expose your credentials in client-side code. Always call the API from your backend and forward only what the frontend needs.

Pre-check

POST/claims/pre-check

Score every line item of a draft claim against a payer's behavioural profile. Returns per-line deduction probability, expected INR deduction, risk tier, plain-English rejection reasons, and a suggested corrective action. No claim is created or stored — this is a stateless scoring call.

curl -X POST https://api.clearcycle.in/claims/pre-check \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_id": "star_health",
    "claim_lines": [
      {
        "line_id": "L1",
        "procedure_code": "27447",
        "diagnosis_codes": ["M17.11"],
        "revenue_category": "procedure",
        "line_amount": 85000,
        "pre_auth_present": true
      },
      {
        "line_id": "L2",
        "procedure_code": "99232",
        "diagnosis_codes": ["M17.11"],
        "revenue_category": "inpatient",
        "line_amount": 18000,
        "pre_auth_present": false
      }
    ]
  }'

Response

{
  "hospital_id": "hosp_abc123",
  "payer_id": "star_health",
  "model_version": "pretrain:2025-09-14",
  "lines": [
    {
      "line_id": "L1",
      "deduction_probability": 0.78,
      "expected_deduction_amount": 21250.0,
      "risk_level": "high",
      "top_reasons": [
        "Implant-only CPT without attached invoice",
        "Missing pre-auth reference number"
      ],
      "suggested_action": "Attach implant invoice and pre-auth approval before submission"
    },
    {
      "line_id": "L2",
      "deduction_probability": 0.42,
      "expected_deduction_amount": 7560.0,
      "risk_level": "medium",
      "top_reasons": [
        "Room upgrade — policy covers standard ward only"
      ],
      "suggested_action": "Split room charges: standard ward vs upgrade differential"
    }
  ],
  "summary": {
    "total_lines": 2,
    "high_risk_lines": 1,
    "medium_risk_lines": 1,
    "low_risk_lines": 0,
    "total_billed_amount": 103000.0,
    "total_expected_deduction": 28810.0,
    "expected_collection_rate": 0.7203,
    "payer_history_available": true
  }
}

Request schema

Top-level body

payer_idstringrequired

Insurer or TPA identifier. See supported payer IDs.

claim_linesClaimLine[]required

One or more claim lines to score. Minimum 1 item.

ClaimLine object

line_idstringrequired

Your identifier for this line. Returned unchanged in the response so you can match results back to your records.

procedure_codestringrequired

HCPCS or CPT code for the procedure (e.g. 27447).

diagnosis_codesstring[]

ICD-10 codes for this line. First element is used as primary diagnosis. Defaults to [].

revenue_categorystring

Billing category. One of: procedureconsumabledruginpatientoutpatientdmeother. Defaults to unknown.

line_amountnumberrequired

Billed amount in INR. Must be ≥ 0.

pre_auth_presentboolean

Whether pre-authorisation is on file for this line. Defaults to false.

Response schema

Top-level response

hospital_idstring

Your hospital's identifier, derived from the bearer token.

payer_idstring

Echoes the payer_id from the request.

model_versionstring

Identifies the model used: pretrain:YYYY-MM-DD for the pre-trained model, or a timestamp if your hospital model has been fine-tuned.

linesLineResult[]

One result per input claim line, in the same order.

summarySummary

Aggregate stats across all lines.

LineResult object

line_idstring

Matches the line_id you sent.

deduction_probabilitynumber

Probability of a deduction for this line (0.0–1.0). Multiply by 100 for a percentage.

expected_deduction_amountnumber

Expected INR amount that will be deducted, rounded to 2 decimal places.

risk_levelstring

low (<30%), medium (30–55%), or high (>55%).

top_reasonsstring[]

Plain-English reasons the model flags for deduction risk. Empty for low-risk lines.

suggested_actionstring

Recommended corrective action to reduce deduction risk before submission.

Summary object

total_linesnumber

Total lines scored.

high_risk_linesnumber

Count of high-risk lines.

medium_risk_linesnumber

Count of medium-risk lines.

low_risk_linesnumber

Count of low-risk lines.

total_billed_amountnumber

Sum of all line amounts (INR).

total_expected_deductionnumber

Sum of expected deductions across all lines (INR).

expected_collection_ratenumber

Fraction of billed amount expected to be collected (0.0–1.0).

payer_history_availableboolean

Whether your hospital has historical persona data for this payer. When false, the model uses pre-trained weights only.

Supported payer IDs

Pass one of the following values as payer_id. Additional insurers are added on request.

payer_id	Insurer / TPA	Type
`star_health`	Star Health and Allied Insurance	Insurer
`icici_lombard`	ICICI Lombard General Insurance	Insurer
`sbi_general`	SBI General Insurance	Insurer
`bajaj_allianz`	Bajaj Allianz General Insurance	Insurer
`tata_aig`	Tata AIG General Insurance	Insurer
`medi_assist`	Medi Assist India TPA	TPA
`health_india`	Health India TPA Services	TPA
`induslnd`	IndusInd TPA	TPA

Error codes

All errors return a JSON body with a detail field describing the problem.

Status	Meaning
401	Missing or expired bearer token
403	Token valid but hospital not authorised for this resource
422	Request body failed validation — check field types and required fields
503	Payer intelligence model unavailable (cold start or missing model file)
500	Unexpected server error — contact support with the request ID

Code examples

Full end-to-end examples for common languages. Replace credentials with your actual values.

Python

import requests

BASE_URL = "https://api.clearcycle.in"

# 1. Authenticate
resp = requests.post(f"{BASE_URL}/auth/login", json={
    "email": "billing@yourhospital.com",
    "password": "your_password",
})
token = resp.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# 2. Score claim lines before submission
payload = {
    "payer_id": "star_health",
    "claim_lines": [
        {
            "line_id": "L1",
            "procedure_code": "27447",
            "diagnosis_codes": ["M17.11"],
            "revenue_category": "procedure",
            "line_amount": 85000,
            "pre_auth_present": True,
        },
    ],
}

result = requests.post(
    f"{BASE_URL}/claims/pre-check",
    json=payload,
    headers=headers,
)
data = result.json()

for line in data["lines"]:
    print(f"{line['line_id']}: {line['risk_level'].upper()} "
          f"({line['deduction_probability']:.0%} deduction risk)")
    print(f"  Expected deduction: ₹{line['expected_deduction_amount']:,.0f}")
    for reason in line["top_reasons"]:
        print(f"  · {reason}")

Node.js (fetch)

const BASE_URL = "https://api.clearcycle.in";

// 1. Authenticate
const loginRes = await fetch(`${BASE_URL}/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "billing@yourhospital.com",
    password: "your_password",
  }),
});
const { access_token } = await loginRes.json();

// 2. Score claim lines
const res = await fetch(`${BASE_URL}/claims/pre-check`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payer_id: "star_health",
    claim_lines: [
      {
        line_id: "L1",
        procedure_code: "27447",
        diagnosis_codes: ["M17.11"],
        revenue_category: "procedure",
        line_amount: 85000,
        pre_auth_present: true,
      },
    ],
  }),
});

const data = await res.json();
console.log(`Expected deduction: ₹${data.summary.total_expected_deduction.toLocaleString("en-IN")}`);
console.log(`Collection rate: ${(data.summary.expected_collection_rate * 100).toFixed(1)}%`);

Need help integrating?

We provide a 2-hour technical onboarding call for all pilot hospitals. Our team can walk through your HIS architecture and set up the integration for you.

Book an integration call →