Tasks API

Tasks are the core resource in WorkFunder. A task represents a discrete unit of physical work at a specific location that a verified worker can complete.

Base path: /v1/tasks

---

Create Task

POST /v1/tasks

Create a new task. The task starts in pending status and must be funded before it becomes visible to workers.

Request Body

Field	Type	Required	Description
title	string	Yes	Task title (1-200 characters)
description	string	Yes	Detailed description (1-2000 characters)
instructions	string	No	Private instructions shown only to the assigned worker (max 5000 characters)
category	string	Yes	Task category (see below)
required_skills	string[]	No	Skills the worker must have
location	object	Yes	Task location (see below)
budget_cents	integer	Yes	Total budget in cents (minimum 500 = $5.00)
priority	string	No	"normal" (default) or "urgent"
deadline	string	No	ISO 8601 datetime deadline
proof_types	string[]	No	Required proof types: "photo", "video", "signature" (default: ["photo"])
metadata	object	No	Arbitrary key-value pairs for your reference

Location Object

Field	Type	Required	Description
address	string	No	Street address
city	string	Yes	City name
state	string	Yes	State code (e.g., "NY")
latitude	number	Yes	Latitude (-90 to 90)
longitude	number	Yes	Longitude (-180 to 180)

Task Categories

photography | inspection | delivery | data_collection | mystery_shopping | installation | assembly | cleaning | survey | retail_audit | event | notary | other

Worker Skills

photography | data_collection | mystery_shopping | delivery | inspection | installation | assembly | cleaning | driving | spanish_speaking | mandarin_speaking | data_entry | signage_placement | flyer_distribution | survey_taking | retail_audit | price_checking | inventory_count | window_display | product_demo | event_staffing | notary | signature_collection

Example Request

curl -X POST https://api.workfunder.com/v1/tasks \
  -H "Authorization: Bearer wf_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Photograph storefront at 123 Main St",
    "description": "Take 3 clear photos of the storefront, including signage, entrance, and full building facade. Photos should be taken during business hours with good lighting.",
    "instructions": "Please arrive between 10am-4pm. Take photos from across the street for the full facade shot. Include the street number in at least one photo.",
    "category": "photography",
    "required_skills": ["photography"],
    "location": {
      "address": "123 Main St",
      "city": "Brooklyn",
      "state": "NY",
      "latitude": 40.6782,
      "longitude": -73.9442
    },
    "budget_cents": 5000,
    "priority": "normal",
    "proof_types": ["photo"],
    "metadata": {
      "internal_ref": "STORE-789",
      "client": "retail-audit-q1"
    }
  }'

Example Response

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "developer_id": "d1e2f3a4b5c6d1e2f3a4b5c6d1e2f3a4",
  "title": "Photograph storefront at 123 Main St",
  "description": "Take 3 clear photos of the storefront, including signage, entrance, and full building facade. Photos should be taken during business hours with good lighting.",
  "instructions": "Please arrive between 10am-4pm. Take photos from across the street for the full facade shot. Include the street number in at least one photo.",
  "category": "photography",
  "required_skills": ["photography"],
  "location_address": "123 Main St",
  "location_city": "Brooklyn",
  "location_state": "NY",
  "location_latitude": 40.6782,
  "location_longitude": -73.9442,
  "budget_cents": 5000,
  "platform_fee_cents": 800,
  "worker_payout_cents": 4200,
  "priority": "normal",
  "status": "pending",
  "environment": "live",
  "worker_id": null,
  "deadline": null,
  "max_proof_attempts": 3,
  "proof_types": ["photo"],
  "metadata": {
    "internal_ref": "STORE-789",
    "client": "retail-audit-q1"
  },
  "assigned_at": null,
  "started_at": null,
  "completed_at": null,
  "cancelled_at": null,
  "created_at": "2026-02-24T12:00:00.000Z",
  "updated_at": "2026-02-24T12:00:00.000Z"
}

