Organisations API — Manage Mapping Organisations

Organisations are the top-level entities in HOT Tasking Manager. Each organisation owns teams and projects, and is administered by one or more designated managers. An organisation has a type (FREE, DISCOUNTED, or FULL_FEE) that reflects its subscription tier. The endpoints below cover full CRUD operations on organisations as well as managing the campaigns linked to them.

Organisation CRUD

List Organisations

GET /api/v2/organisations/ Returns all organisations. Optionally filter by a manager’s user ID or suppress the manager list and statistics from the response to reduce payload size. Authentication: Optional. Filtering by manager_user_id requires authentication. Query Parameters

manager_user_id

integer

Return only organisations managed by this user ID. Requires an authenticated session.

omitManagerList

boolean

default:"false"

When true, each organisation object omits the managers array.

omitOrgStats

boolean

default:"true"

When false, year-to-date statistics are appended to each organisation. Defaults to true to keep responses lightweight.

Response 200 OK

{
  "organisations": [
    {
      "organisationId": 1,
      "name": "Humanitarian OpenStreetMap Team",
      "slug": "hot",
      "logo": "https://cdn.hotosm.org/tasking-manager/uploads/hot-logo.png",
      "url": "https://hotosm.org",
      "description": "HOT works to map the most vulnerable places.",
      "type": "FREE",
      "subscriptionTier": null,
      "managers": [
        {
          "username": "hotadmin",
          "pictureUrl": "https://example.com/avatar.jpg"
        }
      ]
    }
  ]
}

curl -X GET "https://tasking-manager-api.example.com/api/v2/organisations/?omitManagerList=false" \
  -H "Authorization: Token YOUR_SESSION_TOKEN"

Create an Organisation

POST /api/v2/organisations/ Creates a new organisation. Only users with the ADMIN role can create organisations. The creating admin is automatically added to the managers list. Authentication: Required (ADMIN only) Request Body

name

string

required

Unique display name for the organisation (max 512 characters).

slug

string

URL-safe identifier. Auto-generated from name if omitted.

logo

string

URL of the organisation’s logo image.

url

string

Organisation website URL.

description

string

Short description of the organisation.

managers

array

required

Array of usernames to assign as organisation managers. The creating admin is appended automatically.

type

string

Subscription type: FREE, DISCOUNTED, or FULL_FEE. Defaults to FREE.

subscriptionTier

integer

Numeric subscription tier (admin-only field).

Response 201 Created

{ "organisationId": 7 }

Error Responses

Status	Meaning
`400`	Invalid request payload
`403`	User is not an admin

Organisation type and subscriptionTier can only be set or changed by admin users. Non-admin managers will have those fields preserved from their existing values on update.

Get Organisation by ID

GET /api/v2/organisations/{organisation_id}/ Retrieves full details of a single organisation by its numeric ID. Authentication: Optional Path Parameters

organisation_id

integer

required

The unique numeric organisation ID.

Query Parameters

omitManagerList

boolean

default:"false"

Set to true to exclude the managers list from the response.

Response 200 OK

{
  "organisationId": 1,
  "name": "Humanitarian OpenStreetMap Team",
  "slug": "hot",
  "logo": "https://cdn.hotosm.org/tasking-manager/uploads/hot-logo.png",
  "url": "https://hotosm.org",
  "description": "HOT works to map the most vulnerable places.",
  "type": "FREE",
  "subscriptionTier": null,
  "managers": [
    {
      "username": "hotadmin",
      "pictureUrl": "https://example.com/avatar.jpg"
    }
  ]
}

Get Organisation by Slug

GET /api/v2/organisations/{slug}/ Retrieves a single organisation using its URL slug instead of its numeric ID. Useful for constructing human-readable links. Authentication: Optional Path Parameters

slug

string

required

The URL-safe slug for the organisation (e.g. hot).

Query Parameters

omitManagerList

boolean

default:"false"

Set to true to exclude the managers list.

Response 200 OK — same shape as Get Organisation by ID.

Get Organisation Statistics

GET /api/v2/organisations/{organisation_id}/statistics/ Returns project and active-task statistics for the organisation. Authentication: Optional Path Parameters

organisation_id

integer

required

The unique numeric organisation ID.

Response 200 OK

organisationId

integer

ID of the organisation.

projects

object

Aggregate project counts (published, draft, archived).

activeTasks

object

Aggregate counts of tasks by status across all published projects.

Update an Organisation

