# Freelancer.com API scraper — live freelance projects, freelancer & employer profiles, design contests, and the full skill/category taxonomy from Freelancer.com: budget, bids/proposals, skills, client country, ratings and portfolio, in clean PII-safe JSON. No login required.

> Search live freelance PROJECTS on Freelancer.com by keyword, skills, category, budget/hourly band, freshness, country, and language; sorted by recency, bids, or bid-deadline. Returns title, description, budget{type,min,max,currency}, skills[], bids_count (proposals), posted_at, client_country, and url. No client PII.
> ReefAPI engine `freelancer` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/freelancer/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /freelancer/v1/search — 1 credit
Search live freelance PROJECTS on Freelancer.com by keyword, skills, category, budget/hourly band, freshness, country, and language; sorted by recency, bids, or bid-deadline. Returns title, description, budget{type,min,max,currency}, skills[], bids_count (proposals), posted_at, client_country, and url. No client PII.

**Parameters:**
- `query` (string, optional) — Keyword to match in the project title/description — e.g. 'logo design', 'React developer', 'mobile app'. Omit to browse the newest projects.
- `skills` (array, optional) — Filter to projects requiring these skill IDs (use the `skills` action to resolve a skill name → id, e.g. 'PHP'→13). Multiple = OR.
- `category` (string, optional) — Top-level category SEO slug to scope the search (see the `categories` action for the full list, e.g. 'design-media-architecture').
- `project_types` (array, optional) — Restrict to 'fixed' (fixed-price) and/or 'hourly' projects. Omit for both. [one of: fixed, hourly]
- `budget_min` (number, optional) — Minimum average project budget (in the project's own currency). For hourly projects this is the hourly-rate floor.
- `budget_max` (number, optional) — Maximum average project budget (project currency). Pair with budget_min.
- `posted_within` (enum, optional) — Only projects posted within this window (server-side from_time filter). Great for a fresh-leads feed. [one of: 1h, 24h, 3d, 7d, 30d]
- `countries` (array, optional) — Filter by project country name(s) (e.g. 'United States', 'United Kingdom'). Multiple = OR. (Unauthenticated: client identity is not exposed — only the project's listed country is used.)
- `languages` (array, optional) — Filter by the project's language code(s) (ISO-639, e.g. 'en', 'es').
- `sort` (enum, optional, default "time_updated") — Result ordering. [one of: time_updated, time_submitted, bid_count, bid_enddate]
- `limit` (integer, optional, default 30) — How many projects to return (1–100). Use `offset` to page.
- `offset` (integer, optional, default 0) — Pagination offset (0–5000); skip this many results before returning `limit`.

**Returns:** projects[]{id, title, description, type, budget{type,min,max,currency}, skills[], status, bids_count, posted_at, client_country, featured, urgent, nda, seo_url, url}, total_count, returned, offset

**Example request body:**
```json
{
  "query": "python",
  "limit": 10
}
```

### POST /freelancer/v1/project — 1 credit
Full detail for one Freelancer.com project by numeric id, project URL, or SEO slug — everything from `search` plus hourly-commitment, timeframe, qualifications, escrow status and selected-bid count. No client PII.

**Parameters:**
- `id` (string, required) — The project to fetch: a numeric project id (40505996), a project URL (https://www.freelancer.com/projects/<slug>), or the SEO slug itself.

**Returns:** project{...all search fields..., detail{hourly_info, timeframe, qualifications[], is_escrow, selected_bids_count}}

### POST /freelancer/v1/user — 1 credit
PUBLIC business profile of a Freelancer.com freelancer or employer by username/handle or id: display name, country, role, hourly rate, reputation (rating/reviews/completion/repeat-hire), skills, membership, badges, portfolio and registration year. PII (email/phone/legal-name/address) is NEVER returned.

**Parameters:**
- `username` (string, required) — The freelancer/employer to fetch: a Freelancer username (fmsiddique) or a numeric user id. Returns the PUBLIC business profile only — no email / phone / legal-name / address (those are never returned).

**Returns:** user{id, username, display_name, role, country, hourly_rate, primary_currency, registration_year, preferred_freelancer, portfolio_count, membership, skills[], badges[], reputation{...}, employer_reputation{...}, portfolio[], profile_url}

### POST /freelancer/v1/contests — 1 credit
Browse live OPEN Freelancer.com design/creative CONTESTS (accepting entries) — prize, currency, entry count, skills, and deadlines. Filter by keyword and skills.

**Parameters:**
- `query` (string, optional) — Keyword to match in the project title/description — e.g. 'logo design', 'React developer', 'mobile app'. Omit to browse the newest projects.
- `skills` (array, optional) — Filter to projects requiring these skill IDs (use the `skills` action to resolve a skill name → id, e.g. 'PHP'→13). Multiple = OR.
- `limit` (integer, optional, default 20) — How many contests to return (1–50).
- `offset` (integer, optional, default 0) — Pagination offset (0–5000); skip this many results before returning `limit`.

**Returns:** contests[]{id, title, description, prize, currency, entry_count, skills[], status, guaranteed, featured, end_at, url}, total_count, returned, offset

**Example request body:**
```json
{
  "limit": 8
}
```

### POST /freelancer/v1/skills — 1 credit
Resolve a skill name to Freelancer.com skill id(s) (for search's `skills` filter), or list the most-popular skills with their active-project counts — the marketplace's skill taxonomy.

**Parameters:**
- `query` (string, optional) — Skill name (or fragment) to resolve to Freelancer skill id(s) you can feed to search's `skills` filter (e.g. 'php' → {id:13,name:'PHP'}). Omit to list the most-popular skills.
- `limit` (integer, optional, default 60) — Max skills to return (1–200, default 60).

**Returns:** skills[]{id, name, category, seo_url, active_project_count}, returned

**Example request body:**
```json
{
  "query": "php",
  "limit": 10
}
```

### POST /freelancer/v1/categories — 1 credit
List the top-level Freelancer.com job categories (Websites/IT, Design, Writing, Mobile…) with their active-project counts — the browse taxonomy for scoping a search.

**Parameters:** none

**Returns:** categories[]{id, name, seo_url, active_project_count}, returned

## More
- Try it live, no code: https://reefapi.com/playground?engine=freelancer
- Human docs page: https://reefapi.com/docs/freelancer
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt