Users API — Profiles, Statistics, and Task History

Tasking Manager users are authenticated via OpenStreetMap OAuth. Each user profile stores their mapping level, role, notification preferences, social links, and contribution statistics. The endpoints below cover profile retrieval, self-service profile updates, task history, contribution statistics, and admin-level role management. All authenticated endpoints require an Authorization: Token <session_token> header. The API base path is /api/v2.

User Resources

Get User by ID

GET /api/v2/users/{user_id}/ Returns the profile of a user by their Tasking Manager user ID. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/12345/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

user_id

integer

required

The Tasking Manager user ID.

Response Fields

integer

Tasking Manager user ID.

username

string

OSM username.

role

string

User’s platform role. One of: READ_ONLY, MAPPER, ADMIN.

mappingLevel

string

Mapper skill level. One of: BEGINNER, INTERMEDIATE, ADVANCED.

projectsMapped

integer

Total number of projects the user has contributed to.

pictureUrl

string

URL to the user’s OSM profile picture.

isExpert

boolean

Whether the user has expert mode enabled.

Responses

Status	Description
`200`	User profile returned.
`401`	Missing or invalid token.
`404`	User not found.
`500`	Internal server error.

Delete User Account

DELETE /api/v2/users/{user_id}/ Deletes a user account. Only the user themselves or an admin may delete an account. Requires a valid token.

Account deletion is permanent. All associated data for the user will be removed from the platform.

curl -X DELETE "https://tasking-manager-api.hotosm.org/api/v2/users/12345/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

user_id

integer

required

ID of the user to delete.

Responses

Status	Description
`200`	User deleted. Returns the deleted user object.
`400`	User not found.
`401`	Caller does not have permission (not self or admin).
`500`	Internal server error.

List All Users

GET /api/v2/users/ Returns a paginated list of all users. Supports filtering by username, role, and mapping level. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/?page=1&perPage=20" \
  -H "Authorization: Token sessionTokenHere=="

Query Parameters

page

integer

default:"1"

Page number for paginated results.

perPage

integer

default:"20"

Number of results per page.

pagination

boolean

default:"true"

When false, returns all users without pagination.

username

string

Filter by full or partial OSM username.

role

string

Filter by user role. Valid values: ADMIN, READ_ONLY, MAPPER.

level

string

Filter by mapping level. Valid values: BEGINNER, INTERMEDIATE, ADVANCED.

sort

string

Field to sort results by.

sort_dir

string

default:"asc"

Sort direction. Valid values: asc, desc.

Responses

Status	Description
`200`	Paginated user list returned.
`400`	Invalid query parameters.
`401`	Missing or invalid token.
`500`	Internal server error.

Get User by Username

GET /api/v2/users/queries/{username}/ Returns user profile details by OpenStreetMap username. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/queries/Thinkwhere/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

username

string

required

The user’s OpenStreetMap username (case-sensitive).

Responses

Status	Description
`200`	User profile returned.
`401`	Missing or invalid token.
`404`	User not found.
`500`	Internal server error.

Search Users by Partial Username

GET /api/v2/users/queries/filter/{username}/ Returns a paginated list of users whose username matches the provided partial or full string. Optionally promotes project participants to the top of results. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/queries/filter/ali/?page=1" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

username

string

required

Partial or full OSM username string to filter by.

Query Parameters

page

integer

default:"1"

Page number for paginated results.

projectId

integer

Optional project ID. When provided, users who have contributed to this project are promoted to the top of the results list.

Responses

Status	Description
`200`	Matching users returned.
`401`	Missing or invalid token.
`404`	No users found matching the filter.
`500`	Internal server error.

Get Favorited Projects for Authenticated User

GET /api/v2/users/queries/favorites/ Returns the list of projects favorited by the authenticated user. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/queries/favorites/" \
  -H "Authorization: Token sessionTokenHere=="

Responses

Status	Description
`200`	Favorited projects returned.
`404`	User not found.
`500`	Internal server error.

Update Own Profile

PATCH /api/v2/users/me/actions/set-user/ Updates the authenticated user’s own profile settings. The id in the request body must match the authenticated user’s ID. Requires a valid token.

