Public API Endpoints

Welcome to the MorphL - Churning Users API wiki!

Below you can find the documentation for authenticating and retrieving predictions from the API endpoints.

All API paths described below are relative to your API domain name (ex. mydomain.api.morphl.io).

1) Authenticating

POST /authorize

During the MorphL Orchestrator setup, a random API key and API secret are generated. These can be retrieved from your Orchestrator instance, from the /home/airflow/.morphl_secrets.sh file:

export MORPHL_API_KEY=pk_*******************
export MORPHL_API_SECRET=sk_*******************

Once you have retrieved the API key & secret, you can make a request to authenticate. In case of success, the API will return a JSON response containing a JWT (JSON Web Token) that will be used for authorizing requests to other API endpoints.

Params	Headers	Success	Error
api_key & api_secret	-	{token:***}	{error:"Error message"}

Sample request using Postman:

2) Retrieving Predictions

Once a JWT has been retrieved using the /authorize endpoint, you can make requests to API endpoints that are responsible for returning predictions. If an invalid JWT is used, the endpoints will return an error with a 401 Unauthorized HTTP status code.

Single Prediction Based on Client ID

GET /churning/getprediction/<client_id>

Headers	Success	Error
Authorization:<token>	{prediction: {client_id: <client_id>, prediction: < probability>}, status: 1}	{status:0, error:"Error message"}

In the above table:

• <client_id> is the Google Analytics Client ID (ex. GAxxxx.xxxx format);
• <token> is the JWT returned by the /authorize endpoint;
• <probability> is a floating point number between 0 and 1 that represents the probability that the respective Client ID will churn.

Sample request using Postman:

Predictions List

GET /churning/getpredictions

Params	Headers	Success	Error
page (optional)	Authorization:<token>	{predictions:[{client_id:<client_id>, prediction:<probability>},...],next_paging_state:<page_token>, status:1}	{status:0, error:"Error message"}

The endpoints retrieves 100 predictions at a time.

In the above table:

• <token> is the JWT returned by the /authorize endpoint;
• <client_id> is a Google Analytics Client ID (ex. GAxxxx.xxxx format);
• <probability> is a floating point number between 0 and 1 that represents the probability that the respective Client ID will churn.
• <page_token> is a pagination token that can be sent as a GET param (?page=<page_token>) to retrieve the next page of predictions.

Sample request using Postman:

Predictions Statistics

GET /churning/getpredictionstatistics

This endpoint retrieves statistics about the number of predictions that have been generated and model training scores.

Params	Headers	Success	Error
-	Authorization:<token>	{model_statistics:[{loss:<loss>, accuracy:<acc>,day_as_str:<date>},...],churned:<churned>, not_churned:<not_churned>,predictions:<no_predictions>, status:1}	{status:0, error:"Error message"}

In the above table:

• <token> is the JWT returned by the /authorize endpoint;
• model_statistics is a list of the model trainings, with an associated date (<day_as_str>) and scores (<loss> and <acc>)
• <no_predictions> is the total number of generated predictions
• <churned> is the total number of generated predictions where the churn probability is greater than 0.5
• <not_churned> is the total number of generated predictions where the churn probability is lower than 0.5

Sample request using Postman: