Jobs

Jobs represent tracked opportunities that match your team's trackers. Use this endpoint to build job feeds, automate workflows, and sync application status with external tools.

When no tracker_id is provided, GET /api/v1/jobs returns jobs from all AI Job Trackers available to the authenticated user's current team.

The Job Object

{
  "id": 886053,
  "job_id": "022050824509497590983",
  "title": "Senior Laravel Developer for SaaS Platform",
  "description": "We're looking for an experienced Laravel developer...",
  "job_url": "https://www.upwork.com/jobs/~022050824509497590983",
  "is_private": false,
  "time": "19 hours ago",
  "job_type": "fixed",
  "difficulty": "intermediate",
  "duration": "3_to_6_months",
  "proposals_count": 5,
  "min_hourly_rate": null,
  "max_hourly_rate": null,
  "fixed_budget": 700,
  "budget_summary": "$700.00",
  "client_city": "kiriat ono",
  "client_country": "Israel",
  "client_timezone": "Asia/Jerusalem (UTC+03:00)",
  "client_rating": "4.53",
  "client_reviews": 23,
  "client_hours": "38.00",
  "client_total_spent": 41700,
  "client_total_hires": 35,
  "client_avg_spend_per_hire": 1191.43,
  "client_active_jobs": 3,
  "client_open_jobs": 7,
  "client_payment_verified": true,
  "invites_sent": 0,
  "unanswered_invites": 0,
  "interviews": 0,
  "hired": 0,
  "open_positions": 2,
  "us_only": false,
  "relevant_score": "62.00",
  "relevant_reason": "Strong API and Laravel fit.",
  "tracker_profile_user_id": 1,
  "upwork_search_link_id": 162,
  "status": {
    "value": 1,
    "label": "Applied",
    "color": "blue",
    "user_id": 1,
    "cover_letter_text": "I have 5 years of Laravel experience...",
    "connects": 6
  },
  "skills": ["PHP", "Laravel", "API"],
  "category": "Web, Mobile \u0026 Software Dev",
  "subcategory": "Web Development",
  "created_at": "2026-05-03T06:29:09.000000Z",
  "updated_at": "2026-05-04T01:21:28.000000Z",
  "ai_job_tracker": {
    "id": 162,
    "name": "Laravel SaaS Jobs",
    "url": "https://www.upwork.com/nx/search/jobs/?q=laravel%20saas\u0026sort=recency",
    "ai_match_percentage": 70,
    "profile_user_id": 1,
    "is_active": true
  }
}

Attributes

Attribute	Type	Description
id	integer	Unique job identifier
job_id	string	External job identifier
title	string	Job title
description	string	Full job description
job_url	string	Job URL
is_private	boolean	Whether the job is invite-only
time	string	Human-readable posting age
job_type	string	fixed or hourly
difficulty	string|null	entry, intermediate, expert
proposals_count	integer|null	Current proposal count
fixed_budget	number|null	Fixed budget amount
budget_summary	string|null	Formatted budget summary
client_*	mixed	Client location, rating, spend, hire fields
us_only	boolean	Whether restricted to US freelancers
relevant_score	string|null	AI relevance score (0-100)
relevant_reason	string|null	AI explanation for relevance score
ai_job_tracker	object|null	AI Job Tracker context
status	object|null	Current user's team status
skills	array	Job skills
created_at	string	When job was tracked
updated_at	string	Last update timestamp

Status Values

Value	Label	Description
1	Applied	Application submitted
2	Viewed	Client viewed application
3	Interviewed	In interview stage
4	Hired	Hired for the job

List Jobs

GET /api/v1/jobs

Query Parameters

Parameter	Type	Default	Description
search	string	—	Search in title and description
tracker_id	integer	—	Filter by AI Job Tracker ID
profile	string	—	Filter by profile ID or all
score	string	all	Filter by AI score: excellent, good, fair, poor, unanalyzed
status	string	all	Filter by status: any, none, 1, 2, 3, 4
job_type	string	all	fixed, hourly, or all
difficulty	string	all	entry, intermediate, expert, or all
us_only	boolean	—	Filter US-only jobs
not_hired	boolean	—	Jobs with no hires yet
min_proposals	integer	—	Minimum proposal count
max_proposals	integer	—	Maximum proposal count
min_client_rating	float	—	Minimum client rating (0-5)
min_client_spent	integer	—	Minimum client spend in USD
sort_by	string	date	Sort field: date, score, proposals, rating, spent, hired
sort_order	string	desc	asc or desc
page	integer	1	Page number

Filtering Examples

High-quality unapplied jobs:

GET /api/v1/jobs?score=excellent&status=none&min_client_rating=4.5¬_hired=true

Jobs from a specific AI Job Tracker:

GET /api/v1/jobs?tracker_id=42&sort_by=date

Low competition expert jobs:

GET /api/v1/jobs?difficulty=expert&max_proposals=5&status=none

Retrieve a Job

GET /api/v1/jobs/{job}

curl -X GET "https://giguphq.com/api/v1/jobs/12345" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update Job Status

Update the application status of a job. Requires write permission.

PATCH /api/v1/jobs/{job}/status

curl -X PATCH "https://giguphq.com/api/v1/jobs/12345/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": 1,
    "cover_letter_text": "I have 5+ years of Laravel experience...",
    "connects": 6
  }'

Status Transitions

From	To	Description
0 (None)	1 (Applied)	Mark as applied
1 (Applied)	2 (Viewed)	Client viewed your proposal
2 (Viewed)	3 (Interviewed)	In interview stage
3 (Interviewed)	4 (Hired)	Got hired

Error Responses

404 Not Found:

{
  "message": "Resource not found."
}

403 Forbidden:

{
  "message": "This action is unauthorized."
}

422 Validation Error:

{
  "message": "The status field is required.",
  "errors": {
    "status": ["The status field is required."]
  }
}

Use Cases

Slack Job Alerts: Post high-quality unapplied jobs to a Slack channel every morning:

import requests
from datetime import datetime

def post_jobs_to_slack(api_token, slack_webhook):
    headers = {"Authorization": f"Bearer {api_token}"}
    params = {
        "score": "excellent",
        "status": "none",
        "min_client_rating": 4.5,
        "not_hired": True,
        "sort_by": "date",
    }
    
    response = requests.get(
        "https://giguphq.com/api/v1/jobs",
        headers=headers,
        params=params
    )
    jobs = response.json()["data"]
    
    message = f"🎯 *Top {len(jobs)} Jobs for {datetime.now().strftime('%B %d')}*\n\n"
    for job in jobs:
        message += f"• {job['title']} — "
        message += f"_{job['client_rating']}⭐ | ${job['client_total_spent']:,} spent | {job['proposals_count']} proposals_\n"
    
    requests.post(slack_webhook, json={"text": message})