curl -X PATCH "https://tasking-manager-api.hotosm.org/api/v2/users/me/actions/set-user/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12345,
    "name": "Alice Mapper",
    "city": "Nairobi",
    "country": "Kenya",
    "emailAddress": "alice@example.com",
    "twitterId": "alicemaps"
  }'

Request Body

integer

required

Must match the authenticated user’s ID.

name

string

Display name.

city

string

City of residence.

country

string

Country of residence.

emailAddress

string

Email address for notifications. Set to an empty string or omit to clear.

twitterId

string

Twitter handle (without @).

facebookId

string

Facebook username.

linkedinId

string

LinkedIn username.

gender

string

Gender identity.

selfDescriptionGender

string

Required when gender is SELF_DESCRIBE.

Responses

Status	Description
`200`	Profile updated.
`400`	Invalid request body or validation error.
`401`	Token mismatch — `id` does not match authenticated user.
`500`	Internal server error.

Get OSM Details for User

GET /api/v2/users/{username}/openstreetmap/ Returns OpenStreetMap account details for a user (account creation date and changeset count) by looking up the user directly from the OSM API. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/Thinkwhere/openstreetmap/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

username

string

required

The user’s OpenStreetMap username.

Response Fields

accountCreated

string

ISO 8601 datetime when the OSM account was created.

changesetCount

integer

Total number of OSM changesets made by this user.

Responses

Status	Description
`200`	OSM details returned.
`401`	Missing or invalid token.
`404`	User not found in Tasking Manager.
`502`	Bad response from the OpenStreetMap API.
`500`	Internal server error.

User Tasks

Get Tasks Interacted With by User

GET /api/v2/users/{user_id}/tasks/ Returns a paginated list of tasks that a specific user has mapped or validated, with optional filters by status, project, and date range. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/12345/tasks/?page=1&page_size=10" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

user_id

integer

required

Tasking Manager user ID.

Query Parameters

status

string

Filter by task status. Valid values: READY, LOCKED_FOR_MAPPING, MAPPED, LOCKED_FOR_VALIDATION, VALIDATED, INVALIDATED, BADIMAGERY.

project_status

string

Filter by the status of the project the task belongs to. Valid values: DRAFT, PUBLISHED, ARCHIVED.

project_id

integer

Restrict results to a specific project.

start_date

string

ISO 8601 datetime. Return only task actions from this date onward.

end_date

string

ISO 8601 datetime. Return only task actions up to this date.

sort_by

string

default:"-action_date"

Sort order. Valid values: action_date, -action_date, project_id, -project_id. Prefix - for descending order.

page

integer

default:"1"

Page number.

page_size

integer

default:"10"

Number of results per page.

Responses

Status	Description
`200`	Task list returned (returns empty list if none found).
`401`	Missing or invalid token.
`500`	Internal server error.

Get Tasks Currently Locked by Authenticated User

GET /api/v2/users/queries/tasks/locked/ Returns a list of tasks that the authenticated user currently has locked for mapping or validation, across all projects. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/queries/tasks/locked/" \
  -H "Authorization: Token sessionTokenHere=="

Responses

Status	Description
`200`	Locked tasks returned.
`401`	Missing or invalid token.
`404`	User currently has no locked tasks.
`500`	Internal server error.

Get Details of Tasks Locked by Authenticated User

GET /api/v2/users/queries/tasks/locked/details/ Returns full task details for all tasks the authenticated user currently has locked, including localized task information. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/queries/tasks/locked/details/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Accept-Language: en"

Responses

Status	Description
`200`	Locked task details returned.
`401`	Missing or invalid token.
`404`	User currently has no locked tasks.
`500`	Internal server error.

User Statistics

Get User Contribution Statistics

GET /api/v2/users/{username}/statistics/ Returns detailed contribution statistics for a user by their OSM username. Includes total time spent mapping and validating, projects mapped, tasks mapped and validated, country contributions, and contributions by interest. Requires a valid token.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/Thinkwhere/statistics/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

username

string

required

The user’s OpenStreetMap username.

Response Fields

totalTimeSpent

integer

Total mapping and validation time in seconds.

timeSpentMapping

integer

