API Documentation
Get an authorization code for the client (without a user login)
POST https://ushahididocs.api.ushahidi.io/oauth/token
This endpoint allows you to get an authorization token for the client without a user login. It allows you to execute the same actions as any non-logged in user.
Request Body
grant_type
string
Expected value for this type: "client_credentials"
client_secret
string
The client secret you added for your deployment in the database. Default value: "35e7f0bca957836d05ca0492211b0ac707671261"
client_id
string
The client_id you created for your deployment. Default value: "ushahidiui"
scope
string
All allowed scopes for this type: "posts country_codes media forms api tags savedsearches sets users stats layers config messages notifications webhooks contacts permissions csv"
Get an authorization code for a user
POST https://ushahididocs.api.ushahidi.io/oauth/token
This endpoint allows you to get an authentication token. All fields are required.
Request Body
scope
string
Default value: *
client_secret
string
Your client secret. Default value: 35e7f0bca957836d05ca0492211b0ac707671261
client_id
string
Your client ID. Default value: ushahidiui
grant_type
string
Fixed. Send value: password
password
string
Your Ushahidi platform password
username
string
Your Ushahidi platform username
{
"token_type": "Bearer",
"expires_in": "86400",
"access_token": "averylongstring",
"refresh_token": "anotherverylongstring"
}{
"error": "invalid_request",
"error_description": "The user credentials were incorrect."
}Request a password reset token to be sent via email
POST https://ushahididocs.api.ushahidi.io/api/v3/passwordreset
Request Body
This response is sent when the password reset email is going to be sent (as long as the email exists){
"errors": [
{
"status": 400,
"message": "Bad request: Payload parameter email has not been declared, defined parameters are: emails"
}
]
}Reset your password with the reset token
POST https://ushahididocs.api.ushahidi.io/api/v3/passwordreset/confirm
Request Body
password
string
The new password
token
string
The reset token sent by email
Register a new user
POST https://ushahididocs.api.ushahidi.io/api/v3/register
Register your Ushahidi platform users with this endpoint.
Path Parameters
string
Get Collections
GET https://ushahididocs.api.ushahidi.io/api/v3/collections
Headers
Authorization
string
Bearer <your-auth-token>
{
"count": 2,
"results": [
{
"id": 15,
"url": null,
"user": {
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/users\/86"
},
"name": "Testing",
"description": "tests",
"view": "map",
"view_options": null,
"role": null,
"featured": true,
"created": "2018-11-27T15:26:35+00:00",
"updated": null,
"allowed_privileges": [
"read",
"search"
]
},
{
"id": 14,
"url": null,
"user": {
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/users\/86"
},
"name": "Testing",
"description": "tests",
"view": "data",
"view_options": null,
"role": null,
"featured": true,
"created": "2018-11-27T15:26:35+00:00",
"updated": null,
"allowed_privileges": [
"read",
"search"
]
}
],
"limit": null,
"offset": 0,
"order": "DESC",
"orderby": "created",
"curr": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/collections?orderby=created&order=DESC&offset=0",
"next": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/collections?orderby=created&order=DESC&offset=0",
"prev": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/collections?orderby=created&order=DESC&offset=0",
"total_count": 2
}Get Posts from a collection
GET https://ushahididocs.api.ushahidi.io/api/v3/posts?order=desc&orderby=created&set=15
Query Parameters
set
string
:collectionId (required to get posts from a collection)
orderby
string
Options: desc, asc
limit
string
:number
Headers
Authorization
string
Bearer <your-auth-token>
{
"count": 2,
"results": [
{
"id": 18100,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts\/18100",
"parent_id": null,
"form": {
"id": 2,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/forms\/2"
},
"user_id": null,
"message": null,
"color": null,
"type": "report",
"title": "401 edits",
"slug": "401-5bfd5fce5eba2",
"content": "Tests",
"status": "published",
"created": "2018-11-27T15:16:33+00:00",
"updated": "2018-11-27T15:47:13+00:00",
"locale": "en_us",
"values": {
"fc81397d-b73d-43a6-b1da-7614534563be": [
"2018-11-22 05:31:00"
],
"cc0cb71a-c0af-4e0a-94ac-be6b21f4b796": [
"2018-11-27 15:46:50"
],
"9b65d16f-023d-4c1c-9284-8a3d57c8ae0a": [
{
"lon": 9.563599,
"lat": 7.710992
}
]
},
"post_date": "2018-11-27T15:16:33+00:00",
"tags": [],
"published_to": [],
"completed_stages": [],
"sets": [
"14"
],
"lock": null,
"source": null,
"contact": null,
"data_source_message_id": null,
"allowed_privileges": [
"read",
"create",
"search"
]
},
{
"id": 8328,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts\/8328",
"parent_id": null,
"form": {
"id": 1,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1"
},
"user_id": null,
"message": {
"id": 23462,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/messages\/23462"
},
"color": null,
"type": "report",
"title": "Test 2.",
"slug": "-58fdc11e54991",
"content": "Some content",
"status": "published",
"created": "2017-04-24T09:10:54+00:00",
"updated": "2017-04-24T13:10:19+00:00",
"locale": "en_us",
"values": [],
"post_date": "2017-04-24T09:10:54+00:00",
"tags": [],
"published_to": [],
"completed_stages": [
1
],
"sets": [
"1",
"3"
],
"lock": null,
"source": "sms",
"contact": {
"id": 2693,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/contact\/2693"
},
"data_source_message_id": null,
"allowed_privileges": [
"read",
"create",
"search"
]
}
],
"limit": "20",
"offset": 0,
"order": "desc",
"orderby": "created",
"curr": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts?orderby=created&order=desc&limit=20&offset=0",
"next": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts?orderby=created&order=desc&limit=20&offset=20",
"prev": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts?orderby=created&order=desc&limit=20&offset=0",
"total_count": 2
}Create a collection
POST https://ushahididocs.api.ushahidi.io/api/v3/collections
Query Parameters
orderby
string
Options: desc, asc
limit
string
:number
Headers
Authorization
string
Bearer <your-auth-token>
Request Body
user_id
string
The owner of the collection
name
string
Collection's name
role
array
The role id that is allowed to see and use it
view
string
Options: map,data
{
"count": 2,
"results": [
{
"id": 18100,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts\/18100",
"parent_id": null,
"form": {
"id": 2,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/forms\/2"
},
"user_id": null,
"message": null,
"color": null,
"type": "report",
"title": "401 edits",
"slug": "401-5bfd5fce5eba2",
"content": "Tests",
"status": "published",
"created": "2018-11-27T15:16:33+00:00",
"updated": "2018-11-27T15:47:13+00:00",
"locale": "en_us",
"values": {
"fc81397d-b73d-43a6-b1da-7614534563be": [
"2018-11-22 05:31:00"
],
"cc0cb71a-c0af-4e0a-94ac-be6b21f4b796": [
"2018-11-27 15:46:50"
],
"9b65d16f-023d-4c1c-9284-8a3d57c8ae0a": [
{
"lon": 9.563599,
"lat": 7.710992
}
]
},
"post_date": "2018-11-27T15:16:33+00:00",
"tags": [],
"published_to": [],
"completed_stages": [],
"sets": [
"14"
],
"lock": null,
"source": null,
"contact": null,
"data_source_message_id": null,
"allowed_privileges": [
"read",
"create",
"search"
]
},
{
"id": 8328,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts\/8328",
"parent_id": null,
"form": {
"id": 1,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1"
},
"user_id": null,
"message": {
"id": 23462,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/messages\/23462"
},
"color": null,
"type": "report",
"title": "Test 2.",
"slug": "-58fdc11e54991",
"content": "Some content",
"status": "published",
"created": "2017-04-24T09:10:54+00:00",
"updated": "2017-04-24T13:10:19+00:00",
"locale": "en_us",
"values": [],
"post_date": "2017-04-24T09:10:54+00:00",
"tags": [],
"published_to": [],
"completed_stages": [
1
],
"sets": [
"1",
"3"
],
"lock": null,
"source": "sms",
"contact": {
"id": 2693,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/contact\/2693"
},
"data_source_message_id": null,
"allowed_privileges": [
"read",
"create",
"search"
]
}
],
"limit": "20",
"offset": 0,
"order": "desc",
"orderby": "created",
"curr": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts?orderby=created&order=desc&limit=20&offset=0",
"next": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts?orderby=created&order=desc&limit=20&offset=20",
"prev": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts?orderby=created&order=desc&limit=20&offset=0",
"total_count": 2
}Delete a collection
DELETE https://ushahididocs.api.ushahidi.io/api/v3/collections/:collectionId
Delete the collection by its id.
Path Parameters
collectionId
number
The collection id.. can appear as set_id in other places
Headers
Authorization
string
Bearer <your-auth-token>
SuccessThe Collection id is incorrectGET https://ushahididocs.api.ushahidi.io/api/v3/config
Path Parameters
string
GET https://ushahididocs.api.ushahidi.io/api/v3/contacts/:contactId
Only used by deployments that require messaging capabilities such as receiving posts by SMS or Twitter.
Path Parameters
contact_id
number
The contact id that you want to retrieve
Headers
Authorization
string
Bearer: <your-auth-token>
{
"id": 1234,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/contacts\/1234",
"user_id": null,
"data_source": "twitter",
"type": "twitter",
"contact": "999888777",
"created": "2018-12-06T17:15:29+00:00",
"updated": null,
"can_notify": false,
"country_code": null,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}Incorrect contact idGet country codes
GET https://ushahididocs.api.ushahidi.io/api/v3/country-codes
This is only used to get a list of country codes that we can use for the UI of targeted surveys, a SaaS platform feature for sending surveys in steps to groups of people that they can respond to from their phones.
Path Parameters
string
Headers
Auth
string
Bearer <your-auth-token>
{
"count": 246,
"results": [
{
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/country_codes\/1",
"country_name": "Afghanistan",
"dial_code": "+93",
"country_code": "AF",
"allowed_privileges": [
"read",
"search"
]
},
{
"id": 2,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/country_codes\/2",
"country_name": "\u00c5land Islands",
"dial_code": "+358",
"country_code": "AX",
"allowed_privileges": [
"read",
"search"
]
},
{
"id": 3,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/country_codes\/3",
"country_name": "Albania",
"dial_code": "+355",
"country_code": "AL",
"allowed_privileges": [
"read",
"search"
]
},
{
"id": 4,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/country_codes\/4",
"country_name": "Algeria",
"dial_code": "+213",
"country_code": "DZ",
"allowed_privileges": [
"read",
"search"
]
},
{
"id": 5,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/country_codes\/5",
"country_name": "American Samoa",
"dial_code": "+1684",
"country_code": "AS",
"allowed_privileges": [
"read",
"search"
]
}
],
"limit": null,
"offset": 0,
"order": "asc",
"orderby": "id",
"curr": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/country-codes?orderby=id&order=asc&offset=0",
"next": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/country-codes?orderby=id&order=asc&offset=0",
"prev": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/country-codes?orderby=id&order=asc&offset=0",
"total_count": 246
}CSV Exports and Imports
Get a list of CSV exports jobs
GET https://ushahididocs.api.ushahidi.io/api/v3/exports/jobs?user=me
This returns all the metadata for exports of the current user
Path Parameters
:jobId
number
Export ID
Query Parameters
user
string
Value: me
Headers
Authorization
string
Bearer: <your-auth-token>
[WIP]Create metadata to start a CSV Import
PUT https://ushahididocs.api.ushahidi.io/api/v3/csv/:id/import
This returns all the metadata for exports of the current user
Query Parameters
user
string
Value: me
Headers
Authorization
string
Bearer: <your-auth-token>
{
"id": 19,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/csv\/19",
"columns": [
"Post ID",
"Survey",
"Post Status",
"Created (UTC)",
"Updated (UTC)",
"Post Date (UTC)",
"Contact ID",
"Contact",
"Unstructured Description",
"Title",
"Title",
"Title",
"Title",
"Title"
],
"maps_to": null,
"fixed": null,
"filename": "ushahididocs.api.ushahidi.io\/5\/c\/csv-export-full.csv",
"mime": "text\/csv",
"size": 2822,
"created": "2018-12-06T19:51:15+00:00",
"updated": null,
"completed": null,
"status": null,
"errors": null,
"processed": null,
"collection_id": null,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}Dataproviders (Datasources in the UI, read only config)
Get data provider options
GET https://ushahididocs.api.ushahidi.io/api/v3/dataproviders/[:id]
Path Parameters
id
string
Dataprovider id
Headers
Authorization
string
Bearer: <your-auth-token>
{
"count": 6,
"results": [
{
"id": "email",
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/dataprovider\/email",
"name": "Email",
"services": [
"email"
],
"options": {
"intro_text": {
"label": "",
"input": "read-only-text",
"description": "In order to receive posts by email, please input your email account settings below"
},
"incoming_type": {
"label": "Incoming Server Type",
"input": "radio",
"description": "",
"options": [
"POP",
"IMAP"
],
"rules": [
"required",
"number"
]
},
"incoming_server": {
"label": "Incoming Server",
"input": "text",
"description": "Examples: mail.yourwebsite.com, imap.gmail.com, pop.gmail.com",
"rules": [
"required"
]
},
"incoming_port": {
"label": "Incoming Server Port",
"input": "text",
"description": "Common ports: 110 (POP3), 143 (IMAP), 995 (POP3 with SSL), 993 (IMAP with SSL)",
"rules": [
"required",
"number"
]
},
"incoming_security": {
"label": "Incoming Server Security",
"input": "radio",
"description": "",
"options": [
"None",
"SSL",
"TLS"
]
},
"incoming_username": {
"label": "Incoming Username",
"input": "text",
"description": "",
"placeholder": "Email account username",
"rules": [
"required"
]
},
"incoming_password": {
"label": "Incoming Password",
"input": "text",
"description": "",
"placeholder": "Email account password",
"rules": [
"required"
]
}
},
"inbound_fields": {
"Subject": "text",
"Date": "datetime",
"Message": "text"
},
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": "frontlinesms",
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/dataprovider\/frontlinesms",
"name": "FrontlineSMS",
"services": [
"sms"
],
"options": {
"key": {
"label": "Key",
"input": "text",
"description": "The API key",
"rules": [
"required"
]
},
"secret": {
"label": "Secret",
"input": "text",
"description": "Set a secret so that only authorized FrontlineCloud accounts can send\/recieve message.\n\t\t\t\t\tYou need to configure the same secret in the FrontlineCloud Activity.",
"rules": [
"required"
]
}
},
"inbound_fields": {
"Message": "text"
},
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": "nexmo",
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/dataprovider\/nexmo",
"name": "Nexmo",
"services": [
"sms"
],
"options": {
"from": {
"label": "From",
"input": "text",
"description": "The from number",
"rules": [
"required"
]
},
"api_key": {
"label": "API Key",
"input": "text",
"description": "The API key",
"rules": [
"required"
]
},
"api_secret": {
"label": "API secret",
"input": "text",
"description": "The API secret",
"rules": [
"required"
]
}
},
"inbound_fields": {
"Message": "text"
},
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": "smssync",
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/dataprovider\/smssync",
"name": "SMSSync",
"services": [
"sms"
],
"options": {
"intro_step1": {
"label": "Step 1: Download the \"SMSSync\" app from the Android Market.",
"input": "read-only-text",
"description": "Scan this QR Code with your phone to download the app from the Android Market\n\t\t\t\t\t\t<img src=\"https:\/\/ushahididocs.api.ushahidi.io\/images\/smssync.png\" width=\"150\"\/>"
},
"intro_step2": {
"label": "Step 2: Android App Settings",
"input": "read-only-text",
"description": "Turn on SMSSync and use the following link as the Sync URL: https:\/\/ushahididocs.api.ushahidi.io\/sms\/smssync"
},
"secret": {
"label": "Secret",
"input": "text",
"description": "Set a secret so that only authorized SMSSync devices can send\/recieve message.\n\t\t\t\t\tYou need to configure the same secret in the SMSSync App.",
"rules": [
"required"
]
}
},
"inbound_fields": {
"Message": "text",
"Date": "datetime"
},
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": "twilio",
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/dataprovider\/twilio",
"name": "Twilio",
"services": [
"sms"
],
"options": {
"from": {
"label": "Phone Number",
"input": "text",
"description": "The from phone number.\n\t\t\t\t\tA Twilio phone number enabled for the type of message you wish to send. ",
"rules": [
"required"
]
},
"account_sid": {
"label": "Account SID",
"input": "text",
"description": "The unique id of the Account that sent this message.",
"rules": [
"required"
]
},
"auth_token": {
"label": "Auth Token",
"input": "text",
"description": "",
"rules": [
"required"
]
},
"sms_auto_response": {
"label": "SMS Auto response",
"input": "text",
"description": "",
"rules": [
"required"
]
}
},
"inbound_fields": {
"Message": "text"
},
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": "twitter",
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/dataprovider\/twitter",
"name": "Twitter",
"services": [
"twitter"
],
"options": {
"intro_step1": {
"label": "Step 1: Create a new Twitter application",
"input": "read-only-text",
"description": "Create a <a href=\"https:\/\/apps.twitter.com\/app\/new\">new twitter application<\/a>"
},
"intro_step2": {
"label": "Step 2: Generate a consumer key and secret",
"input": "read-only-text",
"description": "Once you've created the application click on \"Keys and Access Tokens\".<br \/>\n\t\t\t\t\t\tThen click \"Generate Consumer Key and Secret\".<br \/>\n\t\t\t\t\t\tCopy keys, tokens and secrets into the fields below."
},
"consumer_key": {
"label": "Consumer Key",
"input": "text",
"description": "Add the consumer key from your Twitter app. ",
"rules": [
"required"
]
},
"consumer_secret": {
"label": "Consumer Secret",
"input": "text",
"description": "Add the consumer secret from your Twitter app.",
"rules": [
"required"
]
},
"oauth_access_token": {
"label": "Access Token",
"input": "text",
"description": "Add the access token you generated for your Twitter app.",
"rules": [
"required"
]
},
"oauth_access_token_secret": {
"label": "Access Token Secret",
"input": "text",
"description": "Add the access secret that you generated for your Twitter app.",
"rules": [
"required"
]
},
"twitter_search_terms": {
"label": "Twitter search terms",
"input": "text",
"description": "Add search terms separated with commas",
"rules": [
"required"
]
}
},
"inbound_fields": {
"Date": "datetime",
"Message": "text"
},
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}
],
"limit": null,
"offset": 0,
"order": "asc",
"orderby": "id",
"curr": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/dataproviders?orderby=id&order=asc&offset=0",
"next": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/dataproviders?orderby=id&order=asc&offset=0",
"prev": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/dataproviders?orderby=id&order=asc&offset=0",
"total_count": 6
}Forms (Surveys)
Get all surveys
GET https://ushahididocs.api.ushahidi.io/api/v3/forms
Headers
Authorization
string
Bearer: <your-auth-token>
{
"count": 6,
"results": [
{
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1",
"parent_id": null,
"name": "Basic Post 2",
"description": "Post with a location",
"color": "#A51A1A",
"type": "report",
"disabled": false,
"created": "2018-04-16T23:51:28+00:00",
"updated": "2018-10-30T16:52:23+00:00",
"hide_author": false,
"hide_time": false,
"hide_location": false,
"require_approval": true,
"QAryone_can_create": true,
"targeted_survey": false,
"can_create": [],
"tags": [
{
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/1"
},
{
"id": 3,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/3"
},
{
"id": 11,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/11"
},
{
"id": 10,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/10"
},
{
"id": 12,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/12"
},
{
"id": 13,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/13"
}
],
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": 2,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/2",
"parent_id": null,
"name": "Data for export",
"description": null,
"color": null,
"type": "report",
"disabled": false,
"created": "2018-04-17T03:24:51+00:00",
"updated": null,
"hide_author": false,
"hide_time": false,
"hide_location": false,
"require_approval": true,
"QAryone_can_create": true,
"targeted_survey": false,
"can_create": [],
"tags": [],
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": 3,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/3",
"parent_id": null,
"name": "Some Testing",
"description": "Regression Testing",
"color": "#5BAA00",
"type": "report",
"disabled": false,
"created": "2018-07-13T09:48:00+00:00",
"updated": "2018-11-14T15:34:33+00:00",
"hide_author": false,
"hide_time": false,
"hide_location": false,
"require_approval": false,
"QAryone_can_create": false,
"targeted_survey": false,
"can_create": [
"admin",
"QA Role"
],
"tags": [],
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": 4,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/4",
"parent_id": null,
"name": "Another survey for api",
"description": null,
"color": null,
"type": "report",
"disabled": false,
"created": "2018-08-10T18:10:57+00:00",
"updated": "2018-08-29T18:47:11+00:00",
"hide_author": false,
"hide_time": false,
"hide_location": false,
"require_approval": true,
"QAryone_can_create": true,
"targeted_survey": false,
"can_create": [],
"tags": [],
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": 6,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/6",
"parent_id": null,
"name": "All fields example",
"description": "",
"color": null,
"type": "report",
"disabled": false,
"created": "2018-08-31T15:33:38+00:00",
"updated": "2018-08-31T16:19:42+00:00",
"hide_author": false,
"hide_time": false,
"hide_location": false,
"require_approval": true,
"QAryone_can_create": true,
"targeted_survey": false,
"can_create": [],
"tags": [
{
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/1"
},
{
"id": 3,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/3"
}
],
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}
],
"limit": null,
"offset": 0,
"order": "asc",
"orderby": "id",
"curr": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms?orderby=id&order=asc&offset=0",
"next": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms?orderby=id&order=asc&offset=0",
"prev": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms?orderby=id&order=asc&offset=0",
"total_count": 6
}Get all options for one survey
GET https://ushahididocs.api.ushahidi.io/api/v3/forms/:id
Path Parameters
id
number
The survey id
Headers
Authorization
string
Bearer: <your-auth-token>
{
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1",
"parent_id": null,
"name": "Basic Post 2",
"description": "Post with a location",
"color": "#A51A1A",
"type": "report",
"disabled": false,
"created": "2018-04-16T23:51:28+00:00",
"updated": "2018-10-30T16:52:23+00:00",
"hide_author": false,
"hide_time": false,
"hide_location": false,
"require_approval": true,
"everyone_can_create": true,
"targeted_survey": false,
"can_create": [],
"tags": [
{
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/1"
},
{
"id": 3,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/3"
},
{
"id": 11,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/11"
},
{
"id": 10,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/10"
},
{
"id": 12,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/12"
},
{
"id": 13,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/tags\/13"
}
],
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}If the survey does not exist, a 404 will be raisedGet all attributes (fields) for one survey
GET https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/attributes
Path Parameters
id
number
The form id
Headers
Authorization
string
Bearer: <your-auth-token>
{
"count": 5,
"results": [
{
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/form_attributes\/1",
"key": "location_default",
"label": "Location",
"instructions": null,
"input": "location",
"type": "point",
"required": false,
"default": null,
"priority": 0,
"options": null,
"cardinality": 1,
"config": null,
"form_stage_id": 1,
"response_private": false,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": 3,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/form_attributes\/3",
"key": "ff068758-2b7e-4a3b-af14-acbe26284ed1",
"label": "Title",
"instructions": null,
"input": "text",
"type": "title",
"required": true,
"default": null,
"priority": 0,
"options": null,
"cardinality": 0,
"config": null,
"form_stage_id": 1,
"response_private": false,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": 4,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/form_attributes\/4",
"key": "794636ad-5333-44db-aa09-d0ed553c06d4",
"label": "Description",
"instructions": null,
"input": "text",
"type": "description",
"required": true,
"default": null,
"priority": 0,
"options": null,
"cardinality": 0,
"config": null,
"form_stage_id": 1,
"response_private": false,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": 58,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/form_attributes\/58",
"key": "4695fc1a-f51d-4d59-b264-97083e4e8179",
"label": "Status",
"instructions": null,
"input": "tags",
"type": "tags",
"required": false,
"default": null,
"priority": 1,
"options": [
11,
10,
12,
13
],
"cardinality": 0,
"config": [],
"form_stage_id": 14,
"response_private": false,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": 5,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/form_attributes\/5",
"key": "1bf39730-3019-4c49-a0c7-c988c519effa",
"label": "Categories",
"instructions": null,
"input": "tags",
"type": "tags",
"required": false,
"default": null,
"priority": 3,
"options": [
1,
3
],
"cardinality": 0,
"config": [],
"form_stage_id": 1,
"response_private": false,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}
],
"limit": null,
"offset": 0,
"order": "asc",
"orderby": "priority",
"curr": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1\/attributes?orderby=priority&order=asc&offset=0",
"next": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1\/attributes?orderby=priority&order=asc&offset=0",
"prev": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1\/attributes?orderby=priority&order=asc&offset=0",
"total_count": 5
}If the survey does not exist, a 404 will be raisedGet all stages (groups of fields) for one survey
GET https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/stages
Path Parameters
id
number
The form id
Headers
Authorization
string
Bearer: <your-auth-token>
{
"count": 2,
"results": [
{
"id": 1,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/form_stages\/1",
"form_id": 1,
"label": "Structure",
"priority": 0,
"icon": null,
"type": "post",
"required": false,
"show_when_published": true,
"description": null,
"task_is_internal_only": false,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
},
{
"id": 14,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/form_stages\/14",
"form_id": 1,
"label": "completion status",
"priority": 1,
"icon": null,
"type": "task",
"required": true,
"show_when_published": true,
"description": null,
"task_is_internal_only": true,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}
],
"limit": null,
"offset": 0,
"order": "asc",
"orderby": "priority",
"curr": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1\/stages?orderby=priority&order=asc&offset=0",
"next": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1\/stages?orderby=priority&order=asc&offset=0",
"prev": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1\/stages?orderby=priority&order=asc&offset=0",
"total_count": 2
}If the survey does not exist, a 404 will be raisedGet stats (usage data) for one survey
GET https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/stats
Path Parameters
id
number
The form id
Headers
Authorization
string
Bearer: <your-auth-token>
{
"id": null,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/form_stats",
"total_responses": null,
"total_recipients": null,
"total_response_recipients": null,
"total_messages_sent": null,
"total_messages_pending": null,
"total_by_data_source": {
"sms": 0,
"email": "2",
"twitter": 0,
"web": "199",
"all": 201
},
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}If the survey does not exist, a 404 will be raisedGet all roles assigned to one survey
GET https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/roles
Path Parameters
id
number
The form id
Headers
Authorization
string
Bearer: <your-auth-token>
{
"count": 1,
"results": [
{
"id": 6,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/forms\/1\/roles\/6",
"form_id": 7,
"role_id": 4,
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}
],
"limit": null,
"offset": 0,
"order": "asc",
"orderby": "role_id",
"curr": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1\/roles?orderby=role_id&order=asc&offset=0",
"next": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1\/roles?orderby=role_id&order=asc&offset=0",
"prev": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1\/roles?orderby=role_id&order=asc&offset=0",
"total_count": 1
}If the survey does not exist, a 404 will be raisedCreate a survey
POST https://ushahididocs.api.ushahidi.io/api/v3/forms
Create a survey in the backend.
Path Parameters
string
Headers
Authorization
string
Bearer: <your-auth-token>
Request Body
name
string
The survey name
tasks.$n.id
string
A frontend generated ID to identify it while its being created. Example interim_id_2
tasks.$n.is_public
boolean
Is the task open to everyone? Default: true
tasks.$n.attributes
array
A list of attributes for the task. Takes the same options as form attributes for each.
tasks.$n.task_is_internal_only
boolean
Default: false
tasks.$n.show_when_published
boolean
Default: true
tasks.$n.type
string
post
tasks.$n.required
boolean
Default: false
tasks.$n.priority
number
The order of the task in the form
tasks.$n.label
string
The stage label
tasks
array
Array of stages (tasks) with options. Look for tasks.$n.$x in this list of params to see the attributes available for tasks
everyone_can_create
string
Can any user create posts? Default: true
require_approvel
boolean
Does the data in this survey auto-publish or is it saved as draft (default: false)
color
string
The survey color (shown in map and data view)
{
"id": 11,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/11",
"parent_id": null,
"name": "The survey name",
"description": null,
"color": null,
"type": "report",
"disabled": false,
"created": "2018-12-10T12:52:05+00:00",
"updated": null,
"hide_author": false,
"hide_time": false,
"hide_location": false,
"require_approval": true,
"everyone_can_create": true,
"targeted_survey": false,
"can_create": [],
"tags": [],
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}Update a survey (example adding a new field)
PUT https://ushahididocs.api.ushahidi.io/api/v3/forms/:form_id
Create a survey in the backend.
Path Parameters
form_id
number
The survey id.
Headers
Authorization
string
Bearer: <your-auth-token>
Request Body
name
string
The survey name
tasks.$n.id
string
A frontend generated ID to identify it while its being created. Example interim_id_2
tasks.$n.is_public
boolean
Is the task open to everyone? Default: true
tasks.$n.attributes
array
A list of attributes for the task. Takes the same options as form attributes for each.
tasks.$n.task_is_internal_only
boolean
Default: false
tasks.$n.show_when_published
boolean
Default: true
tasks.$n.type
string
post
tasks.$n.required
boolean
Default: false
tasks.$n.priority
number
The order of the task in the form
tasks.$n.label
string
The stage label
tasks
array
Array of stages (tasks) with options. Look for tasks.$n.$x in this list of params to see the attributes available for tasks
everyone_can_create
string
Can any user create posts? Default: true
require_approvel
boolean
Does the data in this survey auto-publish or is it saved as draft (default: false)
color
string
The survey color (shown in map and data view)
{
"id": 11,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/11",
"parent_id": null,
"name": "The survey name",
"description": null,
"color": null,
"type": "report",
"disabled": false,
"created": "2018-12-10T12:52:05+00:00",
"updated": null,
"hide_author": false,
"hide_time": false,
"hide_location": false,
"require_approval": true,
"everyone_can_create": true,
"targeted_survey": false,
"can_create": [],
"tags": [],
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}Delete a survey
DELETE https://ushahididocs.api.ushahidi.io/api/v3/forms/:form_id
Path Parameters
form_id
number
The survey id.
Headers
Authorization
string
Bearer: <your-auth-token>
{
"id": 11,
"url": "https:\/\/ushahididocs.api.ushahidi.io\/api\/v3\/forms\/11",
"parent_id": null,
"name": "A survey created to delete it",
"description": null,
"color": null,
"type": "report",
"disabled": false,
"created": "2018-12-17T21:29:13+00:00",
"updated": null,
"hide_author": false,
"hide_time": false,
"hide_location": false,
"require_approval": true,
"everyone_can_create": true,
"targeted_survey": false,
"can_create": [],
"tags": [],
"allowed_privileges": [
"read",
"create",
"update",
"delete",
"search"
]
}Respond to datasource messages
POST https://ushahididocs.api.ushahidi.io/api/v3/messages
Used in the "Conversation with author" UX in the platform.
Headers
Authorization
string
Bearer: <your-auth-token>
Request Body
parent_id
number
The id of the message you are responding to.
contact_id
number
The contact id of the person you want to send a message to. You can get this in the "Get messages for a post contact" endpoint below this one.
direction
string
Use "outgoing" for sending messages. We use "incoming" when a datasource fetches a message.
message
string
The message you want to send
Get all messages for a post's contact
GET https://ushahididocs.api.ushahidi.io/api/v3/messages
Used in the "Conversation with author" UX in the platform.
Query Parameters
orderby
string
Options: "created", "updated"
order
string
Options: "desc", "asc"
limit
number
Pagination limit
offset
number
Pagination offset
contact
number
The contact id. You can get it from the post the message is linked to.
Headers
Authorization
string
Bearer: <your-auth-token>
Get the post for a message
GET https://ushahididocs.api.ushahidi.io/api/v3/messages/:messageId/post
Used in the "Conversation with author" UX in the platform.
Query Parameters
orderby
string
Options: "created", "updated"
order
string
Options: "desc", "asc"
limit
number
Pagination limit
offset
number
Pagination offset
contact
number
The contact id. You can get it from the post the message is linked to.
Headers
Authorization
string
Bearer: <your-auth-token>
Create a new post
POST https://ushahididocs.api.ushahidi.io/api/v3/posts
Create a new post in the ushahidi platform. This method works with a user's password_grant token or with a client_credentials token generated with the client id and secret.
Headers
Authorization
string
Bearer: <your-auth-token>
Request Body
form
object
Format: {id: <formId>} . Sending the id of the form we want to add posts to is required.
values
object
a key:value map of fields and their content. This is used for all fields other than content and title and follows the format fieldKey: value. You can get a field's get by requesting all attributes of a form. Can be an empty object literal if a form has no other fields.
content
string
The post's description field
title
string
The post's title field
SuccessExample payload:
{"title":"My title","content":"My content","values":{},"form":{"id":4}}
Get Posts
GET https://ushahididocs.api.ushahidi.io/api/v3/posts
Query Parameters
orderby
string
Options: desc, asc
limit
string
:number
Headers
Authorization
string
Bearer <your-auth-token>
{
"count": 2,
"results": [
{
"id": 18100,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts\/18100",
"parent_id": null,
"form": {
"id": 2,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/forms\/2"
},
"user_id": null,
"message": null,
"color": null,
"type": "report",
"title": "401 edits",
"slug": "401-5bfd5fce5eba2",
"content": "Tests",
"status": "published",
"created": "2018-11-27T15:16:33+00:00",
"updated": "2018-11-27T15:47:13+00:00",
"locale": "en_us",
"values": {
"fc81397d-b73d-43a6-b1da-7614534563be": [
"2018-11-22 05:31:00"
],
"cc0cb71a-c0af-4e0a-94ac-be6b21f4b796": [
"2018-11-27 15:46:50"
],
"9b65d16f-023d-4c1c-9284-8a3d57c8ae0a": [
{
"lon": 9.563599,
"lat": 7.710992
}
]
},
"post_date": "2018-11-27T15:16:33+00:00",
"tags": [],
"published_to": [],
"completed_stages": [],
"lock": null,
"source": null,
"contact": null,
"data_source_message_id": null,
"allowed_privileges": [
"read",
"create",
"search"
]
},
{
"id": 8328,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts\/8328",
"parent_id": null,
"form": {
"id": 1,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/forms\/1"
},
"user_id": null,
"message": {
"id": 23462,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/messages\/23462"
},
"color": null,
"type": "report",
"title": "Test 2.",
"slug": "-58fdc11e54991",
"content": "Some content",
"status": "published",
"created": "2017-04-24T09:10:54+00:00",
"updated": "2017-04-24T13:10:19+00:00",
"locale": "en_us",
"values": [],
"post_date": "2017-04-24T09:10:54+00:00",
"tags": [],
"published_to": [],
"completed_stages": [
1
],
"lock": null,
"source": "sms",
"contact": {
"id": 2693,
"url": "https://ushahididocs.api.ushahidi.io\/api\/v3\/contact\/2693"
},
"data_source_message_id": null,
"allowed_privileges": [
"read",
"create",
"search"
]
}
],
"limit": "20",
"offset": 0,
"order": "desc",
"orderby": "created",
"curr": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts?orderby=created&order=desc&limit=20&offset=0",
"next": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts?orderby=created&order=desc&limit=20&offset=20",
"prev": "https://ushahididocs.api.ushahidi.io\/api\/v3\/posts?orderby=created&order=desc&limit=20&offset=0",
"total_count": 2
}