PATCH /api/v2/organisations/{organisation_id}/ Updates fields on an existing organisation. The requesting user must be an organisation admin or a platform admin. Authentication: Required (org admin or ADMIN) Path Parameters

organisation_id

integer

required

The unique numeric organisation ID.

Request Body — all fields are optional

name

string

New display name.

slug

string

New URL slug.

logo

string

New logo URL.

url

string

Updated website URL.

description

string

Updated description.

managers

array

Replacement list of manager usernames. Existing managers not included in this list will be removed.

type

string

FREE, DISCOUNTED, or FULL_FEE. Admin-only — ignored for non-admin requests.

subscriptionTier

integer

Numeric tier. Admin-only — ignored for non-admin requests.

Response 200 OK

{ "Status": "Updated" }

Delete an Organisation

DELETE /api/v2/organisations/{organisation_id}/ Permanently deletes an organisation. The organisation must have no associated projects or teams before it can be removed. Authentication: Required (org admin or ADMIN) Path Parameters

organisation_id

integer

required

The unique numeric organisation ID.

Response 200 OK

{ "Success": "Organisation deleted" }

Error Responses

Status	Meaning
`401`	Missing or invalid token
`403`	User is not an org admin or the organisation still has projects
`404`	Organisation not found

An organisation cannot be deleted while it still owns projects. Remove or archive all projects before attempting deletion.

Organisation Campaigns

Campaigns can be linked to organisations to group thematically related mapping efforts. The association is many-to-many: a campaign can belong to multiple organisations and vice versa.

List Campaigns for an Organisation

GET /api/v2/organisations/{organisation_id}/campaigns/ Returns all campaigns associated with the given organisation. Authentication: Not required Path Parameters

organisation_id

integer

required

ID of the organisation.

Response 200 OK

{
  "campaigns": [
    { "id": 3, "name": "West Africa Flood Response 2024" },
    { "id": 7, "name": "Missing Maps" }
  ]
}

Link a Campaign to an Organisation

POST /api/v2/organisations/{organisation_id}/campaigns/{campaign_id}/ Associates an existing campaign with the specified organisation. The requesting user must be an organisation manager. Authentication: Required (org manager) Path Parameters

organisation_id

integer

required

ID of the organisation.

campaign_id

integer

required

ID of the campaign to link.

Response 200 OK

{
  "Success": "campaign with id 3 assigned for organisation with id 1"
}

Error Responses

Status	Meaning
`400`	Campaign is already linked to this organisation
`403`	User is not an org manager

Unlink a Campaign from an Organisation

DELETE /api/v2/organisations/{organisation_id}/campaigns/{campaign_id}/ Removes the association between a campaign and an organisation. Does not delete the campaign itself. Authentication: Required (org manager) Path Parameters

organisation_id

integer

required

ID of the organisation.

campaign_id

integer

required

ID of the campaign to unlink.

Response 200 OK

{ "Success": "Organisation and campaign unassociated successfully" }

Data Models

OrganisationType — FREE | DISCOUNTED | FULL_FEE

organisationId

integer

Unique numeric identifier.

name

string

Display name (unique, max 512 characters).

slug

string

URL-safe identifier derived from the name.

logo

string

URL pointing to the organisation logo.

url

string

Organisation website.

type

string

Subscription type: FREE, DISCOUNTED, or FULL_FEE.

managers

array

List of manager objects, each containing username and pictureUrl.

Overview

Resources

Organisations API — Manage Mapping Organisations

Organisation CRUD

List Organisations

Create an Organisation

Get Organisation by ID

Get Organisation by Slug

Get Organisation Statistics

Update an Organisation

Delete an Organisation

Organisation Campaigns

List Campaigns for an Organisation

Link a Campaign to an Organisation

Unlink a Campaign from an Organisation

Data Models

Build docs developers (and LLMs) love

Overview

Resources

Documentation Index

​Organisation CRUD

​List Organisations

​Create an Organisation

​Get Organisation by ID

​Get Organisation by Slug

​Get Organisation Statistics

​Update an Organisation

​Delete an Organisation

​Organisation Campaigns

​List Campaigns for an Organisation

​Link a Campaign to an Organisation

​Unlink a Campaign from an Organisation

​Data Models

Build docs developers (and LLMs) love

Organisation CRUD

List Organisations

Create an Organisation

Get Organisation by ID

Get Organisation by Slug

Get Organisation Statistics

Update an Organisation

Delete an Organisation

Organisation Campaigns

List Campaigns for an Organisation

Link a Campaign to an Organisation

Unlink a Campaign from an Organisation

Data Models