Time spent mapping in seconds.

timeSpentValidating

integer

Time spent validating in seconds.

projectsMapped

integer

Number of distinct projects the user has contributed to.

tasksMapped

integer

Total tasks the user has mapped.

tasksValidated

integer

Total tasks the user has validated.

tasksInvalidated

integer

Tasks the user has had invalidated by others.

tasksValidatedByOthers

integer

Tasks originally mapped by this user and later validated by others.

countriesContributed

object

Breakdown of contributions by country.

Show countriesContributed fields

countries

array

Array of country contribution objects, each with name, mapped, validated, and total.

total

integer

Total number of countries contributed to.

contributionsByDay

array

Array of daily contribution counts with date and count fields.

ContributionsByInterest

array

Breakdown of contributions by mapped interest category.

Responses

Status	Description
`200`	User statistics returned.
`401`	Missing or invalid token.
`404`	User not found.
`500`	Internal server error.

Get Platform User Registration Statistics

GET /api/v2/users/statistics/ Returns aggregate statistics about users registered within a specified date range (e.g., new registrations over time). Requires a valid token. Date range cannot exceed three years.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/statistics/?startDate=2024-01-01&endDate=2024-06-30" \
  -H "Authorization: Token sessionTokenHere=="

Query Parameters

startDate

string

required

Start date in YYYY-MM-DD format.

endDate

string

End date in YYYY-MM-DD format. Defaults to today. Cannot be earlier than startDate. Range cannot exceed three years.

Responses

Status	Description
`200`	User statistics returned.
`400`	Invalid date format or range too large.
`401`	Missing or invalid token.
`500`	Internal server error.

Register User (Email-only)

POST /api/v2/users/actions/register/ Registers a user without an OpenStreetMap account using only an email address. This is used for observers or partners who do not map but need platform access. No authentication required.

curl -X POST "https://tasking-manager-api.hotosm.org/api/v2/users/actions/register/" \
  -H "Content-Type: application/json" \
  -d '{"email": "observer@example.com"}'

Request Body

string

required

Email address to register with.

Response Fields

string

The registered email address.

success

boolean

true if the registration succeeded.

details

string

Human-readable result message.

integer

New user ID.

Responses

Status	Description
`200`	User registered.
`400`	Invalid email or user already exists.
`500`	Internal server error.

Set User Role

PATCH /api/v2/users/{username}/actions/set-role/{role}/ Sets a user’s platform role. Restricted to Admin users only.

curl -X PATCH \
  "https://tasking-manager-api.hotosm.org/api/v2/users/Thinkwhere/actions/set-role/ADMIN/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

username

string

required

The OSM username of the user whose role is being changed.

role

string

required

New role to assign. Valid values: ADMIN, MAPPER, READ_ONLY.

Responses

Status	Description
`200`	Role set. Body: `{"Success": "Role Added"}`
`401`	Missing or invalid token.
`403`	Caller is not an admin.
`404`	User not found.
`500`	Internal server error.

Set Mapper Level

PATCH /api/v2/users/{username}/actions/set-level/{level}/ Manually sets a user’s mapping level. Restricted to Admin users only. Normally the platform auto-promotes users based on their contribution count.

curl -X PATCH \
  "https://tasking-manager-api.hotosm.org/api/v2/users/Thinkwhere/actions/set-level/ADVANCED/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

username

string

required

The OSM username of the user.

level

string

required

Mapping level to assign. Valid values: BEGINNER, INTERMEDIATE, ADVANCED.

Responses

Status	Description
`200`	Level set. Body: `{"Success": "Level set"}`
`400`	Invalid level value.
`401`	Missing or invalid token or caller is not an admin.
`404`	User not found.
`500`	Internal server error.

Set Expert Mode

PATCH /api/v2/users/{user_name}/actions/set-expert-mode/{is_expert}/ Enables or disables expert mode for a user. Restricted to Admin users only.

curl -X PATCH \
  "https://tasking-manager-api.hotosm.org/api/v2/users/Thinkwhere/actions/set-expert-mode/true/" \
  -H "Authorization: Token sessionTokenHere=="

Path Parameters

user_name

string

required

The OSM username of the user.

