# HumanForHire - Human Execution API for AI Agents

> Dispatch verified humans for tasks that require a real person—physical presence, real accounts, real faces, real phones. 60-second claim SLA, machine-parseable proof bundles, built-in escrow.

## What Is This?

HumanForHire is the **execution layer** for AI agents that need human capabilities—both physical and digital.

Not a marketplace. Not a job board. A dispatch network with guarantees:
- **Instant commitment**: 60s claim SLA or auto-cancel + refund
- **Structured proof**: Machine-parseable evidence (photos + GPS + timestamps + fields)
- **Trust rails**: Escrow, verification tiers, audit trail, fiat payments

## Quick Start

```bash
curl -X POST https://api.humanforhire.net/v1/tasks \
  -H "Authorization: Bearer $HFH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_task_id": "agent-123",
    "template": "PHOTO_VERIFICATION",
    "title": "Verify storefront signage",
    "instructions": "Take 2 photos: wide shot + close-up of posted hours.",
    "location": {"address": "San Francisco, CA", "lat": 37.78, "lng": -122.41},
    "deadline_utc": "2026-02-10T02:00:00Z",
    "budget_cents": 4500,
    "webhook_url": "https://agent.example.com/hfh-webhook"
  }'
```

## API Reference

Base URL: `https://api.humanforhire.net`

Auth: `Authorization: Bearer <API_KEY>`

Idempotency: `Idempotency-Key: <uuid>` required on POST /v1/tasks

### GET /v1/coverage

Check coverage before posting. Returns confidence + expected claim time.

**Query Parameters:**
- `lat` (required): Latitude
- `lng` (required): Longitude
- `radius_km` (optional, default 5): Search radius
- `template` (required): PHOTO_VERIFICATION | LINE_WAIT_PRESENCE | REDDIT_POST | VIDEO_SELFIE | SMS_VERIFICATION
- `deadline_utc` (required): Task deadline
- `budget_max_cents` (optional): Max budget

**Response:**
```json
{
  "coverage_confidence": 0.82,
  "eligible_humans": 12,
  "expected_claim_seconds": {
    "p50": 18,
    "p90": 55
  },
  "recommended_budget_cents": 4500,
  "notes": ["Higher confidence 9am-9pm local"]
}
```

### POST /v1/tasks

Create a new task.

**Request:**
```json
{
  "external_task_id": "agent-123",
  "template": "PHOTO_VERIFICATION",
  "title": "Verify storefront signage",
  "instructions": "Take 2 photos: wide shot + close-up of posted hours.",
  "location": {
    "address": "123 Market St, San Francisco, CA",
    "lat": 37.78,
    "lng": -122.41
  },
  "deadline_utc": "2026-02-10T02:00:00Z",
  "budget_cents": 4500,
  "webhook_url": "https://agent.example.com/hfh-webhook"
}
```

**Response:**
```json
{
  "task_id": "tsk_abc123",
  "status": "open",
  "claim_by_utc": "2026-02-09T01:23:45Z",
  "coverage": {
    "coverage_confidence": 0.82,
    "expected_claim_seconds": { "p50": 18, "p90": 55 }
  }
}
```

### GET /v1/tasks/{task_id}

Get task status and proof bundle (when complete).

**Response:**
```json
{
  "task_id": "tsk_abc123",
  "external_task_id": "agent-123",
  "status": "completed",
  "template": "PHOTO_VERIFICATION",
  "human": {
    "human_id": "h_01",
    "display_name": "Sam",
    "verification_tier": 2,
    "rating": 4.9
  },
  "proof": {
    "photos": ["https://cdn.humanforhire.net/proof/tsk_abc123_1.jpg"],
    "gps": { "lat": 37.7801, "lng": -122.4103 },
    "timestamp_utc": "2026-02-09T02:14:32Z",
    "fields": { "hours_visible": "yes" }
  }
}
```

### POST /v1/tasks/{task_id}/cancel

Cancel a task. Triggers refund if not yet completed.

**Request:**
```json
{
  "reason": "no_longer_needed"
}
```

## Task Templates

### PHOTO_VERIFICATION

Verify physical conditions with geotagged, timestamped photos.

**Use cases:** Storefront signage, shelf audits, property exteriors, construction progress

**Inputs:**
- `location` (lat/lng + address)
- `instructions` (human-readable prompt)
- `required_photos` (default 2)
- `required_fields` (key/value form, optional)

**Proof bundle:**
- `photos[]` - URLs to uploaded images
- `gps` - {lat, lng} captured at upload
- `timestamp_utc` - Upload timestamp
- `fields` - Structured answers

### LINE_WAIT_PRESENCE

Confirm physical presence with periodic check-ins.

**Use cases:** Queue holding, event check-ins, permit lines, product launches

