Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hotosm/tasking-manager/llms.txt

Use this file to discover all available pages before exploring further.

Campaigns are thematic labels that can be applied across many projects and organisations, allowing coordinators to track mapping progress for a humanitarian response, a research initiative, or any other sustained effort. Creating or modifying a campaign requires the authenticated user to manage at least one organisation. Reading campaign data is public and requires no authentication.

​
Campaign CRUD

​
List All Campaigns


GET /api/v2/campaigns/ Returns every campaign in the system. No filtering is currently supported at this endpoint; use the organisation or project sub-resources to scope results. Authentication: Not required Response 200 OK 
{
  "campaigns": [
    { "id": 1, "name": "Missing Maps" },
    { "id": 2, "name": "West Africa Flood Response 2024" },
    { "id": 3, "name": "OpenCities Africa" }
  ]
}

curl -X GET https://tasking-manager-api.example.com/api/v2/campaigns/

​
Create a Campaign


POST /api/v2/campaigns/ Creates a new campaign. The authenticated user must be the manager of at least one organisation. Authentication: Required (organisation manager) Request Body
​
name
string
required
Unique name for the campaign. Must not be an empty string.
URL of a logo image to display with the campaign.
​
url
string
External URL for more information about the campaign.
​
description
string
A free-text description of the campaign’s scope and goals.
​
organisations
array
Array of organisation IDs to associate with the campaign on creation.
Response 201 Created 
{ "campaignId": 5 }
Error Responses
StatusMeaning
403User does not manage any organisation
409A campaign with this name already exists
curl -X POST https://tasking-manager-api.example.com/api/v2/campaigns/ \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "West Africa Flood Response 2024",
    "logo": "https://example.com/campaign-logo.png",
    "url": "https://www.hotosm.org/campaigns/west-africa-flood-2024",
    "description": "Coordinated mapping response to flooding events in West Africa.",
    "organisations": [1, 4]
  }'

​
Get Campaign by ID


GET /api/v2/campaigns/{campaign_id}/ Retrieves full details of a single campaign, including its linked organisations. Authentication: Not required Path Parameters
​
campaign_id
integer
required
The unique numeric campaign ID.
Response 200 OK 
{
  "id": 5,
  "name": "West Africa Flood Response 2024",
  "logo": "https://example.com/campaign-logo.png",
  "url": "https://www.hotosm.org/campaigns/west-africa-flood-2024",
  "description": "Coordinated mapping response to flooding events in West Africa.",
  "organisations": [
    {
      "organisationId": 1,
      "name": "Humanitarian OpenStreetMap Team",
      "slug": "hot",
      "logo": "https://cdn.hotosm.org/tasking-manager/uploads/hot-logo.png",
      "url": "https://hotosm.org"
    }
  ]
}

​
Update a Campaign


PATCH /api/v2/campaigns/{campaign_id}/ Updates one or more fields on an existing campaign. The authenticated user must manage at least one organisation. Authentication: Required (organisation manager) Path Parameters
​
campaign_id
integer
required
The unique numeric campaign ID.
Request Body — all fields are optional
​
name
string
New campaign name. Must be unique across all campaigns.
​
logo
string
Updated logo URL.
​
url
string
Updated external URL.
​
description
string
Updated description.
​
organisations
array
Replacement list of organisation IDs to associate with the campaign.
Response 200 OK 
{ "Success": "Campaign 5 updated" }
Error Responses
StatusMeaning
400Campaign name already exists
403User does not manage any organisation
404Campaign not found

​
Delete a Campaign


DELETE /api/v2/campaigns/{campaign_id}/ Permanently deletes a campaign. The requesting user must manage at least one organisation. Authentication: Required (organisation manager) Path Parameters
​
campaign_id
integer
required
The unique numeric campaign ID.
Response 200 OK 
{ "Success": "Campaign deleted" }
Error Responses
StatusMeaning
403User does not manage any organisation
404Campaign not found

​
Message All Campaign Contributors


POST /api/v2/campaigns/{campaign_id}/actions/message-contributors/ Sends an in-app message to every user who has contributed to any project in the campaign. This operation is dispatched asynchronously as a background task. Only platform admins may use this endpoint. Authentication: Required (ADMIN only) Path Parameters
​
campaign_id
integer
required
ID of the campaign.
Request Body
​
subject
string
required
Subject line of the message. Must not be empty.
​
message
string
required
Body text of the message. Must not be empty.
Response 200 OK 
{ "Success": "Message sent successfully" }
This endpoint is restricted to admins and triggers a bulk notification to potentially thousands of users. Use it with care.

​
Project–Campaign Associations

Campaigns can be linked to individual projects independently of the organisation-level campaign associations. Project managers use these endpoints to tag their projects with one or more campaigns.

​
List Campaigns for a Project


GET /api/v2/projects/{project_id}/campaigns/ Returns all campaigns associated with a given project. Authentication: Not required Path Parameters
​
project_id
integer
required
ID of the project.
Response 200 OK 
{
  "campaigns": [
    { "id": 1, "name": "Missing Maps" },
    { "id": 5, "name": "West Africa Flood Response 2024" }
  ]
}

​
Add a Campaign to a Project


POST /api/v2/projects/{project_id}/campaigns/{campaign_id}/ Links a campaign to a project. The requesting user must be a project manager for the specified project. Authentication: Required (project manager) Path Parameters
​
project_id
integer
required
ID of the project.
​
campaign_id
integer
required
ID of the campaign to link.
Response 200 OK 
{
  "Success": "campaign with id 5 assigned successfully for project with id 12"
}
Error Responses
StatusMeaning
400Campaign is already assigned to this project
403User is not a project manager

​
Remove a Campaign from a Project


DELETE /api/v2/projects/{project_id}/campaigns/{campaign_id}/ Removes the association between a campaign and a project. Does not delete the campaign. Authentication: Required (project manager) Path Parameters
​
project_id
integer
required
ID of the project.
​
campaign_id
integer
required
ID of the campaign to unlink.
Response 200 OK 
{ "Success": "Campaigns Deleted" }
Error Responses
StatusMeaning
400Invalid request.
403User is not a project manager

​
Data Models

​
id
integer
Unique numeric identifier for the campaign.
​
name
string
Human-readable campaign name (must be unique).
​
logo
string
URL of the campaign logo image.
​
url
string
External URL with additional campaign information.
​
description
string
Free-text description of the campaign.
​
organisations
array
List of organisation DTOs associated with this campaign. Each item includes organisationId, name, slug, logo, and url.
When listing campaigns from GET /api/v2/campaigns/, only id and name are returned for each item. Fetch GET /api/v2/campaigns/{campaign_id}/ to retrieve full details including linked organisations.

Build docs developers (and LLMs) love

Get started for freeTalk to us