Skip to main content

Getting started

First thing you need is a collection. A collection will contain Subscription data and related data to the Subscription. Based on the historical data you provide, Churn Prediction will train AI models that you can use to obtain predictions.

When creating a new collection, there is no data in it. To request Churn Prediction invocations, historical data must first be loaded into the collection.

OpenAPI​

For comprehensive details on all generic platform operations, please refer to the OpenAPI documentation available at the following URL: OpenApi documentation.

The OpenAPI documentation provides extensive information on the API endpoints, including their methods, parameters, and responses. It is the go-to resource for understanding the underlying operations of the platform.

While the OpenAPI documentation covers the generic aspects of the platform, specific parameters and configurations unique to our implementation are detailed within this documentation.

Make sure to consult both the OpenAPI documentation and this document to get a complete understanding of the platform's capabilities and how to effectively utilize them for your specific needs.

Postman Collection​

Here you can find a Postman collection containing an example for every request available in Churn Prediction.

How to integrate​

In the sequence diagram above you can find the step required for getting an invocation with Mantissa, the required steps are:

  1. Create a collection.
  2. Upload some data.

  3. Invoke Churn Prediction in order to get prediction and analytics.

Create a collection​

To create a collection, you need to send a POST request to the collection endpoint. Required parameters to be specified in the request body are:

  • name: the name of your choice;
  • product: ChurnPrediction;
  • timezone: the default timezone for the collection.

Additionally you can specify:

  • tag: Additional metadata that can be associated to the collection.

Churn Prediction allows to specify the following properties in the collection creation request:

  • subscription: optional property as a object containing additional subscription properties;
  • invoice: optional property as a object containing additional invoice properties;
  • subscription_item: optional property as a object containing additional subscription item properties;
  • usage: required property as a object containing additional usage properties, it requires to specify at least the type property that has to be a required enum property with the specification of its possible values;
  • ticket: required property as a object containing additional ticket properties, it requires to specify at least the type property that has to be a required enum property with the specification of its possible values;
  • interaction: required property as a object containing additional interaction properties, it requires to specify at least the type property that has to be a required enum property with the specification of its possible values.

The expected input format for the object containing the additional data type properties is:

  • key: the property name;
  • value: an object with the following keys:
    • type: a string indicating the data type of the property, it can be one of enum, boolean, number, integer, date, date-time, string;
    • required: a boolean indicating if the property is required;
    • possibleValues: the list of possible values for the property (only for a property of type enum).
curl --location 'https://nostradamus.u-hopper.com/api/collection' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token my-secret-token' \
--data '{
    "name": "My Collection",
    "product": "ChurnPrediction",
    "timezone": "Europe/Rome",
    "tag": {},
    "properties": {
        "subscription": {
            "social_source": {
                "type": "enum",
                "required": false,
                "possibleValues": ["facebook", "twitter", "linkedin"]
            }
        },
        "usage": {
            "type": {
                "type": "enum",
                "required": true,
                "possibleValues": ["login", "view", "purchase"]
            }
        },
        "ticket": {
            "type": {
                "type": "enum",
                "required": true,
                "possibleValues": ["incident", "request"]
            }
        },
        "interaction": {
            "type": {
                "type": "enum",
                "required": true,
                "possibleValues": ["phone", "email", "chat"]
            }
        }
    }
}'

You can retrieve the list of the collections associated to your account by sending a GET request to the collection endpoint. For more details about the collection management, see Collection.

Upload data​

Churn Prediction supports six data type: subscription, invoice, subscription_item, usage, ticket, interaction. The data history is loaded into a collection via a POST request, in which the type of data being loaded is specified.

Data has to be passed in csv format. For details about the required data schema, see Data schemas.

The request endpoint to append new data into a collection is /api/collection/{collectionId}/data/{dataType}/append, where:

  • collectionId: the identifier of the collection into which you want to upload the data;
  • dataType: subscription, invoice, subscription_item, usage, ticket, interaction.

In the request body, you need to specify as a form-data field:

  • file, the csv file containing the data to be uploaded;
  • separator, the separator of the csv file (e.g. ",").

In the following you can find an example for uploading data of type subscription via curl and python.

curl --location'https://nostradamus.u-hopper.com/api/collection/{my-collection-id}/data/subscription/append' \
--header 'Authorization: Token my-secret-token' \
--form 'file=@"my-data-path/my-subscription-data.csv"' \
--form 'separator=","'

