Endpoint and Authentication

Please refer to the API overview section to get the API endpoint, query format and authentication process.

This section of the documentation shows how to list, create and manage your funnels.

Funnels

List

GET /api/funnels?apps=apps

This API lists all the funnels for the user making the request.

Query Parameters

Property Type Description Default
apps array of strings The list of apps to filter the funnels list with -

Response

Status: 200 OK

{
  "success": true,
  "result": [
    {
      "identifier": "FAFUNNL_1234567891234567",
      "name": "test funnel 1",
      "description": "test description 1",
      "max_duration": 50000,
      "labels": [],
      "steps": [
        {
          "match_name": [
            {
              "app_id": "FAAPPLI_1234567",
              "log_type": 2,
              "log_name": "event name 1"
            }
          ],
          "match_details": []
        },
        {
          "match_name": [
            {
              "app_id": "FAAPPLI_1234567",
              "log_type": 2,
              "log_name": "event name 2"
            }
          ],
          "match_details": []
        }
      ],
      "archived": false,
      "archived_at": null,
      "created_at": "2018-03-01T12:39:02.824Z",
      "updated_at": "2018-03-01T12:39:02.824Z"
    },
    {
      "identifier": "FAFUNNL_1234567891234567",
      "name": "test funnel 2",
      "description": "test description 2",
      "max_duration": 2592000,
      "labels": [],
      "steps": [
        {
          "match_name": [
            {
              "app_id": "FAAPPLI_9876543",
              "log_type": 2,
              "log_name": "event name 3"
            }
          ],
          "match_details": []
        },
        {
          "match_name": [
            {
              "app_id": "FAAPPLI_9876543",
              "log_type": 2,
              "log_name": "event name 4"
            }
          ],
          "match_details": []
        },
        {
          "match_name": [
            {
              "app_id": "FAAPPLI_9876543",
              "log_type": 2,
              "log_name": "event name 5"
            }
          ],
          "match_details": []
        },
        {
          "match_name": [
            {
              "app_id": "FAAPPLI_9876543",
              "log_type": 2,
              "log_name": "event name 6"
            }
          ],
          "match_details": []
        }
      ],
      "archived": false,
      "archived_at": null,
      "created_at": "2018-02-23T12:32:12.800Z",
      "updated_at": "2018-02-26T16:31:20.678Z"
    }
  ]
}

Status: 404 not found

{
  "status": "not_found",
  "success": false,
  "error_message": "Entity not found"
}

View

GET /api/funnels/identifier

Returns a specific funnel, provided the user has access to it.

Query Parameters

Property Type Description Default
identifier string The identifier of the funnel to view required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FAFUNNL_1234567891234567",
    "name": "test funnel 1",
    "description": "test description 1",
    "max_duration": 50000,
    "labels": [],
    "steps": [
      {
        "match_name": [
          {
            "app_id": "FAAPPLI_1234567",
            "log_type": 2,
            "log_name": "event name 1"
          }
        ],
        "match_details": []
      },
      {
        "match_name": [
          {
            "app_id": "FAAPPLI_1234567",
            "log_type": 2,
            "log_name": "event name 2"
          }
        ],
        "match_details": []
      }
    ],
    "archived": false,
    "archived_at": null,
    "created_at": "2018-03-01T12:39:02.824Z",
    "updated_at": "2018-03-01T12:39:02.824Z"
  }
}

Status: 404 not found

{
  "status": "not_found",
  "success": false,
  "error_message": "Funnel not found"
}

Create

POST /api/funnels

Creates a new funnel with a user-specified sequence of steps. The steps need to match existing events and applications.

Body Parameters

Property Type Description Default
name string A name for your funnel required
description string A description for your funnel -
max_duration integer The max duration your funnel sequence can last (in seconds) 2592000
steps array of objects The sequence of steps for your funnel required
step[match_name] array of objects The events to match with your step required
step[match_details] array of objects The events details (values) to match with your step -
match_name[app_id] string The identifier of the application the event belongs to required
match_name[log_type] integer The type of the event (0, 1, 2 or 3) to match with required
match_name[log_name] string The name of the event to match with required
labels array of strings The label names to add to your funnel -

Example

{
  "name": "test funnel",
  "description": "test description",
  "max_duration": 12345,
  "labels": ["a", "b", "c"],
  "steps": [
    {
      "match_name": [
        {
          "app_id": "FAAPPLI_1234567",
          "log_type": 2,
          "log_name": "event name 1"
        }
      ],
      "match_details": []
    },
    {
      "match_name": [
        {
          "app_id": "FAAPPLI_1234567",
          "log_type": 2,
          "log_name": "event name 2"
        }
      ],
      "match_details": []
    }
  ]
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FAFUNNL_gKAaBDRn-CHyb9iN",
    "name": "test funnel",
    "description": "test description",
    "max_duration": 12345,
    "labels": [
      "a",
      "b",
      "c"
    ],
    "steps": [
      {
        "match_name": [
          {
            "app_id": "FAAPPLI_1234567",
            "log_type": 2,
            "log_name": "event name 1"
          }
        ],
        "match_details": []
      },
      {
        "match_name": [
          {
            "app_id": "FAAPPLI_1234567",
            "log_type": 2,
            "log_name": "event name 2"
          }
        ],
        "match_details": []
      }
    ],
    "archived": false,
    "archived_at": null,
    "created_at": "2018-03-07T15:18:59.606Z",
    "updated_at": "2018-03-07T15:18:59.606Z"
  }
}