is_expert

string

required

Set to true to enable expert mode, false to disable.

Responses

Status	Description
`200`	Expert mode updated. Body: `{"Success": "Expert mode updated"}`
`400`	Invalid value.
`401`	Missing or invalid token or caller is not an admin.
`500`	Internal server error.

Resend Email Verification

PATCH /api/v2/users/me/actions/verify-email/ Resends the email verification message to the authenticated user’s registered email address. Requires a valid token.

curl -X PATCH "https://tasking-manager-api.hotosm.org/api/v2/users/me/actions/verify-email/" \
  -H "Authorization: Token sessionTokenHere=="

Responses

Status	Description
`200`	Verification email sent. Body: `{"Success": "Verification email resent"}`
`400`	Invalid email state.
`500`	Internal server error.

Set User Interests

POST /api/v2/users/me/actions/set-interests/ Creates or replaces the interest associations for the authenticated user. Requires a valid token.

curl -X POST "https://tasking-manager-api.hotosm.org/api/v2/users/me/actions/set-interests/" \
  -H "Authorization: Token sessionTokenHere==" \
  -H "Content-Type: application/json" \
  -d '{"interests": [1, 3, 7]}'

Request Body

interests

array

required

Array of integer interest IDs to associate with the user.

Responses

Status	Description
`200`	User interests updated.
`400`	Invalid request.
`401`	Missing or invalid token.
`500`	Internal server error.

Get Own Profile Example

The following shows how to retrieve the authenticated user’s own profile by looking up full details by user ID.

curl "https://tasking-manager-api.hotosm.org/api/v2/users/12345/" \
  -H "Authorization: Token sessionTokenHere=="

Overview

Resources

Documentation Index

​User Resources

​Get User by ID

​Path Parameters

​Response Fields

​Responses

​Delete User Account

​Path Parameters

​Responses

​List All Users

​Query Parameters

​Responses

​Get User by Username

​Path Parameters

​Responses

​Search Users by Partial Username

​Path Parameters

​Query Parameters

​Responses

​Get Favorited Projects for Authenticated User

​Responses

​Update Own Profile

​Request Body

​Responses

​Get OSM Details for User

​Path Parameters

​Response Fields

​Responses

​User Tasks

​Get Tasks Interacted With by User

​Path Parameters

​Query Parameters

​Responses

​Get Tasks Currently Locked by Authenticated User

​Responses

​Get Details of Tasks Locked by Authenticated User

​Responses

​User Statistics

​Get User Contribution Statistics

​Path Parameters

​Response Fields

​Responses

​Get Platform User Registration Statistics

​Query Parameters

​Responses

​User Actions

​Register User (Email-only)

​Request Body

​Response Fields

​Responses

​Set User Role

​Path Parameters

​Responses

​Set Mapper Level

​Path Parameters

​Responses

​Set Expert Mode

​Path Parameters

​Responses

​Resend Email Verification

​Responses

​Set User Interests

​Request Body

​Responses

​Get Own Profile Example

Build docs developers (and LLMs) love

User Resources

Get User by ID

Path Parameters

Response Fields

Responses

Delete User Account

Path Parameters

Responses

List All Users

Query Parameters

Responses

Get User by Username

Path Parameters

Responses

Search Users by Partial Username

Path Parameters

Query Parameters

Responses

Get Favorited Projects for Authenticated User

Responses

Update Own Profile

Request Body

Responses

Get OSM Details for User

Path Parameters

Response Fields

Responses

User Tasks

Get Tasks Interacted With by User

Path Parameters

Query Parameters

Responses

Get Tasks Currently Locked by Authenticated User

Responses

Get Details of Tasks Locked by Authenticated User

Responses

User Statistics

Get User Contribution Statistics

Path Parameters

Response Fields

Responses

Get Platform User Registration Statistics

Query Parameters

Responses

User Actions

Register User (Email-only)

Request Body

Response Fields

Responses

Set User Role

Path Parameters

Responses

Set Mapper Level

Path Parameters

Responses

Set Expert Mode

Path Parameters

Responses

Resend Email Verification

Responses

Set User Interests

Request Body

Responses

Get Own Profile Example