You can find an example CSV at this link.

At each upload request, the platform validates the data to ensure they conform to the schema. If the data do not conform, the upload request is rejected with the validation errors that caused the non-conformity.

The upload request's status changes from queued, in_progress, completed, error. When the status is completed, it means the validation process is successfully terminated and your data upload has been accepted by the platform. On the contrary, the status error indicates that the validation process terminated with errors; the failure motivation will appear in validationErrors.

You may need to poll the platform periodically to check the status of your request. This ensures that you receive timely updates on the progress and outcome of your request.

warning

Ensure that your upload request is successful (i.e. status: completed) before submitting an invocation request. Otherwise, the predictions or analyses you request will either be inaccurate (if the collection already contains data) or the invocation request will fail (if the collection does not have any data uploaded correctly).

To get the status of the upload request with id requestId, you can send a GET request to the /api/collection/{collectionId}/data/{dataType}/append/{requestId} endpoint. The response will contain the status of the request, as well as any validation errors that may have occurred.

Here is an example of how to get the status of an upload request with id my-upload-request-id and dataType subscription via curl and python.

curl --location 'https://nostradamus.u-hopper.com/api/collection/{my-collection-id}/data/subscription/append/{my-upload-request-id}' \
--header 'Authorization: Token my-secret-token'

Churn Prediction works best if the data on a collection are always up-to-date. Whenever you wish to add new points to the data history, use a POST request as above: all new data will be added to the already existing history after the validation process.

Invoke Churn Prediction​

You can invoke Churn Prediction by sending a POST request to the invocation endpoint, specifying the invocation type.

Churn Prediction supports only one invocation type: churn-prediction (ask for a Churn Prediction); it requires at least the subscription data but it is recommended to provide all the data types.

The parameters you have to specify in the request body are:

  • collectionId: the identifier of the collection on which the historical data necessary for successful invocation have been previously uploaded;
  • invocationType: type of invocation;
  • args: dictionary containing extra arguments:
    • horizon is a mandatory argument for the churn-prediction invocation type. It is a positive integer value greater than 0, representing the number of days into the future for which the likelihood of churn is predicted for each subscription.
warning

Churn Prediction relies on machine learning models, which require training on your data before generating predictions. If you are using Churn Prediction on a collection for the first time, a model will not be available immediately after uploading data. In such cases, Churn Prediction invocation will fail, with error message "Model does not exist on Model Registry".

Invocation example: churn-prediction​

Here you can find an example in which a churn-prediction invocation is requested for the collection my-collection-id with a horizon of 30 days.

curl --location 'https://nostradamus.u-hopper.com/api/invocation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token my-secret-token' \
--data '{
    "collectionId": "my-collection-id",
    "invocationType": "churn-prediction",
    "args": {
        "horizon": 30
    }
}'

The endpoint will reply with the details of the request, including the id of the request.

Results retrieval​

The results of the invocation will not be available immediately: you may need to poll the platform periodically to check the status of your request. As for data upload requests, states are: queued, in_progress, completed, error.

The error status indicates that your request failed, with the motivation expressed in invocationErrors.

Once your request reaches the completed status, you can retrieve the results using a GET request to the appropriate endpoint. The available formats for retrieving results are: csv, json, xlsx. Details on the endpoints can be found here: OpenApi documentation.

Invocation retrieval example: churn-prediction​

{
    "id": "my-invocation-request-id",
    "collectionId": "my-collection-id",
    "invocationType": "churn-prediction",
    "args": {
        "horizon": 30
    },
    "status": "queued",
    "message": null,
    "invocationErrors": null,
    "invocationResults": null
}

Using the id of the request is possible to check the status of the request:

curl --location 'https://nostradamus.u-hopper.com/api/invocation/{invocation-id}' \
--header 'Authorization: Token my-secret-token'

When the status of request changes to completed is possible to download the produced results of the invocation in the formats in which these are available, including json, csv and xlsx. In fact, an invocation can produce multiple results, and each result can be available in different formats. The primary result is the one that is considered the main result of the invocation while the others are accessory results.

The following example shows how to retrieve the primary result of an invocation in JSON format:

curl --location 'https://nostradamus.u-hopper.com/api/invocation/{invocation-id}/json' \
--header 'Authorization: Token my-secret-token'

For more details about the invocation results, see Retrieve Invocation Results.