# Upwork Freelancer

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/upwork/freelancer` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/upwork-freelancer |

## Description

Upwork Freelancer API: fetch public freelancer profile data from a profile ID, username or URL. Returns bio, hourly rate, skills, ratings and agency info via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/upwork/freelancer' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Freelancer ~0161ad91037ca6144b

```json
{
  "url": "https://www.upwork.com/freelancers/~0161ad91037ca6144b",
  "name": "Viraj P.",
  "title": "Your technology partner in Mobile & web app development",
  "rating": 4.9,
  "skills": [
    "Website",
    "HTML",
    "CSS",
    "JavaScript",
    "HTML5",
    "CSS 3",
    "Microsoft SharePoint Administration",
    "Microsoft Office SharePoint Server"
  ],
  "user_id": "577820408753631232",
  "currency": "USD",
  "location": "Rajkot , India",
  "username": null,
  "verified": true,
  "is_agency": true,
  "profile_id": "~0161ad91037ca6144b",
  "agency_name": "AllianceTek Inc",
  "description": "View Viraj P. profile on Upwork, the world’s work marketplace. Viraj has completed 55 jobs on Upwork. Check out the complete profile and discover more professionals with the skills you need.",
  "hourly_rate": 32,
  "total_hours": 12029,
  "review_count": 38,
  "job_success_score": 100,
  "profile_image_url": "https://www.upwork.com/profile-portraits/c1dz4wEpEQLXi8mk__RogWkTguDwiFnRRaiqvTOWff1Wr6cQMs-cDGYwEQb7st3SsG"
}
```

## Documentation

## Overview
The **Upwork Freelancer API** returns public profile data from [Upwork](https://www.upwork.com) freelancer pages. Pass a **profile ID** (`~0161...`), **username**, or **full profile URL** and receive structured JSON with bio, hourly rate, skills, ratings, and agency info.

Piloterr uses **browser rendering** to load the Nuxt profile page and extract DOM metadata.

## Quickstart
```
GET https://api.piloterr.com/v2/upwork/freelancer?query=~0161ad91037ca6144b
```

Via POST:
```
POST https://api.piloterr.com/v2/upwork/freelancer
Content-Type: application/json

{"query": "https://www.upwork.com/freelancers/~0161ad91037ca6144b", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Profile ID, username, or `/freelancers/...` URL |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Response fields
| Field | Type | Description |
|---|---|---|
| `user_id` | string | Numeric Upwork user ID |
| `profile_id` | string | Profile token (e.g. `~0161...`) |
| `username` | string \| null | Public username when available |
| `name` | string | Display name |
| `title` | string | Professional headline |
| `description` | string | Profile summary |
| `location` | string \| null | Location label |
| `hourly_rate` | number \| null | Hourly rate |
| `currency` | string | ISO 4217 code |
| `rating` | number \| null | Average rating |
| `review_count` | integer \| null | Review count |
| `job_success_score` | integer \| null | Job Success Score (0–100) |
| `total_hours` | integer \| null | Total billed hours |
| `is_agency` | boolean | Agency profile flag |
| `agency_name` | string \| null | Agency name |
| `verified` | boolean | Verified badge |
| `skills` | string[] | Listed skills |
| `profile_image_url` | string \| null | Avatar URL |
| `url` | string | Canonical profile URL |

## Upwork API workflow
1. **Upwork Jobs**: discover open roles by skill
2. **Upwork Freelancer**: enrich talent profiles (this endpoint)
3. **Upwork Services**: browse Project Catalog listings by category
4. **Upwork Services Info**: fetch full catalog product details; `seller.url` links back here

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Profile not parseable |
| `500` | Rendering or parsing error |

## Notes
- Costs **2 credits** per call (browser rendering).
- Accepted paths: `/freelancers/~{id}` and `/freelancers/{username}`.

## Main use cases
- **Talent sourcing**: enrich candidate profiles before outreach
- **Vendor vetting**: check ratings, JSS, and hourly rates
- **Agency research**: identify agency-backed freelancers