Decision Monitors

Create a new decision monitor

Creates a new monitor that watches for rate changes matching the specified criteria. When rates change and meet the monitor's conditions, a webhook is delivered to your configured endpoint.

Two monitor types (discriminated by target_type):

  • Decision monitor (default, omit target_type): watches the aggregate market-best decision for a state + product.
  • Competitor monitor (target_type: "competitor"): watches a single named credit union's published rate and alerts on changes — useful for tracking a specific competitor rather than the whole market.

Key Features:

  • Subscription-based: Watch specific states and product types for rate changes
  • Condition filtering: Only trigger when savings or confidence thresholds are met
  • Cooldown protection: Prevent webhook spam with configurable cooldown periods
  • Webhook delivery: Secure HTTPS webhooks with signature verification

Important: The webhook signing secret is only returned once at creation time. Store it securely.

Authentication required: Pass your API key in the X-API-Key header.

post/v1/monitors

Request

  • Base URL: https://api.rateapi.dev
  • URL: https://api.rateapi.dev/v1/monitors
  • Auth: API key in header X-API-Key

Headers

Idempotency-Keystring

Optional request identifier that makes this POST safe to retry. The first successful (2xx) response for a given identifier + request body is stored for 24 hours; a retry with the SAME identifier and SAME body replays that stored response and includes an Idempotent-Replayed: true response header (the handler does not run again). Reusing the same identifier with a DIFFERENT request body returns 422. Authenticated writes are scoped per API key. Use a UUID per logical operation.

Request body

OR

Example request

{
  "name": "California Refinance Alerts",
  "decision_context": {
    "state": "CA",
    "product_type": "mortgage",
    "intent": "refinance",
    "amount": 500000,
    "term_months": 360,
    "credit_score": 750,
    "income_annual": 120000,
    "rate_type": "fixed",
    "prefer_credit_unions": true
  },
  "conditions": [
    {
      "field": "apr",
      "operator": "lt",
      "value": 6.5
    }
  ],
  "subscribed_states": [
    "CA",
    "TX"
  ],
  "subscribed_product_types": [
    "mortgage"
  ],
  "cooldown_hours": 24,
  "webhook_url": "https://your-app.com/webhooks/rate-alerts"
}

Response

Monitor created successfully

OR

Example response

{
  "monitor": {
    "id": "mon_abc123xyz",
    "name": "California Refinance Alerts",
    "status": "active",
    "decision_context": {
      "credit_score_band": "excellent",
      "income_band": "high",
      "loan_amount_band": "250k_500k",
      "state": "CA",
      "product_type": "mortgage",
      "intent": "refinance",
      "term_months": 360,
      "rate_type": "fixed",
      "prefer_credit_unions": true
    },
    "conditions": [
      {
        "field": "apr",
        "operator": "lt",
        "value": 6.5
      }
    ],
    "subscribed_states": [
      "CA",
      "TX"
    ],
    "subscribed_product_types": [
      "mortgage"
    ],
    "cooldown_hours": 24,
    "webhook_url": "https://your-app.com/webhooks/rate-alerts",
    "webhook_signing_secret_prefix": "whsec_a1b2",
    "last_evaluated_at": "2024-01-15T12:00:00.000Z",
    "last_triggered_at": "2024-01-14T08:30:00.000Z",
    "created_at": "2024-01-10T09:00:00.000Z",
    "updated_at": "2024-01-15T12:00:00.000Z"
  },
  "webhook_signing_secret": "whsec_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
}

Changes

No recorded changes to this operation across all 1 revision of this API.