API Documentation

post
Get an authorization code for the client (without a user login)
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
Response
Request
Body Parameters
grant_type
required
string
Expected value for this type: "client_credentials"
client_secret
required
string
The client secret you added for your deployment in the database. Default value: "35e7f0bca957836d05ca0492211b0ac707671261"
client_id
required
string
The client_id you created for your deployment. Default value: "ushahidiui"
scope
required
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"
Response
200: OK
​
post
Get an authorization code for a user
https://ushahididocs.api.ushahidi.io/oauth/token
This endpoint allows you to get an authentication token. All fields are required.
Request
Response
Request
Body Parameters
scope
required
string
Default value: *
client_secret
required
string
Your client secret. Default value: 35e7f0bca957836d05ca0492211b0ac707671261
client_id
required
string
Your client ID. Default value: ushahidiui
grant_type
required
string
Fixed. Send value: password
password
required
string
Your Ushahidi platform password
username
required
string
Your Ushahidi platform username
Response
200: OK
Auth token created
{
    "token_type": "Bearer",
    "expires_in": "86400",
    "access_token": "averylongstring",
    "refresh_token": "anotherverylongstring"
}
400: Bad Request
Incorrect credentials
{
    "error": "invalid_request",
    "error_description": "The user credentials were incorrect."
}
post
Request a password reset token to be sent via email
https://ushahididocs.api.ushahidi.io/api/v3/passwordreset
Request
Response
Request
Body Parameters
email
required
string
example: youremail@example.com
Response
204: No Content
This response is sent when the password reset email is going to be sent (as long as the email exists)
400: Bad Request
Incorrect parameter name in the body (emails, instead of email)
{
    "errors": [
        {
            "status": 400,
            "message": "Bad request: Payload parameter email has not been declared, defined parameters are: emails"
        }
    ]
}
post
Reset your password with the reset token
https://ushahididocs.api.ushahidi.io/api/v3/passwordreset/confirm
Request
Response
Request
Body Parameters
password
required
string
The new password
token
required
string
The reset token sent by email
Response
204: No Content
​
post
Register a new user
https://ushahididocs.api.ushahidi.io/api/v3/register
Register your Ushahidi platform users with this endpoint.
Request
Response
Request
Path Parameters
optional
string
​
Response
200: OK
​
get
Get Collections
https://ushahididocs.api.ushahidi.io/api/v3/collections
Request
Response
Request
Headers
Authorization
required
string
Bearer <your-auth-token>
Response
200: OK
{
    "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
Get Posts from a collection
https://ushahididocs.api.ushahidi.io/api/v3/posts?order=desc&orderby=created&set=15
Request
Response
Request
Headers
Authorization
required
string
Bearer <your-auth-token>
Query Parameters
set
required
string
:collectionId (required to get posts from a collection)
orderby
optional
string
Options: desc, asc
limit
optional
string
:number
Response
200: OK
{
    "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
}
post
Create a collection
https://ushahididocs.api.ushahidi.io/api/v3/collections
Request
Response
Request
Headers
Authorization
required
string
Bearer <your-auth-token>
Query Parameters
orderby
optional
string
Options: desc, asc
limit
optional
string
:number
Body Parameters
user_id
required
string
The owner of the collection
name
required
string
Collection's name
role
required
array
The role id that is allowed to see and use it
view
required
string
Options: map,data
Response
200: OK
{
    "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
Delete a collection
https://ushahididocs.api.ushahidi.io/api/v3/collections/:collectionId
Delete the collection by its id.
Request
Response
Request
Path Parameters
collectionId
required
number
The collection id.. can appear as set_id in other places
Headers
Authorization
required
string
Bearer <your-auth-token>
Response
204: No Content
Success
404: Not Found
The Collection id is incorrect
get
​
https://ushahididocs.api.ushahidi.io/api/v3/config
Request
Response
Request
Path Parameters
optional
string
​
Response
200: OK
​
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.
Request
Response
Request
Path Parameters
contact_id
required
number
The contact id that you want to retrieve
Headers
Authorization
required
string
Bearer: <your-auth-token>
Response
200: OK
{
    "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"
    ]
}
404: Not Found
Incorrect contact id
get
Get country codes
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.
Request
Response
Request
Path Parameters
optional
string
​
Headers
Auth
required
string
Bearer <your-auth-token>
Response
200: OK
Example response with 5 countries and their code
{
    "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
Get a list of CSV exports jobs
https://ushahididocs.api.ushahidi.io/api/v3/exports/jobs?user=me
This returns all the metadata for exports of the current user
Request
Response
Request
Path Parameters
:jobId
optional
number
Export ID
Headers
Authorization
optional
string
Bearer: <your-auth-token>
Query Parameters
user
required
string
Value: me
Response
200: OK
​
put
[WIP]Create metadata to start a CSV Import
https://ushahididocs.api.ushahidi.io/api/v3/csv/:id/import
This returns all the metadata for exports of the current user
Request
Response
Request
Headers
Authorization
optional
string
Bearer: <your-auth-token>
Query Parameters
user
required
string
Value: me
Response
200: OK
{
    "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
Get data provider options
https://ushahididocs.api.ushahidi.io/api/v3/dataproviders/[:id]
Request
Response
Request
Path Parameters
id
optional
string
Dataprovider id
Headers
Authorization
optional
string
Bearer: <your-auth-token>
Response
200: OK
{
    "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
Get all surveys
https://ushahididocs.api.ushahidi.io/api/v3/forms
Request
Response
Request
Headers
Authorization
optional
string
Bearer: <your-auth-token>
Response
200: OK
{
    "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
Get all options for one survey
https://ushahididocs.api.ushahidi.io/api/v3/forms/:id
Request
Response
Request
Path Parameters
id
required
number
The survey id
Headers
Authorization
optional
string
Bearer: <your-auth-token>
Response
200: OK
{
    "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"
    ]
}
404: Not Found
If the survey does not exist, a 404 will be raised
get
Get all attributes (fields) for one survey
https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/attributes
Request
Response
Request
Path Parameters
id
required
number
The form id
Headers
Authorization
optional
string
Bearer: <your-auth-token>
Response
200: OK
{
    "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
}
404: Not Found
If the survey does not exist, a 404 will be raised
get
Get all stages (groups of fields) for one survey
https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/stages
Request
Response
Request
Path Parameters
id
required
number
The form id
Headers
Authorization
optional
string
Bearer: <your-auth-token>
Response
200: OK
{
    "count": 2,
    "results": [
        {
            "id": 1,
API Documentation

postGet an authorization code for the client (without a user login)

postGet an authorization code for a user

postRequest a password reset token to be sent via email

postReset your password with the reset token

postRegister a new user

getGet Collections

getGet Posts from a collection

postCreate a collection

deleteDelete a collection

get​

get​

getGet country codes

CSV Exports and Imports

getGet a list of CSV exports jobs

put[WIP]Create metadata to start a CSV Import

Dataproviders (Datasources in the UI, read only config)

getGet data provider options

Forms (Surveys)

getGet all surveys

getGet all options for one survey

getGet all attributes (fields) for one survey

getGet all stages (groups of fields) for one survey

post
Get an authorization code for the client (without a user login)

post
Get an authorization code for a user

post
Request a password reset token to be sent via email

post
Reset your password with the reset token

post
Register a new user

get
Get Collections

get
Get Posts from a collection

post
Create a collection

delete
Delete a collection

get

get

get
Get country codes

get
Get a list of CSV exports jobs

put
[WIP]Create metadata to start a CSV Import

get
Get data provider options

get
Get all surveys

get
Get all options for one survey

get
Get all attributes (fields) for one survey

get
Get all stages (groups of fields) for one survey
