Using GigRadar API

How GigRadar Works

Understanding the GigRadar workflow is essential for building effective integrations. Here's how the system processes jobs from detection to submission. You can learn more in complete API documentation.

System Architecture Flow

Flow Explanation

Scanner + Upwork Job → Opportunity
- GigRadar scanners continuously monitor Upwork for new job postings
- When a job matches your scanner criteria (keywords, skills, budget, etc.), an Opportunity is created
- The opportunity contains job details, match score, and AI qualification results
Opportunity + Scanner Settings (or API) → Application (not sent)
- If auto-bidder is enabled in scanner settings, GigRadar automatically generates an application
- Alternatively, you can create applications via the Public API
- At this stage, the application exists but is not yet sent to Upwork
- The application contains cover letter, question answers, bid information, but no scheduledAt or sent timestamps
Application + scheduledAt → Proposal (sent) or Error
- When scheduledAt is set, GigRadar attempts to send the application to Upwork
- If successful: Application becomes a Proposal with sent timestamp and proposalId
- If failed: Application has error: true with errorCode and errorMessage

Key States

Opportunity: Job matched, no application yet
Application (unscheduled): Created but not scheduled to send (scheduledAt is null)
Application (scheduled): Has scheduledAt but not yet sent (sent is null)
Proposal: Successfully sent to Upwork (sent timestamp exists, proposalId assigned)
Application (error): Failed to send (error: true, errorMessage present)

Building a Custom Cover Letter Generation Agent

This guide walks you through building your own cover letter generation system that integrates with GigRadar via the Public API. You'll receive real-time job opportunities via webhooks, generate custom cover letters, and submit applications programmatically.

Complete Integration Flow

Step 1: Get Your API Key

Log in to your GigRadar account at https://beta.gigradar.io
Navigate to Settings → API Access
Click Generate New API Key
Copy and securely store your API key (format: gr_live_...)

⚠️ Critical: Keep your API key secure. Never commit it to version control. Use environment variables or secure secret management.

Step 2: Register OPPORTUNITY.CREATE Webhook

Create a webhook subscription to receive real-time notifications when new opportunities are created:

curl -X POST https://api.gigradar.io/public-api/v1/webhooks \   
    -H "X-API-Key: your_api_key_here" \   
    -H "Content-Type: application/json" \   
    -d '{   
"url": "https://your-server.com/webhooks/gigradar",   
"scopes": ["GIGRADAR.OPPORTUNITY.CREATE"],   
"auth": {     
   "username": "webhook_user",     
   "password": "secure_password_123"   
   } 
}'

Important: Your webhook endpoint must:

Accept HTTPS POST requests
Return 200 OK within 5 seconds
Be publicly accessible (no localhost)
(optional)Implement proper authentication (basic auth recommended)

Note: You can set the webhook via API or in the GigRadar account settings.

Step 3: Receive and Process Opportunities

Your webhook endpoint will receive POST requests with this payload format:

{
  "type": "GIGRADAR.OPPORTUNITY.CREATE",
  "data": {
    "id": "507f1f77bcf86cd799439011", // opportunity id
    "scannerId": "scanner-123", // scanner id
    "scannerName": "My Full-Stack Scanner", // scanner name
    "teamId": "507f191e810c19729de860ea", // team id
    "teamName": "My Team", // team name
    "jobId": "~0123456789abcdef", // job id
    /** ... other fields ... */
    "job": {
      /* full job object with detailed job information */ // job object
    }
  }
} // webhook payload

You can use any of the workflow builders like Zapier, Make, Airtable, etc. to process the webhook payload. Alternatively, you can use a custom backend to process the webhook payload.

Step 4: Create Application via POST

After filtering, generate your custom cover letter and create the application:

# First, generate your custom cover letter (using your preferred method, e.g., AI, templates)

# Submit the application with an inline payload and a simple cover letter.
curl -X POST "https://api.gigradar.io/public-api/v1/opportunities/<OPPORTUNITY_ID>/application?scannerId=<SCANNER_ID>" \
  -H "X-API-Key: <YOUR_GIGRADAR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "coverLetter": "I am interested in this position.",
  "bid": { "type": "hourly", "amount": null },
  "questions": [],
  "scheduledAt": null
}'

