Settlement API Documentation

Getting Started

The Settlement API lets you integrate settlement matching into your app. It analyzes 100+ active class action settlements against a user's profile and evidence to find eligible matches, then optionally auto-fills claim forms using AI.

Get an API key: Email api@claimr.pro with your use case to request access.

Authentication

All requests require an API key passed via the Authorization header:

curl https://claimr.pro/api/v1/settlements \
  -H "Authorization: Bearer sk_live_your_key_here"
      

You can also use the x-api-key header as an alternative.

Rate Limits

Endpoint	Free Tier	Pro Tier
List settlements	100/hour	1,000/hour
Match settlements	20/hour	100/hour
Auto-file claims	Not available	50/hour

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.

Endpoints

GET /api/v1/settlements List active settlements

Returns all active class action settlements, with optional filtering and pagination.

Query Parameters

Parameter	Type	Default	Description
`status`	string	`active`	`active`, `urgent`, or `all`
`category`	string	—	Filter by category (e.g. `data-breach`, `antitrust`)
`limit`	integer	`50`	Results per page (1–200)
`offset`	integer	`0`	Pagination offset

Example Response

{
  "ok": true,
  "data": {
    "settlements": [
      {
        "title": "Wells Fargo & Company — $33M Settlement",
        "deadline": "2026-04-15",
        "amount": "$33.0M",
        "status": "active",
        "claimUrl": "https://...",
        "type": "Consumer"
      }
    ],
    "pagination": { "total": 121, "limit": 50, "offset": 0, "hasMore": true },
    "metadata": { "lastUpdated": "2026-03-08T...", "sources": ["pacer-rss", "classaction.org"] }
  },
  "requestId": "req_a1b2c3...",
  "meta": { "timestamp": "...", "version": "v1" }
}
          

POST /api/v1/settlements/match Match user to eligible settlements

Analyzes all active settlements against a user's profile and evidence using AI. Returns matches with confidence scores and reasoning.

Request Body

Field	Type	Required	Description
`profile.name`	string	*	User's full name
`profile.email`	string	*	User's email (* at least name or email required)
`profile.phone`	string		Phone number
`profile.city`	string		City
`profile.state`	string		State (2-letter code)
`profile.zip`	string		ZIP code
`profile.services`	string[]		Companies the user is a customer of (e.g. `["T-Mobile", "Wells Fargo"]`)
`evidence`	array		Up to 10 evidence images (base64)
`evidence[].data`	string		Base64-encoded image
`evidence[].mediaType`	string		`image/jpeg`, `image/png`, or `image/webp`
`evidence[].label`	string		Description (e.g. "AT&T bill Jan 2025")

Example Request

curl -X POST https://claimr.pro/api/v1/settlements/match \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "state": "CA",
      "city": "Los Angeles",
      "services": ["T-Mobile", "Wells Fargo", "Amazon"]
    }
  }'
          

Example Response

{
  "ok": true,
  "data": {
    "matches": [
      {
        "settlement": { "title": "Wells Fargo — $33M Settlement", ... },
        "confidence": "high",
        "reasoning": "User self-reported as Wells Fargo customer.",
        "eligibilityFactors": ["customer_self_reported"]
      }
    ],
    "totalAnalyzed": 121,
    "evidenceProcessed": 0
  }
}
          

This endpoint uses AI analysis and may take 10–30 seconds to respond.

POST /api/v1/settlements/auto-file PRO Auto-fill a claim form

Opens a settlement claim URL in a headless browser, uses AI vision to detect form fields, and auto-fills them with the user's information. Returns a screenshot of the filled form.

Request Body

Field	Type	Required	Description
`claimUrl`	string	Yes	URL of the claim form
`userInfo.name`	string	*	Full name (* at least name or email)
`userInfo.email`	string	*	Email address
`userInfo.phone`	string		Phone number
`userInfo.address`	string		Full address
`userInfo.city`	string		City
`userInfo.state`	string		State
`userInfo.zip`	string		ZIP code
`settlementContext`	object		Context for eligibility questions (from match endpoint)
`evidence`	array		Up to 5 evidence images
`action`	string		`fill` (default) or `submit`

Example Response

{
  "ok": true,
  "data": {
    "success": true,
    "screenshot": "base64-encoded JPEG of the filled form",
    "actions": [
      { "selector": "#firstName", "value": "Jane", "status": "filled" }
    ],
    "pageTitle": "Settlement Claim Form",
    "pageUrl": "https://..."
  }
}
          

This endpoint launches a headless browser and may take 30–60 seconds. Pro plan required.

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Key lacks required permission
`PLAN_REQUIRED`	403	Endpoint requires Pro tier
`RATE_LIMITED`	429	Rate limit exceeded
`VALIDATION_ERROR`	400	Invalid request body or parameters
`INTERNAL_ERROR`	500	Unexpected server error

All errors include an ok: false envelope with error.code, error.message, and a requestId for support.

Code Examples

JavaScript

const resp = await fetch('https://claimr.pro/api/v1/settlements/match', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    profile: {
      name: 'Jane Smith',
      email: 'jane@example.com',
      state: 'CA',
      services: ['T-Mobile', 'Amazon'],
    },
  }),
});

const { data } = await resp.json();
console.log(`Found ${data.matches.length} eligible settlements`);
      

Python

import requests

resp = requests.post(
    "https://claimr.pro/api/v1/settlements/match",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "profile": {
            "name": "Jane Smith",
            "state": "CA",
            "services": ["T-Mobile", "Amazon"],
        }
    },
)

data = resp.json()["data"]
print(f"Found {len(data['matches'])} eligible settlements")
      

Try It

Your API Key