Skip to main content

Flow Results API

The Flow Results API standardizes the exchange of data collected by a Stack and external data analysis/visualization applications. The data covered by this API is the "results" or "responses" recorded during interactions with end-users through Journeys.

This API follows the Flow Results API Usage. See the Flow Results Specification for more details on how this open specification for the exchange of data generated by Flow-like software applications works.

Get all Flow Results Packages​

Request a list of Flow Results Packages available for the authorized user.

A Flow Results Package is a container and data format describing a collection of interactions or "responses" reported by end-users using Journeys. See Flow Results Package Specification for more details.

Optional query parameters:​

  • stack_uuid: Only list packages by the given Journeys's UUID.
$ curl "https://whatsapp.turn.io/v1/flow-results/packages?stack_uuid=<journey-uuid>" \
  -H "Authorization: Bearer <token>" \
  -H "accept: application/vnd.v1+json"
> {
    "links": {
        "self": "https://whatsapp.turn.io/v1/flow-results/packages",
    },
    "data": [
        {
            "type": "packages",
            "id": "0c364ee1-0305-42ad-9fc9-2ec5a80c55fa",
            "attributes": {
                "title": "Standard survey",
                "name": "standard-survey",
                "created": "2015-11-26 02:59:24+00:00",
                "modified": "2015-11-26 02:59:24+00:00"
            }
        },
        {
            "type": "packages",
            "id": "d8d0275f-e108-4528-a259-d738bb626143",
            "attributes": {
                "title": "Test survey",
                "name": "test-survey",
                "created": "2015-05-19 15:59:25+00:00",
                "modified": "2015-05-19 15:59:25+00:00"
            }
        }
    ]
}

Get the Details of a Package​

Request the details of a Flow Results Package.

$ curl "https://whatsapp.turn.io/v1/flow-results/packages/<id>" \
    -H 'Authorization: Bearer <token>' \
    -H "Accept: application/vnd.v1+json" \
> {
   "links": {
      "self": "https://whatsapp.turn.io/v1/flow-results/packages/<id>"
   },
   "data": {
      "type": "packages",
      "id": "<id>",
      "attributes": {
         "profile": "flow-results-package",
         "name": "standard-survey",
         "flow-results-specification": "1.0.0-rc1",
         "created": "2015-11-26 02:59:24+00:00",
         "modified": "2015-11-26 02:59:24+00:00",
         "id": "<id>",
         "title": "Standard survey",
         "resources": [
            {
               "path": null,
               "api-data-url": "https://whatsapp.turn.io/v1/flow-results/packages/<id>/responses",
               "mediatype": "application/json",
               "encoding": "utf-8",
               "schema": {
                  "language": "eng",
                  "fields": [
                     {
                        "name": "timestamp",
                        "title": "Timestamp",
                        "type": "datetime"
                     },
                     {
                        "name": "row_id",
                        "title": "Row ID",
                        "type": "string"
                     },
                     {
                        "name": "contact_id",
                        "title": "Contact ID",
                        "type": "integer"
                     },
                     {
                        "name": "session_id",
                        "title": "Session ID",
                        "type": "string"
                     },
                     {
                        "name": "question_id",
                        "title": "Question ID",
                        "type": "string"
                     },
                     {
                        "name": "response",
                        "title": "Response",
                        "type": "any"
                     },
                     {
                        "name": "response_metadata",
                        "title": "Response Metadata",
                        "type": "object"
                     }
                  ],
                  "questions": {
                     "gender": {
                        "type": "select_one",
                        "label": "Please select your gender",
                        "type_options": {
                           "choices": [
                              "Woman",
                              "Man",
                              "Other"
                           ]
                        }
                     },
                     "feeling": {
                        "type": "open",
                        "label": "How are you?",
                        "type_options": {}
                     }
                  }
               }
            }
         ]
      },
      "relationships": {
         "responses": {
            "links": {
               "related": "https://whatsapp.turn.io/v1/flow-results/packages/<id>/responses"
            }
         }
      }
   }
}

Get Responses for a Package​

Request some or all responses of a Flow Results Package. It supports pagination for large data sets and an optional set of filter parameters.

Query parameters:​

  • filter[start-timestamp]: Only show Responses that were recorded after this timestamp.
  • filter[end-timestamp]: Only show Responses that were recorded before and on this timestamp.
  • page[size]: The requested number of responses per page.
  • page[afterCursor]: The response row_id to requests responses after this id, when paginating forward.
  • page[beforeCursor]: The response row_id to request responses prior to this id, when paginating in reverse.
$ curl "https://whatsapp.turn.io/v1/flow-results/packages/<id>/responses" \
  -H "Authorization: Bearer <token>" \
  -H "accept: application/vnd.v1+json"
> {
    "data": {
        "type": "responses",
        "id": "<id>",
        "attributes": {
            "responses": [
                [
                    "2015-11-26 04:33:26",
                    "11393115",
                    "10825354",
                    "47029339",
                    "gender",
                    "Man",
                    {}
                ],
                [
                    "2015-11-26 04:33:31",
                    "11393119",
                    "10825354",
                    "47029339",
                    "feeling",
                    "I'm good. Thanks!",
                    {}
                ],
                ...
            ]
        },
        "relationships": {
            "packages": {
                "links": {
                    "related": "https://whatsapp.turn.io/v1/flow-results/packages/<id>"
                }
            }
        }
    },
    "links": {
        "self": "https://whatsapp.turn.io/v1/flow-results/packages/<id>/responses?page%5Bsize%5D=100",
        "next": "https://whatsapp.turn.io/v1/flow-results/packages/<id>/responses?page%5Bsize%5D=100&page%5BafterCursor%5D=0c364ee1-0305-42ad-9fc9-2ec5a80c55fa",
        "previous": null
    }
}