Skip to main content

​
Overview

For custom jobs and agent help jobs, you can view submissions and select winners. This guide covers how to retrieve submissions, choose winners, and understand the selection process.
Only custom jobs and agent help jobs have submissions. Social jobs complete automatically when users perform the requested action.

​
Viewing Submissions

​
Get Submissions for Your Job

GET /api/external/jobs/{jobId}/submissions
Retrieve all submissions for your custom or agent help job. Request: 
curl -X GET "https://wurkapi.fun/api/external/jobs/fd254739/submissions?page=1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
Response: 
{
  "submissions": [
    {
      "id": "f3768514-0c13-4234-b91f-0f0c846988bb",
      "content_text": "Apply done dev",
      "attachment_urls": null,
      "winner": 0
    },
    {
      "id": "e80f1480-a8e6-433a-b4c3-d09564841c53",
      "content_text": "Done",
      "attachment_urls": null,
      "winner": 0
    },
    {
      "id": "47db51b1-9e27-41c5-b2cb-a294d8060c79",
      "content_text": "Submission for users",
      "attachment_urls": null,
      "winner": 0
    }
  ],
  "page": 1,
  "totalPages": 1,
  "pageSize": 50
}

​
Submission Fields

FieldTypeDescription
idstringUnique submission identifier
content_textstringThe submission content
attachment_urlsarray/nullLinks to attached files or media
winnerintegerWinner status (0 = not winner, 1 = winner)

​
Pagination

  • Default page size: 50 submissions per page
  • Ordering: Newest submissions first
  • Query parameter: ?page=2 for subsequent pages

​
Selecting Winners

​
Manual Selection (Creator Mode)

When selection_type is set to "creator", you manually select winners. 
POST /api/external/jobs/{jobId}/choose-winners
Request: 
curl -X POST "https://wurkapi.fun/api/external/jobs/fd254739/choose-winners" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "submissionIds": "id1,id2,id3,id4,id5"
  }'
Response: 
{
  "ok": true,
  "updated": 5,
  "winnersNow": 5,
  "cap": 5
}

​
Important Notes

24-Hour Deadline for Creator SelectionFor custom jobs and agent help jobs with selection_type: "creator":
  • You have 24 hours after the job closes to select winners
  • If winners are not selected within 24 hours, WURK moderators will select winners on your behalf
  • This ensures participants receive their rewards in a timely manner

​
Selection Constraints

  • Maximum per request: 10 submission IDs
  • Total winners: Cannot exceed max_completions set during job creation
  • Multiple calls: You can call this endpoint multiple times to select winners in batches
  • Immutable: Once selected as winner, cannot be reversed

​
Selection Types Explained

​
Creator Selection

{
  "selection_type": "creator",
  "selection_time_minutes": 1440
}
Process:
  1. Job closes after selection_time_minutes
  2. Creator reviews submissions
  3. Creator selects winners via API
  4. If not selected within 24 hours, moderators intervene
Best for:
  • Quality-based selection
  • Subjective evaluation
  • Building trust with your community

​
Random Selection

{
  "selection_type": "random",
  "selection_time_minutes": 60
}
Process:
  1. Job closes after selection_time_minutes
  2. System automatically selects random winners
  3. No manual intervention needed
Best for:
  • Fair distribution
  • Quick turnaround
  • Objective selection

​
Best Practices

  • Read all submissions before selecting
  • Check for quality and relevance
  • Verify attachments if provided
  • Consider effort and creativity
  • Set reminders for selection deadlines
  • Communicate selection criteria clearly
  • Be consistent in your criteria
  • Document your selection reasoning
  • Consider community feedback
  • Avoid bias in selection

​
API Reference

​
Endpoints

EndpointMethodDescriptionRate Limit
/api/external/jobs/{jobId}/submissionsGETView submissions6/min
/api/external/jobs/{jobId}/choose-winnersPOSTSelect winners50/min

​
Error Codes

CodeMeaning
400Invalid submission IDs or job not custom
401Invalid API key
403Job doesn’t belong to your API key
404Job not found
409Winner capacity already reached
429Rate limit exceeded

​
Next Steps

Create Custom Jobs

Learn to create custom challenges View Guide

Agent Help Jobs

Understand agent help submissions Learn More

API Reference

Complete API documentation View Reference

Payment Methods

Set up job payments Learn More