API Reference

Complete reference for the Talon API. Base URL: https://talonapi.dev

Authentication

Most endpoints require an API key passed via the X-API-Key header. Get your key from the developer dashboard.

Example
curl -H "X-API-Key: tln_live_abc123..." \
  "https://talonapi.dev/api/v1/rules?payer=aetna&cpt=27447"

Key format: Production keys start with tln_live_, sandbox keys with tln_test_.

Free endpoints: /api/v1/health and /api/v1/metrics do not require authentication.

Rate Limits

All authenticated endpoints are rate-limited to 100 requests per minute per API key using a sliding window.

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating when to retry (in seconds).

Credits & Pricing

Talon uses prepaid credits. Purchase credit packs from your dashboard and each API call deducts from your balance.

EndpointCostFree Tier
GET /v1/rules$0.02100/month
GET /v1/rules/payersFreeUnlimited
GET /v1/rules/cpt-codesFreeUnlimited
GET /v1/compare$0.0520/month
GET /v1/metricsFreeUnlimited
POST /v1/appeals/generate$2.005/month

Volume discounts: 10K+ calls/month: 20% off. 100K+: 40% off. 1M+: custom pricing.

Sandbox Mode

API keys starting with tln_test_ operate in sandbox mode. Sandbox requests return realistic fake data, are never rate-limited, and never charge credits.

Use sandbox mode for development and testing. Available sandbox payers: Aetna, Blue Cross Blue Shield, Cigna, Humana, UnitedHealthcare, Kaiser Permanente, Anthem, Molina Healthcare.

Error Format

All errors follow a consistent JSON structure with an error code, message, and optional fix suggestion.

Error response
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or does not exist.",
    "suggestion": "Check that your API key is correct. Keys start with tln_live_ or tln_test_."
  }
}
CodeStatusDescription
invalid_api_key401API key is missing, invalid, or deactivated
insufficient_credits402Not enough credits for this request
not_found404Requested resource not found
validation_error422Missing or invalid parameters
phi_detected422Request contains patient identifiers (appeals only)
rate_limit_exceeded429Too many requests — check Retry-After header
internal_error500Unexpected server error

Endpoints

GET/api/v1/health

Returns API status. No authentication required.

No AuthFree
curl
curl https://talonapi.dev/api/v1/health
JavaScript
const res = await fetch("https://talonapi.dev/api/v1/health");
const data = await res.json();
console.log(data.status); // "ok"
Python
import requests

res = requests.get("https://talonapi.dev/api/v1/health")
print(res.json()["status"])  # "ok"
Response
{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-02-28T12:00:00.000Z"
}

GET/api/v1/rules

Look up payer requirements for a specific CPT code. Returns documentation requirements, blocking rules, approval rates, and denial patterns.

Auth Required$0.02/call
ParameterTypeRequiredDescription
payerstringRequiredPayer name (e.g. "aetna", "unitedhealthcare")
cptstringRequiredCPT procedure code (e.g. "27447")
curl
curl -H "X-API-Key: tln_live_abc123..." \
  "https://talonapi.dev/api/v1/rules?payer=aetna&cpt=27447"
JavaScript
const res = await fetch(
  "https://talonapi.dev/api/v1/rules?payer=aetna&cpt=27447",
  { headers: { "X-API-Key": "tln_live_abc123..." } }
);
const data = await res.json();
console.log(data.approval_rate); // 0.84
Python
import requests

res = requests.get(
    "https://talonapi.dev/api/v1/rules",
    params={"payer": "aetna", "cpt": "27447"},
    headers={"X-API-Key": "tln_live_abc123..."}
)
print(res.json()["approval_rate"])  # 0.84
Response
{
  "payer": "Aetna",
  "cpt_code": "27447",
  "description": "Total Knee Replacement",
  "required_docs": [
    "Clinical notes",
    "Conservative treatment history",
    "Imaging reports"
  ],
  "blocking_requirements": [
    "6+ weeks documented conservative treatment",
    "BMI documented",
    "Functional limitation score"
  ],
  "soft_requirements": [
    "Physical therapy notes",
    "Failed medication list"
  ],
  "typical_turnaround_days": 5,
  "approval_rate": 0.84,
  "common_denial_reasons": [
    {
      "code": "J1",
      "reason": "Insufficient conservative treatment documentation",
      "frequency": 0.34
    }
  ],
  "last_updated": "2026-02-15T00:00:00.000Z"
}

GET/api/v1/rules/payers

List all supported payer names.

Auth RequiredFree
curl
curl -H "X-API-Key: tln_live_abc123..." \
  "https://talonapi.dev/api/v1/rules/payers"
JavaScript
const res = await fetch("https://talonapi.dev/api/v1/rules/payers", {
  headers: { "X-API-Key": "tln_live_abc123..." }
});
const { payers, count } = await res.json();
Python
import requests

res = requests.get(
    "https://talonapi.dev/api/v1/rules/payers",
    headers={"X-API-Key": "tln_live_abc123..."}
)
payers = res.json()["payers"]
Response
{
  "payers": ["Aetna", "Blue Cross Blue Shield", "Cigna", "Humana", "UnitedHealthcare"],
  "count": 5
}

GET/api/v1/rules/cpt-codes

List all supported CPT codes with descriptions.

Auth RequiredFree
curl
curl -H "X-API-Key: tln_live_abc123..." \
  "https://talonapi.dev/api/v1/rules/cpt-codes"