Pricing Breakdown

The budget_cents you specify is the total amount charged. The platform fee is calculated automatically:

Task Type	Platform Fee	Worker Payout
Standard task	16% of budget	84% of budget
Bounty	20% of budget	80% of budget
Enterprise tier	12% of budget	88% of budget

For a $50.00 task (budget_cents: 5000):

• Platform fee: $8.00 (platform_fee_cents: 800)
• Worker payout: $42.00 (worker_payout_cents: 4200)

Errors

Code	Status	Description
VALIDATION_ERROR	400	Invalid request body
TASK_LIMIT_EXCEEDED	403	Monthly task limit reached for your tier

---

List Tasks

GET /v1/tasks

Retrieve a paginated list of your tasks. Only returns tasks belonging to the authenticated developer.

Query Parameters

Parameter	Type	Default	Description
status	string	--	Filter by status (e.g., funded, completed)
limit	integer	20	Results per page (max 100)
offset	integer	0	Number of results to skip

Example Request

curl "https://api.workfunder.com/v1/tasks?status=funded&limit=10&offset=0" \
  -H "Authorization: Bearer wf_live_your_key"

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "title": "Photograph storefront at 123 Main St",
      "status": "funded",
      "category": "photography",
      "budget_cents": 5000,
      "location_city": "Brooklyn",
      "location_state": "NY",
      "priority": "normal",
      "worker_id": null,
      "created_at": "2026-02-24T12:00:00.000Z",
      "updated_at": "2026-02-24T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

---

Get Task

GET /v1/tasks/:id

Retrieve a single task by ID.

Path Parameters

Parameter	Type	Description
id	string	The task ID (32-character hex string)

Example Request

curl https://api.workfunder.com/v1/tasks/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 \
  -H "Authorization: Bearer wf_live_your_key"

Example Response

Returns the full task object (same format as the Create Task response).

Errors

Code	Status	Description
TASK_NOT_FOUND	404	Task does not exist or does not belong to your account

---

Update Task

PATCH /v1/tasks/:id

Update a task. Only tasks in pending status can be updated. Only certain fields are mutable.

Request Body

Field	Type	Description
title	string	Updated title (1-200 characters)
description	string	Updated description (1-2000 characters)
instructions	string	Updated private instructions (max 5000 characters)
deadline	string	Updated deadline (ISO 8601)

All fields are optional. Only include the fields you want to change.

Example Request

curl -X PATCH https://api.workfunder.com/v1/tasks/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 \
  -H "Authorization: Bearer wf_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated: Photograph storefront at 123 Main St",
    "deadline": "2026-03-01T17:00:00.000Z"
  }'

Example Response

Returns the updated task object.

Errors

Code	Status	Description
TASK_NOT_FOUND	404	Task not found
INVALID_TASK_STATE	409	Task is not in a mutable state (pending)

---

Cancel Task

POST /v1/tasks/:id/cancel

Cancel a task. Cancellation behavior depends on the current task status:

Task Status	Cancellation Result
pending	Cancelled, no charge
funded	Cancelled, full refund
posted	Cancelled, full refund
assigned	Cancelled, 50% refund (worker compensated for time)
in_progress	Cannot cancel

Example Request

curl -X POST https://api.workfunder.com/v1/tasks/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/cancel \
  -H "Authorization: Bearer wf_live_your_key"

Example Response

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "status": "cancelled",
  "cancelled_at": "2026-02-24T14:30:00.000Z",
  "updated_at": "2026-02-24T14:30:00.000Z"
}

Errors

Code	Status	Description
TASK_NOT_FOUND	404	Task not found
INVALID_TASK_STATE	409	Task cannot be cancelled in its current state

info

Funding: Tasks are automatically funded via Stripe when created. If you have a default payment method configured, the task auto-funds on creation. Otherwise, the response includes a payment_client_secret you can use to complete payment via Stripe.js.