Proof Verification

Proof of completion is the core trust mechanism in WorkFunder. Every task requires the worker to submit verifiable evidence that the work was done at the correct location. This guide explains how the proof system works end-to-end.

How Proofs Work

When a worker completes a task, they submit proof through the WorkFunder mobile portal. The proof submission flow:

1. Worker opens the proof submission screen on their mobile device
2. Device captures GPS coordinates via navigator.geolocation.getCurrentPosition()
3. Worker takes a photo/video or provides a signature depending on the task's proof_types
4. File is uploaded to WorkFunder's secure storage (Cloudflare R2)
5. GPS is automatically validated against the task location
6. Proof enters the review queue for approval or rejection

Worker's Device                    WorkFunder API                    R2 Storage
     │                                  │                                │
     │  Capture GPS coordinates         │                                │
     │  Take photo/video                │                                │
     │                                  │                                │
     │  POST /portal/tasks/:id/proof    │                                │
     │  + file upload                   │                                │
     │  + GPS coordinates               │                                │
     │ ─────────────────────────────▶  │                                │
     │                                  │  Upload file to R2             │
     │                                  │ ─────────────────────────────▶ │
     │                                  │                                │
     │                                  │  Validate GPS (haversine)      │
     │                                  │  Calculate distance            │
     │                                  │  Set geo_valid flag            │
     │                                  │                                │
     │                                  │  Create proof record           │
     │                                  │  Update task status            │
     │                                  │  → proof_submitted             │
     │                                  │                                │
     │  ◀─────────────────────────────  │                                │
     │  { proof_id, geo_valid, dist }   │                                │

Photo and Video Requirements

Photo Proof

Requirement	Value
Formats	JPEG, PNG
Maximum file size	10 MB
GPS required	Yes
Minimum resolution	No minimum (device camera default)

Best practices for task instructions to get quality photos:

• Specify what should be visible in the photo (e.g., "Include the storefront signage")
• Mention lighting requirements (e.g., "Take during daylight hours")
• Specify the number of photos needed
• Describe angles or perspectives wanted

Video Proof

Requirement	Value
Format	MP4
Maximum file size	100 MB
GPS required	Yes
Maximum duration	No limit (bounded by file size)

Signature Proof

Requirement	Value
Format	PNG (canvas capture)
Maximum file size	1 MB
GPS required	No

Signatures are captured on-screen via the worker portal's signature pad. They are typically used for notary tasks or delivery confirmations.

GPS Validation

GPS validation is the primary mechanism for verifying that a worker was physically present at the task location.

Validation Rules

• Radius: 500 meters from the task's location_latitude / location_longitude
• Calculation: Haversine formula (great-circle distance)
• Fields set: geo_valid (boolean) and distance_from_task_meters (exact distance)

Example Distance Calculation

For a task at (40.6782, -73.9442) and a worker submitting proof from (40.6784, -73.9440):

Distance = haversine(40.6782, -73.9442, 40.6784, -73.9440)
         = ~26 meters
         → geo_valid = true (26m < 500m)

Geo-Invalid Proofs

When a proof's GPS coordinates are more than 500 meters from the task location:

• geo_valid is set to false
• The proof is not automatically rejected
• The proof is flagged in the admin review queue for manual evaluation
• The admin can approve a geo-invalid proof if the circumstances warrant it

info

GPS accuracy varies significantly. In dense urban areas (Manhattan, downtown Chicago), GPS can be off by 50-200 meters due to signal reflection from buildings. WorkFunder flags geo-invalid proofs rather than auto-rejecting them to avoid false negatives.

Why 500 Meters?

The 500-meter radius balances accuracy with practicality:

• Too tight (< 100m): Too many false negatives from GPS inaccuracy
• 500m: Confirms the worker is in the immediate area without penalizing GPS drift
• Too loose (> 1km): Does not meaningfully verify location

Approval and Rejection Flow

Approval

When a proof is approved:

1. Proof status changes to approved
2. Task status changes to completed
3. Stripe Transfer is created: worker_payout_cents sent to worker's Stripe Express account
4. Platform fee (platform_fee_cents) is captured as the Stripe application fee
5. task.completed webhook fires
6. Worker receives a "Payment on the way" notification

Rejection

When a proof is rejected:

1. Proof status changes to rejected
2. Rejection reason is recorded
3. Task status changes to proof_rejected
4. Worker is notified via email and push notification with the specific rejection reason
5. task.proof_rejected webhook fires
6. If attempts remain, the worker can resubmit

Common rejection reasons:

• Photo is blurry or out of focus
• Required elements are not visible (signage, address, etc.)
• Photo does not match the task description
• Wrong location
• Timestamp discrepancy (photo metadata suggests a different time)

Submission Attempts

Each task allows a maximum of 3 proof submission attempts. This gives workers two chances to correct issues after an initial rejection.

Attempt 1 ──▶ Rejected ("Photo is blurry")
                  │
                  ▼
Attempt 2 ──▶ Rejected ("Signage not visible")
                  │
                  ▼
Attempt 3 ──▶ Approved ──▶ Task completed, worker paid
              OR
              Rejected ──▶ Task refunded, no more attempts

What Happens When All Attempts Are Exhausted

If all 3 proof submissions are rejected:

1. Task status moves to refunded
2. Developer receives a full refund of the escrowed budget
3. Worker does not receive payment
4. The task is closed and cannot be retried

Attempt Tracking

The attempt_number field on each proof tracks which attempt it is:

{
  "id": "proof_123",
  "attempt_number": 2,
  "status": "pending",
  "type": "photo"
}

Proof Storage and Access

Storage

Proof files are stored in Cloudflare R2 with the following key format:

proofs/{task_id}/{proof_id}/{filename}

Metadata stored with each file:

• worker_id
• task_id
• submitted_at (ISO 8601)
• gps_lat, gps_lng
• content_type

Access Control

Proof files are private by default. They are accessed via signed URLs that expire after 1 hour.

• Call GET /v1/tasks/:id/proofs to get proof records with signed file_url values
• URLs expire after 1 hour -- re-fetch to get fresh URLs
• Only the task's developer can access the proof files

warning

Proof photos may contain personally identifiable information (worker photos, bystanders, license plates). Do not store or redistribute proof URLs. Your Terms of Service agreement prohibits redistribution of proof files.

Tips for Better Proof Quality

When creating tasks, write clear instructions to help workers submit approvable proofs:

1. Be specific about what to photograph. "Take a photo of the storefront" is better than "take a photo."
2. Specify the number of photos. "Take 3 photos: facade, signage, and entrance."
3. Mention lighting. "Photos should be taken during daylight hours."
4. Include reference images if possible in the task description.
5. Use the instructions field for private, detailed guidance only the assigned worker sees.