JavaScript
const res = await fetch("https://talonapi.dev/api/v1/rules/cpt-codes", {
  headers: { "X-API-Key": "tln_live_abc123..." }
});
const { cpt_codes } = await res.json();
Python
import requests

res = requests.get(
    "https://talonapi.dev/api/v1/rules/cpt-codes",
    headers={"X-API-Key": "tln_live_abc123..."}
)
codes = res.json()["cpt_codes"]
Response
{
  "cpt_codes": [
    { "cpt_code": "27447", "description": "Total Knee Replacement" },
    { "cpt_code": "29881", "description": "Knee Arthroscopy with Meniscectomy" },
    { "cpt_code": "63030", "description": "Lumbar Discectomy" }
  ],
  "count": 3
}

GET/api/v1/compare

Compare approval rates across all payers for a specific CPT code.

Auth Required$0.05/call
ParameterTypeRequiredDescription
cptstringRequiredCPT procedure code (e.g. "27447")
curl
curl -H "X-API-Key: tln_live_abc123..." \
  "https://talonapi.dev/api/v1/compare?cpt=27447"
JavaScript
const res = await fetch(
  "https://talonapi.dev/api/v1/compare?cpt=27447",
  { headers: { "X-API-Key": "tln_live_abc123..." } }
);
const { payers } = await res.json();
Python
import requests

res = requests.get(
    "https://talonapi.dev/api/v1/compare",
    params={"cpt": "27447"},
    headers={"X-API-Key": "tln_live_abc123..."}
)
payers = res.json()["payers"]
Response
{
  "cpt_code": "27447",
  "payers": [
    { "payer": "Aetna", "approval_rate": 0.84 },
    { "payer": "UnitedHealthcare", "approval_rate": 0.78 },
    { "payer": "Cigna", "approval_rate": 0.81 }
  ],
  "count": 3
}

GET/api/v1/metrics

CMS-mandated payer prior authorization metrics. Public data, no authentication required, no credits charged.

No AuthFree
ParameterTypeRequiredDescription
payerstringOptionalFilter by payer name (partial match, case-insensitive)
curl
curl "https://talonapi.dev/api/v1/metrics?payer=aetna"
JavaScript
const res = await fetch("https://talonapi.dev/api/v1/metrics?payer=aetna");
const { metrics } = await res.json();
Python
import requests

res = requests.get(
    "https://talonapi.dev/api/v1/metrics",
    params={"payer": "aetna"}
)
metrics = res.json()["metrics"]
Response
{
  "metrics": [
    {
      "payer_name": "Aetna",
      "reporting_year": 2025,
      "pct_approved_standard": 85.3,
      "pct_denied_standard": 14.7,
      "pct_approved_after_appeal": 42.1,
      "avg_days_to_decision": 4.8,
      "source_url": "https://www.aetna.com/about-us/prior-authorization-metrics.html",
      "scraped_at": "2026-02-28T00:00:00.000Z"
    }
  ],
  "count": 1
}

POST/api/v1/appeals/generate

Generate an AI-powered appeal letter for a denied prior authorization. Uses historical denial pattern data for context.

Auth Required$2.00/call

PHI Policy: The clinical_summary must be de-identified. Requests containing patient names, dates of birth, SSNs, or member IDs will be rejected with a phi_detected error.

ParameterTypeRequiredDescription
payerstringRequiredPayer name (e.g. "UnitedHealthcare")
cpt_codestringRequiredCPT code of the denied procedure
denial_reasonstringRequiredReason for denial from the payer
denial_codestringOptionalPayer denial code (e.g. "J1")
clinical_summarystringRequiredDe-identified clinical summary
curl
curl -X POST "https://talonapi.dev/api/v1/appeals/generate" \
  -H "X-API-Key: tln_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "payer": "UnitedHealthcare",
    "cpt_code": "27447",
    "denial_reason": "Insufficient documentation of conservative treatment",
    "denial_code": "J1",
    "clinical_summary": "Patient is 67yo female with severe bilateral knee OA, Kellgren-Lawrence Grade IV. Failed 6 months PT, NSAIDs, and corticosteroid injections."
  }'
JavaScript
const res = await fetch("https://talonapi.dev/api/v1/appeals/generate", {
  method: "POST",
  headers: {
    "X-API-Key": "tln_live_abc123...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    payer: "UnitedHealthcare",
    cpt_code: "27447",
    denial_reason: "Insufficient documentation of conservative treatment",
    denial_code: "J1",
    clinical_summary: "Patient is 67yo female with severe bilateral knee OA..."
  })
});
const data = await res.json();
Python
import requests

res = requests.post(
    "https://talonapi.dev/api/v1/appeals/generate",
    headers={"X-API-Key": "tln_live_abc123..."},
    json={
        "payer": "UnitedHealthcare",
        "cpt_code": "27447",
        "denial_reason": "Insufficient documentation of conservative treatment",
        "denial_code": "J1",
        "clinical_summary": "Patient is 67yo female with severe bilateral knee OA..."
    }
)
letter = res.json()["appeal_letter"]
Response
{
  "appeal_letter": "Dear Medical Director, I am writing to appeal the denial...",
  "key_arguments": [
    "6 months PT documented",
    "Failed NSAID therapy",
    "Kellgren-Lawrence Grade IV"
  ],
  "success_probability": 0.72,
  "confidence": "medium",
  "based_on": 43
}