> ## 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.

# API Overview

> Overview of TAMradar APIs, radar types, delivery modes, and integration model.

## What is TAMradar API?

The TAMradar API gives developers a single integration surface for company, contact, and industry monitoring. The API:

* Continuously monitors publicly available web data across 15 radar types
* Structures findings into consistent, typed webhook payloads
* Delivers updates via push (webhooks) or pull (`GET /v1/updates`), based on your integration model
* Provides a REST API with JSON responses and API key authentication

The API lets developers integrate company, contact, and industry monitoring into their applications, from sales intelligence to market research to competitive tracking.

## How TAMradar Works

TAMradar operates on a simple concept:

1. **Create a radar** — specify a domain (or contact/industry) and the signal type to monitor
2. **We scan continuously** — our pipelines monitor sources on a recurring schedule
3. **We detect findings** — when a match is found, it's processed and structured
4. **You receive updates** — delivered to your webhook and/or available to poll

```
You ──► Create Radar ──► TAMradar monitors ──► Finding detected
                                                      │
                              ┌───────────────────────┴──────────────────────┐
                              │ Push (webhook)                Pull (poll)     │
                              │ POST to webhook_url           GET /v1/updates │
                              │ (if webhook_url was set)      (always works)  │
                              └───────────────────────────────────────────────┘
```

Both delivery modes return identical payload structures.

## Core Components

### Radars

Radars are the fundamental monitoring units. Each radar monitors a specific target and signal type and runs continuously until deactivated.

**Company radars** — monitor a company by domain:

| Radar Type                   | What it tracks                       |
| ---------------------------- | ------------------------------------ |
| `company_job_openings`       | New job postings                     |
| `company_new_hires`          | Recently hired employees             |
| `company_promotions`         | Internal promotions                  |
| `company_reviews`            | Employer reviews                     |
| `company_social_posts`       | Company social media posts           |
| `company_social_posts_cxo`   | Executive-level social posts         |
| `company_mentions`           | Web mentions of the company          |
| `company_social_engagements` | Engagement activity on company posts |

**Contact radars** — monitor a specific person:

| Radar Type                   | What it tracks                   |
| ---------------------------- | -------------------------------- |
| `contact_job_changes`        | Career moves / employer changes  |
| `contact_social_posts`       | Individual's social media posts  |
| `contact_social_engagements` | Individual's engagement activity |

**Industry radars** — monitor signals across an industry or keyword set:

| Radar Type                | What it tracks                         |
| ------------------------- | -------------------------------------- |
| `industry_mentions`       | Companies mentioning specific keywords |
| `industry_funding_rounds` | New funding announcements              |
| `industry_new_companies`  | Newly founded companies                |
| `industry_job_openings`   | Job openings matching criteria         |

### Delivery

TAMradar supports two delivery modes. You can use one or both:

**Push — Webhooks**
Set a `webhook_url` when creating a radar and TAMradar will POST each finding to your endpoint in real-time. Your endpoint must return a 2xx response to acknowledge receipt.

**Pull — Polling**
`GET /v1/updates` returns findings on demand for any radar, including radars created without a `webhook_url`. Supports cursor-based pagination and filters by `radar_id`, `radar_type`, `domain`, and `since` (ISO 8601 date).

> `webhook_url` is optional on single-radar creation endpoints. For async bulk (`POST /v1/radars/bulk`), `webhook_url` is required.

See **[Update Payloads](/webhooks/overview)** for the full payload format per radar type.

### Contact-Based Radars

Contact radars track specific individuals rather than company-wide events:

* Identified via email, profile URL, or full name
* Multiple contacts can be tracked per company domain
* Different contact radar types for the same person are allowed (e.g., both `contact_job_changes` and `contact_social_posts`)
* Contact identifiers are used for creation but not included in webhook payloads for privacy

### Persona-Based Filtering

Reduce noise by filtering findings to your target persona. Provide a `filters` object when creating a radar:

* Filter by `departments` and `seniorities`
* Use boolean queries for `job_titles` (`AND`, `OR`, `NOT`, quoted phrases)
* Supported radar types: `company_new_hires`, `company_job_openings`, `company_promotions`, `company_social_posts_cxo`

See **[Persona-Based Filtering Guide](/guides/filtering-and-personas)** for full details.

### Balance & Pricing

TAMradar uses a USD-based balance system with two pricing models:

**Monthly Subscription**

* Charged at radar creation
* Recharged automatically every 30 days while active
* If balance is insufficient at renewal, the radar is automatically deactivated

**Update-Based**

* No charge at creation
* Charged per approved finding only — you pay for results
* If a charge fails, all active radars of that type are paused until balance is restored

Rates are per radar type and customer-specific. See **[Balance System Explained](/guides/balance-system-explained)** for full details including refunds and balance webhook events.

## The TAMradar Lifecycle

1. **Create** — single radar or submit an async bulk (up to 1000 items) via `POST /v1/radars/bulk`
2. **Monitor** — TAMradar scans sources continuously on a schedule
3. **Detect** — findings are processed, structured, and stored
4. **Deliver** — pushed to your webhook and/or available via `GET /v1/updates`
5. **Charge** — monthly at renewal (subscription) or per finding (update-based)
6. **Deactivate** — manually via `DELETE /v1/radars/:id` or automatically on insufficient balance

## Use Cases

* **Sales Intelligence** — trigger outreach on hiring signals, leadership changes, funding rounds
* **TAM Prioritization** — surface accounts showing intent (social posts, job openings, new hires)
* **TAM Expansion** — discover companies mentioning target keywords or hiring for specific roles
* **Competitive Analysis** — monitor competitor activities and executive messaging
* **Recruitment** — track hiring patterns and new joiners at target companies
* **Investor Intelligence** — monitor portfolio companies or track funding activity by sector

## Technical Foundation

* **RESTful API** — standard HTTP methods, consistent JSON responses
* **API Key Auth** — `x-api-key` header on all `/v1/` routes
* **Typed creation endpoints** — `POST /v1/radars/companies`, `/contacts`, `/industry`
* **Async bulk creation** — `POST /v1/radars/bulk` — queue up to 1000 items (returns `202` + `bulk_id`)
* **Bulk status polling** — `GET /v1/radars/bulk/{bulk_id}` — track progress and final per-item outcomes
* **Poll endpoint** — `GET /v1/updates` — cursor-based, up to 100 per page, filterable
* **Account summary** — `GET /v1/account` — balance, radar counts, optional `?month=YYYY-MM`
* **Webhook schema** — `GET /v1/webhooks/schema` — runtime payload schema per radar type
* **Rate limiting** — fair-use limits enforced per API key

## Getting Started

1. **[Get Started Guide](/getting-started)** — step-by-step: create your first radar
2. **[API Definitions](/api-reference/post-radars-companies#/)** — full OpenAPI spec
3. **[Authentication](/guides/authentication-rate-limits#/)** — API key usage and rate limits
4. **[Update Payloads](/webhooks/overview)** — payload structure per radar type (webhooks + poll)
5. **[Error Handling](/guides/error-handling#/)** — error codes and troubleshooting

***

Need personalized assistance? [Contact our support team](mailto:support@tamradar.com)