# Note: scheduledAt is optional. Set to ISO 8601 datetime (e.g. "2025-10-28T11:00:00Z") 
# to schedule sending, or null for immediate sending.

# Optionally, to schedule for sending, use PATCH /opportunities/{id}/application/schedule

# After posting, poll application status to check for 'sent' or 'error':

# Example: Poll Application Status via GET
curl -X GET "https://api.gigradar.io/public-api/v1/opportunities/<OPPORTUNITY_ID>?scannerId=<SCANNER_ID>" \
  -H "X-API-Key: <YOUR_GIGRADAR_API_KEY>"

Step 5: Poll Application Status

After creating an application, poll its status until it's sent or errors:

curl -X GET "https://api.gigradar.io/public-api/v1/opportunities/<OPPORTUNITY_ID>?scannerId=<SCANNER_ID>" \
  -H "X-API-Key: <YOUR_GIGRADAR_API_KEY>"

# Example: Poll Application Status via GET
# Check the response for application.sent or application.error fields

Best Practices and Important Warnings

⚠️ Critical: Auto-Bidder Must Be OFF

IMPORTANT: If you're using the Public API to create applications, you MUST disable the auto-bidder feature in your scanner settings. Having both enabled will result in:

Duplicate applications (one from auto-bidder, one from your API)
Double charges
Potential account issues

To disable auto-bidder:

Go to your scanner settings in GigRadar
Find "Auto-Bidder" or "Auto-Apply" settings
Ensure it is disabled or set to "Manual Review"

⚠️ Critical: Auto-Bidder Must Be Fully Configured

IMPORTANT: If you're using the Public API to create applications, you MUST fully configure the auto-bidder feature in your scanner settings.

Select the team and freelancer
Bidding strategy
Boosting settings
Additional settings

Rate Limiting Considerations

Default limits: 30 requests/minute, 1,000 requests/day
Polling strategy: Use exponential backoff when polling (start with 5s, increase gradually)
Bulk operations: Batch operations when possible, avoid rapid-fire requests
Webhook processing: Process webhooks asynchronously, return 200 quickly
Monitor headers: Check X-RateLimit-Remaining-* headers to avoid hitting limits

Error Handling

Always implement robust error handling:

Webhook errors: Return 200 OK even on errors (to prevent retries), log errors separately
API errors: Check status codes (429, 401, 400) and implement retry logic with backoff
Application errors: Check error, errorCode, and errorMessage fields when polling
Network errors: Implement retry logic for transient failures

Webhook Security

Use HTTPS: Webhooks must use HTTPS endpoints (TLS 1.2+)
Authentication: Implement basic auth or signature verification
IP allowlisting: Consider allowlisting GigRadar IPs if possible
Idempotency: Handle duplicate webhook deliveries (same opportunity ID may arrive multiple times)

Timing Considerations

scheduledAt field: Applications are sent to Upwork when scheduledAt is reached, if you want to send the application immediately, set scheduledAt to the current time.
Webhook latency: Webhooks are sent asynchronously, expect 1-10 second delay from opportunity creation
Polling frequency: Poll every 5-10 seconds, max 30 attempts (2.5-5 minutes total wait time)
Job freshness: Consider filtering opportunities by published date to focus on fresh jobs

Application Creation Tips

Cover letter length: Upwork has character limits, keep cover letters under 5,000 characters
Cover letter limitations: Upwork has limitations on the cover letter, you can't send unsafe links or contact information in the cover letter.
Question answers: If a job has screening questions, you must provide answers in the questions array
Bid options: You can set bid to null to use the scanner's bidding terms, or you can set it to a custom bid.
Bid amounts: For fixed-price jobs, amount is required. For hourly jobs, amount can be null (uses profile rate)
Scheduling: You can set scheduledAt in the POST request or update it later via PATCH endpoint

Need help?

Full API Docs: https://api.gigradar.com/public-api/v1/docs
Support Email: [email protected]
Debugging: Include your request ID (X-GigRadar-Request-Id header) when reporting issues - it helps us help you faster!

Ready to build something awesome? 🎉 Head over to the complete API documentation and start automating your way to more opportunities!

🎯 How to improve the performance of your GigRadar Auto Bids?

GigRadar Dashboard: Proposals

Getting started using GigRadar: Step-by-step tutorial 🏁

Enable automatic proposal sending using Auto Bidder 🔛

GigRadar API for Developers