Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tamradar.com/llms.txt

Use this file to discover all available pages before exploring further.

This page gives a high-level view of TAMradar billing and lifecycle behavior. For model-specific implementation details:

​
Overview

TAMradar uses a USD credit balance system to bill for radar usage. Two pricing models exist, and which one applies to a radar depends on your account configuration per radar type.

​
Pricing Models

​
Monthly Subscription

  • Charge at creation — balance is deducted when the radar is first created.
  • Recurring charge — deducted automatically every 30 days while the radar is active. next_charge_at in the API response shows the next billing date.
  • Refund on setup failure — if the radar fails during initial setup (missing prerequisites, source inaccessible), the creation charge is automatically reversed and you receive a radar_failure webhook with refund_amount_usd > 0.
  • User cancellation — radar transitions to inactive. For monthly subscription, service can continue until the current billing period ends.

​
Update-Based

  • No charge at creation — next_charge_at is null. Nothing is deducted when the radar is set up.
  • Charged per update found — balance is deducted each time TAMradar finds and approves a new update for your radar (a new hire, job change, funding round, etc.).
  • No refund on setup failure — if the radar fails during setup, you receive a radar_failure webhook with refund_amount_usd: 0 (nothing was charged, so nothing to refund).
  • Auto-reactivation on top-up — if a radar was deactivated due to insufficient funds, it automatically reactivates when a new payment is added to your account. No manual action needed.

​
Radar States

radar_status in public API responses is intentionally simplified to two values:
Public radar_statusMeaning
activeRunning normally. Balance is deducted per the pricing model.
inactiveAny non-active lifecycle state (cancelled, failed, insufficient funds, or grace-period state).
Internal lifecycle enums are implementation details and are not part of the public API contract. For external handling, use:
  • radar_status (active / inactive)
  • radar_failure payload fields like failure_reason, message, and refund_amount_usd

​
Monitoring Balance Events

​
Webhook Notifications

Your application receives radar_failure webhook events whenever a radar is deactivated due to a billing or setup issue. Monthly subscription — insufficient funds during renewal Radar is deactivated when the 30-day charge cannot be covered. No refund (the original creation charge was for time already used). 
{
  "update_id": "550e8400-e29b-41d4-a716-446655440000",
  "update_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2025-03-20T14:10:38Z",
  "data": {
    "radar_id": "54e32291-25a4-459f-8bd6-4f79489ea931",
    "radar_type": "company_new_hires",
    "domain": "example.com",
    "next_charge_at": null,
    "custom_fields": {}
  },
  "content": {
    "failure_reason": "insufficient_funds",
    "refund_amount_usd": 0,
    "message": "Your radar was deactivated due to insufficient funds. Please add more credits to reactivate."
  }
}
Monthly subscription — setup failure (with refund) Radar failed during initial setup. Creation charge is reversed automatically. 
{
  "update_id": "41991828-ed31-4bd9-98d2-44b2763f9f35",
  "update_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2025-03-20T08:30:00Z",
  "data": {
    "radar_id": "c70813b3-7e87-4ca7-90fd-8c64574d911b",
    "radar_type": "industry_job_openings",
    "domain": null,
    "next_charge_at": null,
    "custom_fields": {}
  },
  "content": {
    "failure_reason": "missing_prerequisites",
    "refund_amount_usd": 5.00,
    "message": "Radar creation failed: missing prerequisites."
  }
}
Update-based — setup failure (no refund) Same webhook shape, but refund_amount_usd is always 0 because nothing was charged at creation. 
{
  "update_id": "72bc9a00-1234-4abc-b000-aabbccddeeff",
  "update_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2025-03-21T10:00:00Z",
  "data": {
    "radar_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "radar_type": "contact_job_changes",
    "domain": "example.com",
    "next_charge_at": null,
    "custom_fields": {}
  },
  "content": {
    "failure_reason": "missing_prerequisites",
    "refund_amount_usd": 0,
    "message": "Radar creation failed: missing prerequisites."
  }
}

​
Failure Reasons

failure_reasonDescriptionRefund
missing_prerequisitesRequired public data not found (e.g. no LinkedIn profile, no public RSS)Monthly sub: yes. Update-based: no.
source_inaccessibleData source exists but cannot be accessedMonthly sub: yes. Update-based: no.
setup_failureGeneric failure during radar initialisationMonthly sub: yes. Update-based: no.
insufficient_fundsRadar deactivated — balance too low for renewal chargeNo refund

​
Bulk Endpoint — Async Outcomes

POST /v1/radars/bulk is asynchronous. The submission endpoint returns 202 with bulk_id, and item outcomes are emitted later. For balance-related failures in bulk:
  • the affected item ends in a failure state during async processing
  • the failure appears in:
    • GET /v1/radars/bulk/:bulk_id item results, and
    • webhook delivery (radar_failure for item-level failures, plus final bulk_completed)
Treat bulk as a queued workflow rather than a synchronous per-item response.

​
Best Practices

  1. Monitor balance — poll GET /v1/account for balance_remaining_usd and alert before it hits zero.
  2. Handle radar_failure webhooks — persist failure_reason and refund_amount_usd for reconciliation.
  3. Update-based: top up proactively — radars auto-reactivate on top-up, but there’s a gap while they’re inactive. Schedule automatic top-ups to avoid missed updates.
  4. Monthly subscription: budget for renewals — check next_charge_at on your active radars and ensure balance covers the next 30 days.
  5. Bulk retries are workflow-based — top up balance, then resubmit the failed items from your async bulk status/webhook outcomes.