Platform Contributor Guide
[Legacy v3] Platform
[Legacy v3] Platform
  • 👋[Legacy v3] Welcome | README
  • Contributing | Getting Involved
    • Specific tasks needed for COVID19-support
    • Add code to Ushahidi
    • Encouraging contribution from non-developers
  • Frequently Asked Questions
  • Join the Ushahidi community
  • Contributors ✨
  • 🛣️ The Ushahidi Platform Roadmap
    • V2-V3+ Migration tool
  • Privacy and security best practices
    • Security as a user
    • Security for deployment admins
    • Security for deployment hosts
  • Development & Code
    • Development: Overview
    • How to get the source code
    • Setup Guides
      • Installing for production environments
      • Development environment with XAMPP
      • Development environment setup with Vagrant
      • [Client] Setting up the Platform Client for development
        • Migration from AngularJS
      • Setting up the Pattern Library for development
      • [API & Client] Bundled release install
    • Add code to Ushahidi
    • Development process
    • Coding Standards
    • Track and submit issues in Github
    • Upgrading Ushahidi
      • Upgrading to latest release
      • Upgrading from V3.x.x to V4.x.x
    • ⚙️ Installation Helper‌
  • Tech Stack
    • API Documentation
    • Third party app development
      • Web hooks
    • Database | Tables overview
    • Database | Database Schema Diagram
    • Database | Table details
    • 📐Architecture
    • Use case internals
  • QA & Testing
    • The QA process
    • How to run QA tests
    • Defect Management
    • How to write QA test scripts
    • Hotfixes
  • Front-end development
    • Changing UI styles: introduction to the pattern library
      • File-structure
      • Installing new packages
      • How to Apply to the Platform
      • Using the changed styles in platform-client
      • Syntax and Formatting
      • Grid, Breakpoints, & Media Queries
      • Variables
      • Mixins
      • Helpers
      • Icons
      • Create a New Component from Scratch
      • Read Direction
  • Design
    • 🎨Design: overview
    • 'Best practice' design
    • Ushahidi Platform 'Sticker Sheet'
    • User testing process
    • User testing script examples
    • Synthesising user testing results examples
      • Synthesis example 1
      • Synthesis example 2
      • Synthesis example 3
      • Synthesis recommendations example 1
      • Synthesis recommendations example 2
    • Open Source Design
  • Documentation
    • Documentation
    • Contributing docs via GitHub
  • Translation
    • Localization and Translation
  • The Ushahidi Platform Facebook bot
    • The Facebook bot
      • Installing the bot
      • The bot script
  • Hackathon and events
    • Installathon, May 2019
      • Welcome to the hackathon!
    • Write/Speak/Code 2019
    • Open Design: Bangalore
    • Open Design: Taipei
    • 📑Google season of docs
    • 💻Google Summer of Code
      • GSoC 2024
  • Enhancement Proposals
    • Exchange Format
    • Importing data from previous versions
Powered by GitBook
On this page
  • Get an authorization code for the client (without a user login)
  • Get an authorization code for a user
  • Request a password reset token to be sent via email
  • Reset your password with the reset token
  • Register a new user
  • Get Collections
  • Get Posts from a collection
  • Create a collection
  • Delete a collection
  • Get country codes
  • CSV Exports and Imports
  • Get a list of CSV exports jobs
  • [WIP]Create metadata to start a CSV Import
  • Dataproviders (Datasources in the UI, read only config)
  • Get data provider options
  • Forms (Surveys)
  • Get all surveys
  • Get all options for one survey
  • Get all attributes (fields) for one survey
  • Get all stages (groups of fields) for one survey
  • Get stats (usage data) for one survey
  • Get all roles assigned to one survey
  • Create a survey
  • Update a survey (example adding a new field)
  • Delete a survey
  • Respond to datasource messages
  • Get all messages for a post's contact
  • Get the post for a message
  • Create a new post
  • Get Posts
  1. Tech Stack

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

Name
Type
Description

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

Name
Type
Description

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

Name
Type
Description

email

string

example: youremail@example.com

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

Name
Type
Description

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

Name
Type
Description

string

Get Collections

GET https://ushahididocs.api.ushahidi.io/api/v3/collections

Headers

Name
Type
Description

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

Name
Type
Description

set

string

:collectionId (required to get posts from a collection)

orderby

string

Options: desc, asc

limit

string

:number

Headers

Name
Type
Description

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

Name
Type
Description

orderby

string

Options: desc, asc

limit

string

:number

Headers

Name
Type
Description

Authorization

string

Bearer <your-auth-token>

Request Body

Name
Type
Description

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

Name
Type
Description

collectionId

number

The collection id.. can appear as set_id in other places

Headers

Name
Type
Description

Authorization

string

Bearer <your-auth-token>

Success
The Collection id is incorrect

GET https://ushahididocs.api.ushahidi.io/api/v3/config

Path Parameters

Name
Type
Description

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

Name
Type
Description

contact_id

number

The contact id that you want to retrieve

Headers

Name
Type
Description

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 id

Get 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

Name
Type
Description

string

Headers

Name
Type
Description

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

Name
Type
Description

:jobId

number

Export ID

Query Parameters

Name
Type
Description

user

string

Value: me

Headers

Name
Type
Description

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

Name
Type
Description

user

string

Value: me

Headers

Name
Type
Description

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

Name
Type
Description

id

string

Dataprovider id

Headers

Name
Type
Description

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

Name
Type
Description

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

Name
Type
Description

id

number

The survey id

Headers

Name
Type
Description

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 raised

Get all attributes (fields) for one survey

GET https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/attributes

Path Parameters

Name
Type
Description

id

number

The form id

Headers

Name
Type
Description

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 raised

Get all stages (groups of fields) for one survey

GET https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/stages

Path Parameters

Name
Type
Description

id

number

The form id

Headers

Name
Type
Description

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 raised

Get stats (usage data) for one survey

GET https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/stats

Path Parameters

Name
Type
Description

id

number

The form id

Headers

Name
Type
Description

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 raised

Get all roles assigned to one survey

GET https://ushahididocs.api.ushahidi.io/api/v3/forms/:id/roles

Path Parameters

Name
Type
Description

id

number

The form id

Headers

Name
Type
Description

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 raised

Create a survey

POST https://ushahididocs.api.ushahidi.io/api/v3/forms

Create a survey in the backend.

Path Parameters

Name
Type
Description

string

Headers

Name
Type
Description

Authorization

string

Bearer: <your-auth-token>

Request Body

Name
Type
Description

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

Name
Type
Description

form_id

number

The survey id.

Headers

Name
Type
Description

Authorization

string

Bearer: <your-auth-token>

Request Body

Name
Type
Description

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

Name
Type
Description

form_id

number

The survey id.

Headers

Name
Type
Description

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

Name
Type
Description

Authorization

string

Bearer: <your-auth-token>

Request Body

Name
Type
Description

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

Name
Type
Description

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

Name
Type
Description

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

Name
Type
Description

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

Name
Type
Description

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

Name
Type
Description

Authorization

string

Bearer: <your-auth-token>

Request Body

Name
Type
Description

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

Success

Example payload:

{"title":"My title","content":"My content","values":{},"form":{"id":4}}

Get Posts

GET https://ushahididocs.api.ushahidi.io/api/v3/posts

Query Parameters

Name
Type
Description

orderby

string

Options: desc, asc

limit

string

:number

Headers

Name
Type
Description

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
}
Previous⚙️ Installation Helper‌NextThird party app development