Getting Started with TAMradar

What is TAMradar?

TAMradar helps you monitor companies by tracking their online activities and sending you real-time notifications about important changes.

Core Concepts Briefly Explained

Radars: These are your monitors. You define a company domain (e.g., example.com) and the type of information you want to track (e.g., job_openings, new_hires).
Webhooks: This is how you receive real-time notifications. When a radar detects a relevant event, TAMradar sends a POST request with the data to a URL you provide.
Credits: Radars require credits to be created and to continue running. Credits are deducted for initial setup and for monthly renewals.

Implementation Journey

Integrating TAMradar into your application involves these key steps that we'll explore in this guide:

Setting up your environment
Creating your first radar
Checking your radar status
Verifying your credit balance
Receiving and processing webhook events
Managing your radars (optional deactivation)

Step 1: Setting Up Your Environment

Prerequisites

API Key: You'll need a TAMradar API key to authenticate your requests
Webhook Endpoint: A publicly accessible URL that can receive POST requests
HTTP Client: Any tool or library that can make HTTP requests (e.g., cURL, Axios, Fetch)

Configure Your API Key

All requests to TAMradar require authentication via an API key. You'll include this key in the x-api-key header with every request:

# You'll use this pattern for all API calls
curl -H "x-api-key: YOUR_API_KEY" https://api.tamradar.com/v1/...

Set Up Your Webhook Endpoint

Before creating a radar, ensure you have a publicly accessible endpoint that can:

Accept HTTP POST requests
Parse JSON request bodies
Return a 2xx response code to acknowledge receipt

Step 2: Creating Your First Radar

Now let's create a radar to monitor a company:

curl -X POST https://api.tamradar.com/v1/radars \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "radar_type": "job_openings",
    "webhook_url": "https://your-domain.com/webhook",
    "filters": {
      "departments": ["Engineering"],
      "seniorities": ["Senior", "Manager"]
    },
    "custom_fields": {
      "priority": "high",
      "target_account_id": "0011U00000TFV7MQAX"
    }
  }'

Key Parameters:

domain: The company domain you want to monitor (e.g., "example.com")
radar_type: The type of information you want to track - see API Overview for all available types
webhook_url: Your endpoint where events will be sent
filters: (Optional) An object to filter for specific personas. See our Filtering Guide for details.
custom_fields: (Optional) Any additional data you want included with webhook events

Sample Response:

{
  "status": "success",
  "code": 201,
  "message": "Radar created successfully",
  "data": {
    "radar_id": "rad_123xyz",
    "domain": "example.com",
    "radar_type": "job_openings",
    "webhook_url": "https://your-domain.com/webhook",
		"next_charge_at": "2024-04-20T12:05:00Z", 
    "filters": {
      "departments": ["Engineering"],
      "seniorities": ["Senior", "Manager"]
    },
    "custom_fields": {
      "priority": "high",
      "target_account_id": "0011U00000TFV7MQAX"
    },
    "active": true,
    "created_at": "2024-03-20T12:05:00Z"
  },
  "timestamp": "2024-03-20T12:05:00Z"
}

Be sure to store the radar_id - you'll need it to check status or deactivate the radar later.

Step 3: Checking Your Radar Status

After creating a radar, you might want to check its status:

# Get a specific radar by ID
curl -X GET https://api.tamradar.com/v1/radars/rad_123xyz \
  -H "x-api-key: YOUR_API_KEY"

# List all your active radars
curl -X GET https://api.tamradar.com/v1/radars \
  -H "x-api-key: YOUR_API_KEY"

This allows you to:

Verify your radar was created successfully
Check its current status (active, inactive, etc.)
See when the next charge will occur
View other configuration details

Step 4: Checking Your Credit Balance

It's good practice to monitor your credit balance regularly:

curl -X GET https://api.tamradar.com/v1/account \
  -H "x-api-key: YOUR_API_KEY"

This will return your current balance and information about upcoming credit expirations:

