Overview

The admin api has been designed to specially handle most of the administrative task handled by the administrator of the Ushahidi deployment. All admin API request requires an HTTP authentication which means for any request you make to any of the admin API call, you have to provide your Ushahidi admin username and password to the HTTP client before you can get the intended response. The server sends a 401 Authentication Required header to prompt for username and password.

All the admin API tasks in the table below have “Requires admin authentication.” appended to the them and they are all POST request and it's shipped with Ushahidi version 2.1 and above.

Reports


Administrative tasks on reports are performed by sending a HTTP POST request to the base URL with report as the task parameter

Request Example
http://<deployment_url>/api?task=reports
Request Parameters

In addition to the task parameter, one of the following action request parameters MUST also be specified

Parameter

Description

Example

delete

Deletes the report with the specified incident_id from the system

&action=delete&incident_id=1

approve

Approves the report with the specified incident_id

&action=approve&incident_id=1

verify

Verifies the report with the specified incident_id

&action=verify&incident_id=1

edit

Edits an existing report. Parameters required are listed below

&action=edit&incident_id=5

Required Parameters for Report Editing (&action=edit)

When editing a report, the following parameters must be specifed in the request.

Parameter

Description

Example

incident_id

ID of the report to be edited

&incident_id=1

incident_title

Title of the report

&incident_title=Modified Report

incident_description

Description of the report

&incident_description=Modified report description

incident_date

Date of the report (in mm/dd/yyyy) format

&incident_date=12/22/2009

incident_hour

Hour component (in 12 hour format) of the time when the event being reported took place

&incident_hour=11

incident_minute

Minute component of the time the event being reported took place

&incident_minute=11

incident_ampm

Whether the event took place in the AM or PM

&incident_ampm=am

latitude

Latitude component of the report location

&latitude=-1.0477494

longitude

Longitude component of the report location

&longitude=36.02937473

location_name

Name of the location association where the event took place

&location_name=Nyan Island

location_id

ID of the location associated with the report

&location_id=5

incident_active

Whether the report has been approved (0 - Not approved, 1 - Approved)

&incident_active=1

incident_verified

Whether the report has been verified (0 - Not verified, 1 - Verified)

&incident_verified=1

incident_categoryList of category ids (list must contain at least 1 category)&incident_category=12,45,3
Optional Parameters

Parameter

Description

Example

person_first

First name of the person who submitted the report

&person_first=John

person_last

Last name of the person who submitted the report

&person_last=Doe

person_email

Email address of the person who submitted the report

johndoe@example.com

incident_photo[]

Photo(s) associated with the report

None

incident_news

A URL to a news or other website link that is associated with the report

None

incident_video

Optional A URL to a video related to the report

None

Comments


A comment to a report is submitted by sending a HTTP POST request to the base URL with comments as the task parameter

Request Example
http://<deployment_url>/api?task=comments
Request Parameters

When submitting a comment via the Admin API, the following parameters MUST be specified:

Parameter

Description

Example

incident_id

ID of the report under which the comment is being submitted

&incident_id=5

checkin_id

ID of the checkin to post the comment on (when not using incident_id)

&checkin_id=6

comment_author

Name of person posting the comment

&comment_author=John+Doe

comment_description

Details of the comment

&comment_description=Ninja+rats+up+in+this+codebase

comment_email

Email address of the person submitting the comment

&comment_email=johndoe@example.com

NOTE: As of v2.2 of the platform, comment_email and comment_author are not necessary if the comment is being submitted by an already authenticated user. If specified, they shall be overwritten with the details of the authenticated user.

Categories


Administrative tasks on categories are performed by sending a HTTP POST to the base URL with category as the task parameter.

Request Example
http://<deployment_url>/api?task=category

In addition to the task parameter, one of the following action parameters must also be specified

Parameter

Description

Example

add

Creates a new category

&action=add

edit

Edits an existing category. The id of the category to be edited must also be specified

&action=edit&category_id=5

delete

Deletes an existing category. The id of the category to be deleted must also be specified

&action=delete&category_id=7

Request Parameters (&action=add and &action=edit)

Parameter

Description

Example

category_id

ID of the category - Only when a category is being edited

&category_id=2

parent_id

ID of the parent category or 0 when you want the new category to be the parent category

&parent_id=2

category_title

Title of the category

&category_title=Category+One

category_description

Description of the category

category_description=Describing+category+one

category_color

Hex value of the color to be used to visually identify the category

category_color=FF0000

category_image

Optional Path to an image that shall serve as the category's icon

None