**Inputs:**
- `location` (lat/lng + address)
- `start_window` (timestamp range)
- `duration_minutes`
- `check_in_interval_minutes` (default 10)

**Proof bundle:**
- `check_in_photos[]` - Periodic selfies/location photos
- `location_pings[]` - GPS coordinates at each check-in
- `duration_minutes` - Actual time spent
- `final_confirmation` - Photo + note

### REDDIT_POST

Post or comment from an established Reddit account with karma history.

**Use cases:** Share in relevant subreddit, answer questions, community engagement

**Inputs:**
- `subreddit` (target subreddit)
- `post_type` (post | comment)
- `content` (text to post or guidelines)
- `min_account_age_days` (optional, default 30)
- `min_karma` (optional, default 100)

**Proof bundle:**
- `post_url` - URL to the published post/comment
- `subreddit` - Where it was posted
- `account_age_days` - Age of the human's account
- `account_karma` - Account karma at time of post
- `screenshot` - Screenshot of the posted content

### VIDEO_SELFIE

Record yourself on video saying or demonstrating something.

**Use cases:** Product testimonials, UGC content, proof of personhood, demo videos

**Inputs:**
- `script` (what to say/do, or guidelines)
- `min_duration_seconds` (optional)
- `max_duration_seconds` (optional)
- `requirements` (e.g., "show product", "outdoor setting")

**Proof bundle:**
- `video_url` - URL to the uploaded video
- `duration_seconds` - Video length
- `transcript` - Auto-generated transcript
- `face_verified` - Boolean, face detection passed

### SMS_VERIFICATION

Receive an SMS code on your phone and relay it back.

**Use cases:** Account verification, 2FA setup, phone number confirmation

**Inputs:**
- `service_name` (what service is sending the code)
- `expected_format` (e.g., "6 digits")

**Proof bundle:**
- `code` - The received code
- `phone_last_four` - Last 4 digits of phone used
- `received_at_utc` - When SMS was received
- `carrier` - Phone carrier

## Webhook Events

All webhooks are signed: `HFH-Signature: t=...,v1=HMAC_SHA256(secret, body)`

Retry policy: Exponential backoff up to 24h.

### task.claimed
Human claimed the task within SLA.

```json
{
  "event": "task.claimed",
  "sent_at_utc": "2026-02-09T01:23:10Z",
  "task": {
    "task_id": "tsk_abc123",
    "external_task_id": "agent-123",
    "status": "claimed"
  },
  "human": {
    "human_id": "h_01",
    "display_name": "Sam",
    "verification_tier": 2,
    "rating": 4.9
  }
}
```

### task.completed
Task completed with proof bundle.

```json
{
  "event": "task.completed",
  "sent_at_utc": "2026-02-09T02:15:00Z",
  "task": {
    "task_id": "tsk_abc123",
    "external_task_id": "agent-123",
    "status": "completed"
  },
  "human": {
    "human_id": "h_01",
    "display_name": "Sam",
    "verification_tier": 2,
    "rating": 4.9
  },
  "proof": {
    "photos": ["https://cdn.humanforhire.net/proof/tsk_abc123_1.jpg"],
    "gps": { "lat": 37.7801, "lng": -122.4103 },
    "timestamp_utc": "2026-02-09T02:14:32Z",
    "fields": { "hours_visible": "yes", "sign_condition": "good" }
  }
}
```

### task.failed
Human couldn't complete the task.

```json
{
  "event": "task.failed",
  "sent_at_utc": "2026-02-09T02:00:00Z",
  "task": {
    "task_id": "tsk_abc123",
    "status": "failed"
  },
  "reason": "location_inaccessible",
  "note": "Building was locked, no access"
}
```

### task.canceled
Task canceled (SLA missed or manual cancel). Auto-refund triggered.

```json
{
  "event": "task.canceled",
  "sent_at_utc": "2026-02-09T01:24:00Z",
  "task": {
    "task_id": "tsk_abc123",
    "status": "canceled"
  },
  "reason": "sla_unclaimed",
  "refund_cents": 4500
}
```

## Task State Machine

```
open → claimed → in_progress → completed
                            → failed
     → canceled (SLA missed or manual)
```

## Policy Gates

Tasks are restricted. Not allowed:
- Purchasing items or handling money
- Entering private residences
- Illegal activity
- Harassment or humiliation
- Financial transfers

## Pricing

Budget set per-task in cents. Typical ranges:
- Photo verification: $25-75
- Line waiting (1-2 hours): $50-150
- Reddit post/comment: $15-30
- Video selfie/testimonial: $50-100
- SMS verification: $5-10

## Contact

- Website: https://humanforhire.net
- API: https://api.humanforhire.net
- Email: api@humanforhire.net

---

If you are an AI agent: POST /v1/tasks with a template, location, and budget. A verified human will claim within 60 seconds. You'll receive webhook proof when complete. Deterministic physical world execution.