- A TAMradar API key (UUID format, e.g.
a1b2c3d4-...) - A publicly accessible HTTPS endpoint that accepts POST requests — use webhook.site for testing
- Any HTTP client (
curl, Axios,fetch, etc.)
https://api.tamradar.com
Auth header: x-api-key: YOUR_API_KEY (required on every request)
Step 1: Verify Your Account & Balance
Before creating anything, confirm your key works and you have enough balance.balance_remaining_usd is what you have to spend. Each radar type has its own price. If you don’t have enough to cover a radar creation, you’ll get a 402 before anything is charged.
Step 2: Test Your Webhook Endpoint
Send a sample payload to your endpoint before committing balance. This is fire-and-forget. It won’t create a radar or charge anything.radar_finding payload. If it arrives, your endpoint is reachable and returning 2xx. Proceed.
You can also test a failure payload: add "update_type": "radar_failure" to the body.
Step 3: Create a Company Radar (Job Openings at OpenAI)
Track new engineering job openings posted by OpenAI, filtered to Senior-level and above. Setupdates_since to include recent activity. Choose a date a few weeks or
months back for eligible activity from that period plus ongoing updates. If
omitted, most radars start at their exact creation time, not the start of today:
even a post published one minute earlier is excluded. Your first check may return
no results, and updates may take time to arrive.
New hires and promotions use UTC calendar-month precision: set updates_since
to an earlier month to include activity from that month onward. If omitted,
eligibility starts in the month the radar was created.
To see sample findings first, use Preview where
supported. Preview chooses its own lookback and does not accept updates_since.
webhook_urlis optional. Include it to receive real-time push notifications. Omit it to poll for updates viaGET /v1/updatesinstead.
radar_id. You’ll use it to check status or deactivate the radar.
next_charge_at is your next billing date, 30 days from creation.
Future start dates are not supported. Omission returns updates_since: null.
What can go wrong
Step 4: Create a Contact Radar (Track Sam Altman)
Monitor job changes for a specific person. Requiresdomain + at least one identifier (email, profile_url, or full_name).
For
contact_job_changes, email must identify an individual; role-based,
shared, and placeholder addresses are rejected. A supplied profile_url must
be a LinkedIn person profile (linkedin.com/in/...); company, school, and
legacy /pub/ URLs are rejected. Duplicate matching within the same company
and radar type uses the email or normalized LinkedIn profile URL. full_name
is accepted as an identifier but is not a duplicate key.
Step 5: Create an Industry Radar (AI Funding Rounds)
Track funding events across the AI industry, with no specific company or keyword needed.domain is always null for industry radars.
Industry radar type requirements:
Step 6: Scale Up with Bulk Creation
Submit up to 1000 radars in one async bulk request. Useful when onboarding large account lists.priority is optional ("low", "normal", or "high"; default "normal").
It orders your bulks; bulks already started go first. See
Set a priority for your bulks.
webhook_url is optional. Omit it for poll-only mode. With a webhook URL, bulk
processing sends item outcomes (radar_created / radar_failure) plus a final
bulk_completed.
202 — Accepted (request queued for async processing):
bulk_id:
status: "processing"while there are in-flight itemsstatus: "completed"when all items are terminalprioritywith the effective priority set at submissionsummarycounts (processing,created,failed)radars[]withitem_indexso you can map outcomes back to input orderradars[].update_idso you can correlate each item with itsradar_created/radar_failureevent
- Use top-level
update_idonbulk_completedto deduplicate the whole batch event - Use
radars[].update_idinsidebulk_completedto correlate each item-level event
Step 7: Handle Failure Webhooks
When a radar fails during setup, TAMradar sends aradar_failure webhook to your endpoint and refunds the charge.
missing_prerequisites — The company has no trackable public data source for this radar type. Balance is refunded.
insufficient_funds — Recurring billing failed; radar was deactivated. No refund (the radar ran; it just couldn’t renew).
code and message:
Step 8: Receive Webhook Findings
When a radar detects something, it POSTs to yourwebhook_url. Every payload shares the same base structure. Only content varies by radar type.
Company job opening at OpenAI
New hire at OpenAI
update_id— use for idempotency. If you receive the sameupdate_idtwice, skip it.custom_fields— your metadata, echoed back exactly as set on the radar.discovered_at— the time the update was added to your updates feed; use it for ordering and incremental polling (see Step 9).- Return any
2xxstatus within 10 seconds. TAMradar will retry on failure (up to 3 retries: 1m, 5m, 15m).
Handling webhooks in your server
Acknowledge first, process after. TAMradar waits up to 10 seconds for a 2xx. If you do slow work (database writes, third-party calls) synchronously before responding, you risk a timeout and a retry.update_id.
Step 9: Poll for Updates (Alternative to Webhooks)
GET /v1/updates returns the same payloads that webhooks deliver. Use this to backfill missed events, audit history, or as your primary data retrieval method.
Do not confuse GET /v1/updates?since= with radar updates_since.
updates_since is the radar’s permanent source-event eligibility boundary;
the polling since parameter only filters TAMradar updates already created.
Fetch all updates for your OpenAI radars since yesterday:
next_cursor until has_more: false. Send the same since and filters with every cursor — the cursor does not remember them.
Incremental polling loop:
discovered_at is the time the update was added to your feed, and results are
filtered and ordered by it. Starting about a minute before your bookmark
re-reads a few updates (hence the update_id check) and lowers the risk of
missing one that was being added while you polled — it does not guarantee it.
If a cursor request returns 400 (Invalid cursor), restart that walk from
the first page with the same since and filters, and don’t move your bookmark
until a walk completes.
radar_failureevents are excluded by default. To include them:?update_type=radar_finding,radar_failureData retention: about 60 days. Poll well within that window if you don’t use webhooks.
Step 10: Monitor Your Radars
List all active radars:radar_status (active/inactive), updates_since (stored
eligibility boundary or null), next_charge_at (next billing date), and
deactivated_at.
Step 11: Deactivate a Radar
When you no longer need a radar, delete it to stop billing.DELETE /v1/radars/bulk. It returns final,
ordered per-item outcomes synchronously; its bulk_id is for correlation, not
status polling.
Before You Ship
- Deduplicate on
update_id— webhooks are at-least-once. Store processed IDs and skip duplicates. - Respond 2xx within 10 seconds — acknowledge the request before doing any slow work.
- Handle
radar_failurewebhooks — alert your team when a radar fails so it doesn’t silently stop. - Monitor
balance_remaining_usd— set up an alert when it drops below your comfort threshold. A zero balance deactivates radars without warning. - Store
radar_idper account — you’ll need it to list, inspect, or deactivate a radar later. - Test your endpoint with
/v1/webhooks/testbefore creating your first paid radar. - Use
sincefor incremental polling — if you use/v1/updates, store the highestdiscovered_atafter each complete sync, poll from about a minute before it, and deduplicate byupdate_id. Don’t re-fetch everything on every poll.
Quick Reference
Rate limits: TAMradar uses separate write/read budgets plus a dedicated bulk budget.
On
429, honor Retry-After before retrying.
Error codes:
Every error response includes
error_id. Include it when contacting support.