MicroMatch Developer API

MicroMatch REST API v1

Base URL

https://trymicromatch.com

Authentication

Public endpoints require no tokens. Protected endpoints use HTTP session cookies or session headers.

Content Safety

Automated moderation scans titles, descriptions, and claim notes. Violations return 400 Bad Request.

GET /api/tasks

Retrieve public active task listings for volunteers and directory views.

Query Parameters

Parameter	Type	Req	Description
`duration`	number	Opt	Max duration in mins (e.g. 15, 30)
`lang`	string	Opt	Target ISO lang code (e.g. es, fr)

Response

200 OK

[
  {
    "id": "task_89f2a",
    "title": "Proofread Disaster Relief Guidelines",
    "shortDescription": "Review 3 pages of translated emergency response documentation.",
    "tags": [
      "documentation",
      "disaster-relief",
      "translation"
    ],
    "estimatedMinutes": 15,
    "language": "English",
    "isVerified": true
  }
]

POST /api/tasks

Create a new micro-task listing. Submissions undergo automated content safety checks.

Note: Task creation requires an active NGO session. Content safety moderation flags unsafe text.

Request Body

{
  "title": "Translate Sanitation Infographic",
  "shortDescription": "Translate a single-page hygiene graphic from English to Spanish.",
  "description": "Full text and context file link for translators...",
  "language": "Spanish",
  "tags": [
    "translation",
    "graphics",
    "health"
  ],
  "estimatedMinutes": 20,
  "maxVolunteers": 2,
  "deadline": "2026-08-30T00:00:00Z"
}

Response

201 Created

{
  "id": "task_99b1c",
  "orgId": "user_ngo_402",
  "title": "Translate Sanitation Infographic",
  "shortDescription": "Translate a single-page hygiene graphic from English to Spanish.",
  "description": "Full text and context file link for translators...",
  "language": "Spanish",
  "tags": [
    "translation",
    "graphics",
    "health"
  ],
  "estimatedMinutes": 20,
  "status": "active",
  "maxVolunteers": 2,
  "deadline": "2026-08-30T00:00:00Z",
  "isVerified": true,
  "lastActivityAt": "2026-07-31T08:30:00Z"
}

PATCH /api/tasks/[id]

Update task status (active, completed, paused), max volunteers, or deadline.

Request Body

{
  "status": "completed",
  "maxVolunteers": 5,
  "deadline": "2026-09-15T00:00:00Z"
}

Response

200 OK

{
  "success": true
}

DELETE /api/tasks/[id]

Delete or archive an existing task listing.

Response

200 OK

{
  "success": true
}

POST /api/tasks/[id]/claim

Claim an active task and submit proof of completion with optional notes.

Request Body

{
  "proofUrl": "https://github.com/org/repo/pull/104",
  "notes": "Completed all translation strings and checked alt text."
}

Response

201 Created

{
  "id": "claim_34a1",
  "taskId": "task_89f2a",
  "userId": "user_vol_77",
  "proofUrl": "https://github.com/org/repo/pull/104",
  "notes": "Completed all translation strings and checked alt text.",
  "status": "pending",
  "createdAt": "2026-07-31T08:32:00Z"
}

GET /api/claims

Retrieve submitted task claims (volunteers see their own; NGOs see claims for their tasks).

Query Parameters

Parameter	Type	Req	Description
`status`	string	Opt	Filter: pending \| approved \| rejected
`limit`	number	Opt	Page limit (default 50, max 100)
`offset`	number	Opt	Page offset (default 0)

Response

200 OK

