Submissions

Submissions represent files uploaded by workers for a job. Each submission is automatically scored by AI.

List Submissions

GET /v1/submissions

List submissions across all jobs for your organization.

Query Parameters:

Param	Type	Description
`job_id`	string	Filter by job ID
`status`	string	Filter: `pending_score`, `approved`, `rejected`, `retry_pending`
`min_score`	integer	Minimum AI star rating (1-5)
`start_date`	string	Start date (ISO 8601, default: 30 days ago)
`end_date`	string	End date (ISO 8601, default: now)
`limit`	integer	Max results (1-100, default 20)
`cursor`	string	Pagination cursor

Response:

{
  "object": "list",
  "data": [
    {
      "object": "submission",
      "id": "sub_01JQ...",
      "job_id": "job_01JQ...",
      "worker_id": "wkr_01JQ...",
      "status": "approved",
      "ai_star_rating": 4,
      "ai_reasoning": "Clear, well-lit photo that matches the job description. Subject is centered and in focus.",
      "file_url": "https://files.firsthandapi.com/...",
      "content_type": "image/jpeg",
      "size_bytes": 2450000,
      "submitted_at": "2026-03-16T14:30:00Z",
      "scored_at": "2026-03-16T14:30:05Z"
    }
  ],
  "has_more": true,
  "next_cursor": "..."
}

Get Submission

GET /v1/submissions/{submission_id}

Retrieve a single submission by ID, including its AI star rating and reasoning.

Response:

{
  "object": "submission",
  "id": "sub_01JQ...",
  "job_id": "job_01JQ...",
  "worker_id": "wkr_01JQ...",
  "status": "approved",
  "ai_star_rating": 4,
  "ai_reasoning": "Clear, well-lit photo that matches the job description. Subject is centered and in focus with good composition.",
  "file_url": "https://files.firsthandapi.com/...",
  "content_type": "image/jpeg",
  "size_bytes": 2450000,
  "submitted_at": "2026-03-16T14:30:00Z",
  "scored_at": "2026-03-16T14:30:05Z"
}

Submission Summary

GET /v1/submissions/summary

Returns aggregate submission metrics for your organization.

Query Parameters:

Param	Type	Description
`job_id`	string	Filter by job ID
`start_date`	string	Start date (ISO 8601, default: 30 days ago)
`end_date`	string	End date (ISO 8601, default: now)

Response:

{
  "object": "submission_summary",
  "total_submissions": 1250,
  "approved": 1050,
  "rejected": 200,
  "approval_rate": 0.84,
  "avg_ai_star_rating": 3.8,
  "by_type": [
    {
      "type": "data_collection",
      "total": 800,
      "approved": 700,
      "avg_ai_star_rating": 4.0
    }
  ]
}

Jobs API Keys