Update

PUT /api/funnels/identifier

Query Parameters

Property Type Description Default
identifier string The identifier of the funnel to update required

Body Parameters

Property Type Description Default
labels array of strings The new labels to update the funnel with -

Example

{
    "labels": ["123", "test", "other"]
}

Response

NOTE: The response JSON will be the same as the view endpoint, except the labels returned are the new updated ones.

Status: 200 OK

{
  "success": true,
  "result": {
    ...,
    "labels": [
      "123",
      "test",
      "other"
    ],
    ...,
    "updated_at": "2018-03-07T15:24:31.289Z"
  }
}

Archive

PUT /api/funnels/identifier/archive

This API endpoint archives a funnel, making it unnaccessible. In other words, making it disabled for use in some operations.

Query Parameters

Property Type Description Default
identifier string The identifier of the funnel to archive required

Response

NOTE: The response JSON will be the same as the view endpoint, except the archived and archived_at values will be filled in.

Status: 200 OK

{
  "success": true,
  "result": {
    ...,
    "archived": true,
    "archived_at": "2018-03-07T15:36:44.924Z",
    ...
  }
}

Restore

PUT /api/funnels/identifier/restore

This API endpoint restores a funnel, making it accessible again.

Query Parameters

Property Type Description Default
identifier string The identifier of the funnel to restore required

Response

NOTE: The response JSON will be the same as the view endpoint, except the archived and archived_at values will be reset.

Status: 200 OK

{
  "success": true,
  "result": {
    ...,
    "archived": false,
    "archived_at": null,
    ...
  }
}

Retrieving Funnel Analytics

The two next endpoints are used to retrieved data from a funnel through its sequence of steps. The current available data includes completions and proposed events for next steps of a sequence.

Quick Stats

POST /api/funnels/quick_stats?app_id=app_id&from=from&till=till&mode=mode

Returns the completions for each step of a given funnel sequence. This endpoint is not tied to any specific funnel.

Query Parameters

Property Type Description Default
app_id string The identifier of the app to explore -
from date The date to start looking for completions, expressed as YYYY-MM-DD -
till date The date to stop looking for completions, expressed as YYYY-MM-DD -
mode string Specifies the mode of search, for more slow or less fast accurate results -

Body Parameters

Property Type Description Default
funnel object An abstraction of the funnel to explore required
funnel[max_duration] float The max duration of the funnel -
funnel[steps] array of objects The sequence of steps for your funnel required
step[match_name] array of objects The events to match with your step required
step[match_details] array of objects The events details (values) to match with your step -
match_name[app_id] string The identifier of the application the event belongs to required
match_name[log_type] integer The type of the event (0, 1, 2 or 3) to match with required
match_name[log_name] string The name of the event to match with required

Example

{
  "funnel": {
    "max_duration": 12345,
    "steps": [
    {
      "match_name": [
        {
          "app_id": "FAAPPLI_1234567",
          "log_type": 2,
          "log_name": "event name 1"
        }
      ],
      "match_details": []
    },
    {
      "match_name": [
        {
          "app_id": "FAAPPLI_1234567",
          "log_type": 2,
          "log_name": "event name 2"
        }
      ],
      "match_details": []
    }
  ]
  }
}

Response

{
  "success": true,
  "result": [
    {
      "step": 1,
      "completions": 1,
      "average_duration": 0,
      "last_completed_at": "Fri Jan 19 09:28:54 GMT 2018"
    }
  ]
}

Explore

POST /api/funnels/explore?app_id=app_id&from=from&till=till&position=position&mode=mode

Returns the possible follow up events after a step of a given funnel sequence. This endpoint is not tied to any specific funnel.

Query Parameters

Property Type Description Default
app_id string The identifier of the app to explore -
from date The date to start looking for completions, expressed as YYYY-MM-DD -
till date The date to stop looking for completions, expressed as YYYY-MM-DD -
position integer The number of the current step to check for follow ups -
mode string Specifies the mode of search, for more slow or less fast accurate results -

Body Parameters

Property Type Description Default
funnel object An abstraction of the funnel to explore required
funnel[max_duration] float The max duration of the funnel -
funnel[steps] array of objects The sequence of steps for your funnel required
step[match_name] array of objects The events to match with your step required
step[match_details] array of objects The events details (values) to match with your step -
match_name[app_id] string The identifier of the application the event belongs to required
match_name[log_type] integer The type of the event (0, 1, 2 or 3) to match with required
match_name[log_name] string The name of the event to match with required

Example

{
  "funnel": {
    "max_duration": 12345,
    "steps": [
      {
      "match_name": [
        {
        "app_id": "FAAPPLI_1234567",
        "log_type": 2,
        "log_name": "event name 1"
        }
      ],
      "match_details": []
      },
      {
      "match_name": [
        {
        "app_id": "FAAPPLI_1234567",
        "log_type": 2,
        "log_name": "event name 2"
        }
      ],
      "match_details": []
      }
    ]
  }
}

Response

{
  "success": true,
  "result": [
    {
      "application_id": 123,
      "log_type": 1,
      "log_name": "event 123",
      "display_name": "event 123"
      "completions": 210,
      "average_duration": 0,
    },
    {
      "application_id": 123,
      "log_type": 1,
      "log_name": "event 456",
      "display_name": "event 456"
      "completions": 30,
      "average_duration": 5.3,
    },
  ]
}