{
  "data": [
    {
      "id": "claim_34a1",
      "taskId": "task_89f2a",
      "userId": "user_vol_77",
      "proofUrl": "https://github.com/org/repo/pull/104",
      "notes": "Completed all translation strings.",
      "status": "pending",
      "createdAt": "2026-07-31T08:32:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  },
  "error": null
}

POST /api/claims/[id]/approve

Approve a volunteer claim, awarding XP and evaluating badge achievements.

Response

200 OK

{
  "id": "claim_34a1",
  "status": "approved",
  "badgeAwarded": true
}

POST /api/claims/[id]/reject

Reject a claim with reviewer feedback notes.

Request Body

{
  "reason": "Uploaded proof screenshot link is inaccessible."
}

Response

200 OK

{
  "status": "rejected"
}

POST /api/verifications

Submit NGO verification request with EIN and supporting document reference.

Request Body

{
  "ein": "12-3456789",
  "organizationName": "Global Education Alliance",
  "documentId": "doc_99182"
}

Response

201 Created

{
  "userId": "user_ngo_402",
  "ein": "12-3456789",
  "organizationName": "Global Education Alliance",
  "documentId": "doc_99182",
  "status": "pending",
  "submittedAt": "2026-07-31T08:00:00Z"
}

GET /api/verifications/me

Fetch the current user organization verification status.

Response

200 OK

{
  "status": "approved",
  "ein": "12-3456789",
  "organizationName": "Global Education Alliance"
}

DELETE /api/verifications/me

Cancel pending verification submission.

Response

200 OK

{
  "success": true
}

POST /api/verifications/upload

Upload official verification proof document (PDF or image).

Request Body

FormData: file (PDF, PNG, JPEG max 10MB)

Response

200 OK

{
  "fileId": "doc_99182",
  "url": "/api/verifications/user_ngo_402/document"
}

GET /api/verifications/[userId]/document

Download or inspect verification document file binary.

Response

200 OK

[Binary file stream: application/pdf or image/png]

POST /api/verifications/[userId]/approve

Approve NGO verification and mark organization tasks as Verified.

Response

200 OK

{
  "success": true,
  "verified": true
}

POST /api/verifications/[userId]/reject

Reject NGO verification request with detailed rejection reason.

Request Body

{
  "reason": "Tax ID documentation could not be verified in state database."
}

Response

200 OK

{
  "success": true
}

GET /api/badges

Get earned badges for the current user or targeted user ID.

Query Parameters

Parameter	Type	Req	Description
`userId`	string	Opt	Target user ID (defaults to current user)

Response

200 OK

[
  {
    "id": "badge_first_task",
    "name": "First Response",
    "description": "Completed your first micro-task on MicroMatch.",
    "icon": "heroicons:sparkles",
    "unlockedAt": "2026-07-28T14:20:00Z"
  }
]

GET /api/badges/manage

List custom badge templates defined by the organization.

Response

200 OK

[
  {
    "id": "badge_custom_01",
    "name": "Translation Hero",
    "description": "Awarded for completing 5 translation micro-tasks.",
    "icon": "heroicons:language",
    "triggerTag": "translation",
    "requiredCount": 5
  }
]

POST /api/badges/manage

Define a custom badge template for volunteer achievements.

Request Body

{
  "name": "Accessibility Champion",
  "description": "Awarded for completing 5 accessibility review tasks.",
  "icon": "heroicons:eye",
  "triggerTag": "accessibility",
  "requiredCount": 5
}

Response

201 Created

{
  "id": "badge_custom_02",
  "name": "Accessibility Champion",
  "description": "Awarded for completing 5 accessibility review tasks.",
  "icon": "heroicons:eye",
  "triggerTag": "accessibility",
  "requiredCount": 5,
  "orgId": "user_ngo_402"
}

DELETE /api/badges/manage

Delete a custom badge template.

Request Body

{
  "id": "badge_custom_02"
}

Response

200 OK

{
  "success": true
}

POST /api/profile/role

Switch current active account view role between Volunteer and NGO.

Request Body

{
  "role": "ngo"
}

Response

200 OK

{
  "success": true,
  "role": "ngo"
}

POST /api/profile/update

Update profile information (display name, bio, skills, organization name).

Request Body

{
  "name": "Elena Rostova",
  "bio": "Bilingual tech volunteer passionate about health accessibility.",
  "skills": [
    "Spanish Translation",
    "Proofreading",
    "UI Testing"
  ],
  "orgName": "Community Health First"
}

Response

200 OK

{
  "success": true
}

POST /api/profile/avatar

Upload user profile avatar image.

Request Body

FormData: avatar (JPEG, PNG, WEBP max 5MB)

Response

200 OK

{
  "avatarUrl": "https://trymicromatch.com/storage/avatars/user_vol_77.jpg"
}

POST /api/teams/assign

Assign a task directly to specific team members.

Request Body

{
  "taskId": "task_89f2a",
  "memberIds": [
    "user_vol_77",
    "user_vol_88"
  ]
}

Response

200 OK

{
  "success": true
}

POST /api/auth/session

Exchange provider auth token for HTTP-only session cookie.

Request Body

{
  "token": "sess_token_secure_abc123"
}

Response

200 OK

{
  "success": true
}

POST /api/auth/logout

Destroy current active authentication session.

Response

200 OK

{
  "success": true
}

← Back to Documentation