API Documentation

The Sheltr Claims Engine API lets you submit product protection claims, get AI-powered damage assessments, fraud detection scoring, and auto-approve/deny decisions in seconds.

Overview

Base URL: https://sheltr-crsk.polsia.app

All request and response bodies are JSON. Include Content-Type: application/json in your headers.

Authentication

API endpoints require your merchant API key. Pass it as:

X-API-Key: sk_sheltr_your_api_key_here

Or as a Bearer token:

Authorization: Bearer sk_sheltr_your_api_key_here

Quick Start

Submit your first claim in 3 steps:

# 1. Register your merchant account
curl -X POST https://sheltr-crsk.polsia.app/api/merchants/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"secure123","company_name":"Acme"}'

# 2. Save your API key from the response

# 3. Submit a claim
curl -X POST https://sheltr-crsk.polsia.app/api/claims \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_sheltr_YOUR_KEY" \
  -d '{
    "customer_email": "customer@email.com",
    "damage_photo_url": "https://example.com/photo.jpg",
    "damage_description": "Screen cracked after drop",
    "purchase_price": 299.99
  }'

Register Merchant

POST /api/merchants/register
Create a new merchant account. Returns an API key for authenticating future requests.

Request Body

FieldTypeRequiredDescription
emailstringYesMerchant email address
passwordstringYesAccount password
company_namestringYesBusiness name

Login

POST /api/merchants/login
Log in and retrieve your API key.

Update Settings

PUT /api/merchants/settings
Adjust AI decision thresholds for your account.
Auth: X-Session-Token

Request Body

FieldTypeDefaultDescription
auto_approve_below_scorenumber0.30Claims with fraud score below this are auto-approved
auto_deny_above_scorenumber0.80Claims with fraud score above this are auto-denied
max_auto_approve_valuenumber500Maximum $ value for auto-approval
require_photobooleantrueRequire damage photo for claims

Submit Claim

POST /api/claims
Submit a product protection claim for AI assessment. Returns damage analysis, fraud score, decision, and next steps.
Auth: X-API-Key

Request Body

FieldTypeRequiredDescription
customer_emailstringYesCustomer's email address
damage_photo_urlstring*URL of damage photo (* required if merchant requires photo)
damage_descriptionstringNoCustomer's description of the damage
customer_namestringNoCustomer's name
product_idintegerNoSheltr product ID
product_external_idstringNoYour system's product ID
purchase_datedateNoDate of purchase (ISO 8601)
purchase_pricenumberNoOriginal purchase price

Response

{
  "claim": {
    "id": 1,
    "claim_number": "SH-M1K2N3-A4B5C6",
    "status": "approved"
  },
  "assessment": {
    "damage_type": "screen_crack",
    "damage_severity": "severe",
    "confidence": 0.92,
    "description": "Visible spider-web crack pattern on phone screen..."
  },
  "fraud": {
    "score": 0.1,
    "signals": []
  },
  "decision": {
    "result": "approved",
    "reasoning": "Auto-approved: Low fraud risk, damage confirmed...",
    "resolution": "repair"
  },
  "next_steps": [
    "Repair center will be assigned within 24 hours",
    "Customer will receive shipping label via email"
  ]
}

List Claims

GET /api/claims
List all claims for your merchant account. Supports filtering by status.
Auth: X-API-Key

Query Parameters

ParamTypeDescription
statusstringFilter: approved, denied, review, pending
limitintegerResults per page (default 50)
offsetintegerSkip N results for pagination

Get Claim Details

GET /api/claims/:id
Get full details for a specific claim. Can use claim ID or claim number.
Auth: X-API-Key

Override Decision

PUT /api/claims/:id/decision
Manually override the AI decision for a claim. Useful for claims flagged for review.
Auth: X-API-Key

Request Body

FieldTypeRequiredDescription
decisionstringYes"approved" or "denied"
resolution_typestringNo"repair", "replacement", or "refund"
reasoningstringNoReason for the override

Create Product

POST /api/products
Register a product for warranty tracking. Use external_id to sync with your system.
Auth: X-API-Key

List Products

GET /api/products
List all registered products for your merchant account.
Auth: X-API-Key