# API Documentation

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

<mark style="color:green;">`POST`</mark> `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" |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get an authorization code for a user

<mark style="color:green;">`POST`</mark> `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                                             |

{% tabs %}
{% tab title="200 Auth token created" %}

```javascript
{
    "token_type": "Bearer",
    "expires_in": "86400",
    "access_token": "averylongstring",
    "refresh_token": "anotherverylongstring"
}
```

{% endtab %}

{% tab title="400 Incorrect credentials" %}

```javascript
{
    "error": "invalid_request",
    "error_description": "The user credentials were incorrect."
}
```

{% endtab %}
{% endtabs %}

## Request a password reset token to be sent via email

<mark style="color:green;">`POST`</mark> `https://ushahididocs.api.ushahidi.io/api/v3/passwordreset`

#### Request Body

| Name  | Type   | Description                      |
| ----- | ------ | -------------------------------- |
| email | string | example: <youremail@example.com> |

{% tabs %}
{% tab title="204 " %}

```
This response is sent when the password reset email is going to be sent (as long as the email exists)
```

{% endtab %}

{% tab title="400 Incorrect parameter name in the body (emails, instead of email)" %}

```javascript
{
    "errors": [
        {
            "status": 400,
            "message": "Bad request: Payload parameter email has not been declared, defined parameters are: emails"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Reset your password with the reset token

<mark style="color:green;">`POST`</mark> `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 |

{% tabs %}
{% tab title="204 " %}

```
```

{% endtab %}
{% endtabs %}

## Register a new user

<mark style="color:green;">`POST`</mark> `https://ushahididocs.api.ushahidi.io/api/v3/register`

Register your Ushahidi platform users with this endpoint.

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get Collections

<mark style="color:blue;">`GET`</mark> `https://ushahididocs.api.ushahidi.io/api/v3/collections`

#### Headers

| Name          | Type   | Description               |
| ------------- | ------ | ------------------------- |
| Authorization | string | Bearer \<your-auth-token> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}
{% endtabs %}

## Get Posts from a collection

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}
{% endtabs %}

## Create a collection

<mark style="color:green;">`POST`</mark> `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                             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}
{% endtabs %}

## Delete a collection

<mark style="color:red;">`DELETE`</mark> `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> |

{% tabs %}
{% tab title="204 " %}

```
Success
```

{% endtab %}

{% tab title="404 " %}

```
The Collection id is incorrect
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `https://ushahididocs.api.ushahidi.io/api/v3/config`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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"
    ]
}
```

{% endtab %}

{% tab title="404 " %}

```
Incorrect contact id
```

{% endtab %}
{% endtabs %}

## Get country codes

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 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
}
```

{% endtab %}
{% endtabs %}

## CSV Exports and Imports

## Get a list of CSV exports jobs

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## \[WIP]Create metadata to start a CSV Import

<mark style="color:orange;">`PUT`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```
{
    "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"
    ]
}
```

{% endtab %}
{% endtabs %}

## Dataproviders (Datasources in the UI, read only config)

## Get data provider options

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}
{% endtabs %}

## Forms (Surveys)

## Get all surveys

<mark style="color:blue;">`GET`</mark> `https://ushahididocs.api.ushahidi.io/api/v3/forms`

#### Headers

| Name          | Type   | Description                |
| ------------- | ------ | -------------------------- |
| Authorization | string | Bearer: \<your-auth-token> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}
{% endtabs %}

## Get all options for one survey

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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"
    ]
}
```

{% endtab %}

{% tab title="404 " %}

```
If the survey does not exist, a 404 will be raised
```

{% endtab %}
{% endtabs %}

## Get all attributes (fields) for one survey

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}

{% tab title="404 " %}

```
If the survey does not exist, a 404 will be raised
```

{% endtab %}
{% endtabs %}

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

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}

{% tab title="404 " %}

```
If the survey does not exist, a 404 will be raised
```

{% endtab %}
{% endtabs %}

## Get stats (usage data) for one survey

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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"
    ]
}
```

{% endtab %}

{% tab title="404 " %}

```
If the survey does not exist, a 404 will be raised
```

{% endtab %}
{% endtabs %}

## Get all roles assigned to one survey

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}

{% tab title="404 " %}

```
If the survey does not exist, a 404 will be raised
```

{% endtab %}
{% endtabs %}

## Create a survey

<mark style="color:green;">`POST`</mark> `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)                                                                               |

{% tabs %}
{% tab title="200 " %}

```
{
    "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"
    ]
}
```

{% endtab %}
{% endtabs %}

## Update a survey (example adding a new field)

<mark style="color:orange;">`PUT`</mark> `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)                                                                               |

{% tabs %}
{% tab title="200 " %}

```
{
    "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"
    ]
}
```

{% endtab %}
{% endtabs %}

## Delete a survey

<mark style="color:red;">`DELETE`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```
{
    "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"
    ]
}
```

{% endtab %}
{% endtabs %}

## Respond to datasource messages

<mark style="color:green;">`POST`</mark> `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                                                                                                                   |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get all messages for a post's contact

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get the post for a message

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Create a new post

<mark style="color:green;">`POST`</mark> `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                                                                                                                                                                                                                                                        |

{% tabs %}
{% tab title="204 " %}

```
Success
```

{% endtab %}
{% endtabs %}

Example payload:

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

## Get Posts

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ushahidi.com/platform-developer-documentation/dev-legacy-v3/tech-stack/api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.