SecondAppraisal Total-Loss Intake

Submit a vehicle owner's total-loss situation to SecondAppraisal on their behalf. Minimum: one of customer.phone / customer.email, your `agent` self-identification, and a `consent.attestation`. Returns a receipt with `customer_confirmation_url` (one tap confirms), a relayable `customer_message`, an optional `preliminary` market read, `contact_policy` (we will email/text a welcome and a person will call to confirm the request came from the customer or their agent), and `pricing` — the consultation is free; if the owner wants more, Appraisal Research is $199 (paid up front, no guarantee) or Appraisal Research + Negotiation is $495 with a $25 discount for customers you send ($470; a card HOLD captured only after the settlement improves by $1,000+, otherwise nothing is charged). The $25 applies to representation only. You may quote `pricing` verbatim; payment always happens on our site by the customer's own click (`checkout` links appear once they have confirmed) — never collect card details. Read `customer_message` to the user verbatim.

{
  "type": "object",
  "properties": {
    "agent": {
      "type": "object",
      "properties": {
        "name": {
          "allOf": [
            {
              "type": "string",
              "maxLength": 120
            },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            }
          ],
          "description": "Human-readable name of the agent or product submitting on the customer's behalf (e.g. \"OpenClaw\", \"Acme Claims Copilot\"). Shown to the customer."
        },
        "platform": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]{0,59}$",
          "description": "Platform slug for attribution. Known values: openclaw, chatgpt, claude, gemini, copilot, perplexity, custom. Any lowercase slug is accepted."
        },
        "version": {
          "type": "string",
          "minLength": 1,
          "maxLength": 60,
          "description": "Agent / integration version string."
        },
        "operator_url": {
          "type": "string",
          "format": "uri",
          "maxLength": 300,
          "description": "Homepage or documentation URL of the agent operator."
        }
      },
      "required": [
        "name",
        "platform"
      ],
      "additionalProperties": false,
      "description": "Who is calling. Required — an intake without self-identification is refused."
    },
    "customer": {
      "type": "object",
      "properties": {
        "first_name": {
          "allOf": [
            {
              "type": "string",
              "maxLength": 80
            },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            }
          ]
        },
        "last_name": {
          "allOf": [
            {
              "type": "string",
              "maxLength": 80
            },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            }
          ]
        },
        "email": {
          "type": "string",
          "format": "email",
          "maxLength": 254,
          "description": "Customer email address."
        },
        "phone": {
          "allOf": [
            {
              "type": "string"
            },
            {
              "type": "string",
              "pattern": "^[2-9]\\d{9}$"
            }
          ],
          "description": "US mobile or landline number. Punctuation and a leading +1 are tolerated."
        }
      },
      "additionalProperties": false,
      "description": "The vehicle owner. At least one of email / phone is required; everything else is optional."
    },
    "vehicle": {
      "type": "object",
      "properties": {
        "vin": {
          "allOf": [
            {
              "type": "string"
            },
            {
              "type": "string",
              "minLength": 11,
              "maxLength": 17
            }
          ],
          "description": "Vehicle Identification Number. A full 17-character VIN lets us decode year/make/model/trim."
        },
        "plate": {
          "type": "string",
          "minLength": 1,
          "maxLength": 12,
          "description": "License plate. Requires plate_state to resolve a VIN."
        },
        "plate_state": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2,
          "description": "Two-letter US state code, e.g. TX."
        },
        "year": {
          "type": "integer",
          "minimum": 1900,
          "maximum": 2100
        },
        "make": {
          "allOf": [
            {
              "type": "string",
              "maxLength": 60
            },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          ]
        },
        "model": {
          "allOf": [
            {
              "type": "string",
              "maxLength": 80
            },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            }
          ]
        },
        "trim": {
          "allOf": [
            {
              "type": "string",
              "maxLength": 80
            },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            }
          ]
        },
        "odometer": {
          "type": "integer",
          "minimum": 0,
          "maximum": 2000000,
          "description": "Odometer reading in miles at the time of loss."
        }
      },
      "additionalProperties": false,
      "description": "The vehicle. A VIN (or plate + plate_state) is best; year/make/model works too."
    },
    "loss": {
      "type": "object",
      "properties": {
        "date_of_loss": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Calendar date, YYYY-MM-DD."
        },
        "loss_state": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2,
          "description": "State where the loss occurred / the policy is written."
        },
        "zip": {
          "type": "string",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "description": "US ZIP code (5 or 5+4). Used to search comparable vehicles near the customer."
        },
        "insurance_path": {
          "type": "string",
          "enum": [
            "own",
            "at-fault",
            "unknown",
            "none"
          ],
          "description": "Whose insurance is handling it: own (customer's carrier), at-fault (the other driver's carrier), unknown, or none (no insurance claim — valuation only)."
        }
      },
      "additionalProperties": false,
      "description": "When and where the loss happened."
    },
    "offer": {
      "type": "object",
      "properties": {
        "insurer": {
          "allOf": [
            {
              "type": "string",
              "maxLength": 120
            },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            }
          ],
          "description": "Insurance company handling the total loss."
        },
        "claim_number": {
          "type": "string",
          "minLength": 1,
          "maxLength": 60
        },
        "acv_offer_cents": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000000,
          "description": "Insurer's Actual Cash Value offer in cents. `acv_offer` (dollars) is also accepted."
        },
        "acv_offer": {
          "type": "number",
          "minimum": 0,
          "maximum": 1000000,
          "description": "Insurer's Actual Cash Value offer in dollars. Converted to cents server-side."
        }
      },
      "additionalProperties": false,
      "description": "The insurer's position so far, if any."
    },
    "consent": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "customer_directed",
            "warm_handoff"
          ],
          "default": "customer_directed",
          "description": "customer_directed: the customer asked their agent to submit this. warm_handoff: a registered agent attests the customer asked to be contacted now (priority callback; requires an API key)."
        },
        "attestation": {
          "type": "string",
          "minLength": 20,
          "maxLength": 1000,
          "description": "The agent's attestation, in its own words, that the customer asked for this submission and knows SecondAppraisal will email/text and call to confirm. Stored verbatim on the intake."
        },
        "attestor_name": {
          "allOf": [
            {
              "type": "string",
              "maxLength": 120
            },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            }
          ],
          "description": "Who is attesting (the agent, or the person operating it)."
        },
        "notify_customer": {
          "type": "boolean",
          "default": true,
          "description": "true (default): we send the customer our welcome email/text with the confirm link. false: you relay `customer_message` and `customer_confirmation_url` yourself and we send nothing until they confirm or we call."
        }
      },
      "required": [
        "attestation"
      ],
      "additionalProperties": false,
      "description": "Consent basis. Attestation wording version 2026-09-16.1."
    },
    "external_ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Your reference id; echoed in every response."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Any unique string per logical submission; a replay returns the original receipt."
    }
  },
  "required": [
    "agent",
    "customer",
    "consent"
  ],
  "additionalProperties": false,
  "description": "Submit a vehicle owner's total-loss situation on their behalf."
}