{
  "status": "success",
  "code": 200,
  "timestamp": "2025-06-20T12:00:00Z",
  "message": "Account summary retrieved",
  "data": {
    "usage": {
      "month": "2025-06",
      "credits_used": 25,
      "radars_created": 5,
      "radars_deactivated": 2
    },
    "account": {
      "total_radars": 18,
      "active_radars": 15,
      "inactive_radars": 3
    },
    "credits_remaining": 1000
  }
}

Step 5: Receiving Webhook Events

Once your radar is active and finds relevant information that matches your filters (if any), TAMradar will send webhook events to your specified URL. Here's what to expect:

Example Webhook Payload

{
  "event_id": "56827475-e5cf-4c00-b22c-479a334c29c3",
  "event_type": "radar_finding",
  "record_id": "b77af154-c369-4446-b70a-f328880c3a48",
  "discovered_at": "2025-06-18T16:29:40Z",
  "data": {
    "radar_id": "c70813b3-7e87-4ca7-90fd-8c64574d911b",
    "radar_type": "reviews",
    "domain": "domain.com",
		"next_charge_at": "2024-04-18T10:15:30Z",
    "custom_fields": {
      "priority": "high",
      "account_id": "0011U00000TFV7MQAX"
    }
  },
  "content": {
    "review_content": "Great product with excellent customer support. The onboarding process was smooth and the team was very responsive to our needs. Would highly recommend!",
    "review_url": "https://www.g2.com/products/domain/reviews/123456",
    "review_source": "G2",
    "review_rating": "5",
    "reviewed_at": "2024-03-18"
  }
}

Handling Webhook Events

When processing webhook events, you should:

Verify the event structure - Check that it contains all expected fields
Process the data - Extract the relevant information for your application
Acknowledge receipt - Return a 2xx HTTP status code to confirm successful delivery
Implement idempotency - Use the event timestamp or other unique identifiers to prevent duplicate processing

For detailed information on webhook event structures for each radar type, refer to our Webhook Payloads documentation.

Step 6: Managing Your Radars (Optional)

Deactivating a Radar

If you no longer need a radar, you can deactivate it to stop monitoring and prevent future credit charges:

curl -X DELETE https://api.tamradar.com/v1/radars/7597876d-127b-451e-ab56-6dd6429e6f70 \
  -H "x-api-key: YOUR_API_KEY"

Upon successful deactivation, you'll receive:

{
    "status": "success",
    "code": 200,
    "timestamp": "2025-06-18T17:27:02Z",
    "message": "Radar deactivation initiated - service will continue until the end of the current billing cycle",
    "data": {
        "radar_id": "7597876d-127b-451e-ab56-6dd6429e6f70",
        "radar_type": "promotions",
        "domain": "domain.com",
	      "created_at": "2025-06-18T17:25:48.20Z",
				"next_charge_at": null,
        "deactivated_at": "2025-06-18T17:27:02Z",
        "webhook_url": "https://your-domain.com/webhook",
        "radar_status": "inactive",
        "custom_fields": {
            "yc_experiment": true
        },
        "filters": {}
    }
}

Note that deactivation is immediate and cannot be undone. To resume monitoring, you would need to create a new radar.

Common Implementation Patterns

Recommended Implementation Flow

Check your credit balance before creating new radars
Create radars for companies you want to monitor
Set up robust webhook handling with error logging
Store events in your database for historical reference
Implement regular credit balance checking
Add automated alerts for low credit balance

Error Handling Best Practices

Handle 402 errors (insufficient credits) by alerting administrators
Implement retries with backoff for 5xx errors
Log all API interactions for troubleshooting
For detailed error handling strategies, see our Error Handling guide

Next Steps

Now that you've learned the basics, explore these resources to enhance your TAMradar integration:

API Overview: Understand the fundamental concepts and workflows
API Definitions: Detailed API specifications for all endpoints
Authentication & Rate Limits: Details about security and usage limits
Webhook Payloads: In-depth information about webhook event structures
Error Handling: Comprehensive guide to handling API errors

Need help with your implementation? Contact our support team