Fetch the current receipt for a submitted intake (status, confirm link while still confirmable, preliminary).

{
  "type": "object",
  "properties": {
    "intake_id": {
      "type": "string",
      "minLength": 1,
      "description": "The `intake_id` from a previous submission."
    },
    "poll_token": {
      "type": "string",
      "minLength": 1,
      "description": "The `poll_token` returned once on that submission."
    }
  },
  "required": [
    "intake_id",
    "poll_token"
  ],
  "additionalProperties": false
}

Attach the insurer's Market Valuation Report (CCC / Mitchell PDF) to a submitted intake. We parse it (vehicle, mileage, offer, insurer, loss date) and refresh the preliminary. Allow up to two minutes.

{
  "type": "object",
  "properties": {
    "intake_id": {
      "type": "string",
      "minLength": 1,
      "description": "The `intake_id` from a previous submission."
    },
    "poll_token": {
      "type": "string",
      "minLength": 1,
      "description": "The `poll_token` returned once on that submission."
    },
    "file_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Original file name, e.g. valuation-report.pdf."
    },
    "file_base64": {
      "type": "string",
      "minLength": 1,
      "description": "The PDF bytes, base64-encoded (standard or URL-safe alphabet). Up to 15 MB decoded."
    }
  },
  "required": [
    "intake_id",
    "poll_token",
    "file_name",
    "file_base64"
  ],
  "additionalProperties": false
}

A no-commitment early market read for a vehicle: comparable listing prices near the customer (10th percentile / median / 90th), an odometer-adjusted mid, and the gap vs the insurer's offer. Not an appraisal. Nothing is stored about the customer.

{
  "type": "object",
  "properties": {
    "year": {
      "type": "integer",
      "minimum": 1900,
      "maximum": 2100
    },
    "make": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "model": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "trim": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "zip": {
      "type": "string",
      "pattern": "^\\d{5}(-\\d{4})?$",
      "description": "Preferred; searches comparables near here."
    },
    "state": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "Two-letter state; used when no zip is given."
    },
    "odometer": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2000000
    },
    "acv_offer_cents": {
      "type": "integer",
      "minimum": 0,
      "description": "Insurer's offer in cents, to report the gap."
    }
  },
  "required": [
    "year",
    "make",
    "model"
  ],
  "additionalProperties": false
}

State-specific total-loss facts: threshold and method, whether an independent appraiser must be licensed there, whether third-party appraisals are allowed, statute citations, must-know rights, common pitfalls, and the consumer hotline.

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "minLength": 2,
      "maxLength": 40,
      "description": "Two-letter code (TX) or state name (Texas)."
    }
  },
  "required": [
    "state"
  ],
  "additionalProperties": false
}