Invoke Churn Prediction

Invoking Churn Prediction means asking for a prediction based on the data you have in your collection.

Sending an invocation is a three-step process:

1. Send an invocation
2. Retrieve the request id
3. Poll the platform to check the status of the invocation request

1. Send an invocation

To send an invocation, you need to send a POST request to the following endpoint:

/api/invocation

The request body should contain the following fields:

• collectionId: the id of the collection containing the data you want to use for the invocation;

• InvocationType: the type of the invocation you want to perform. It can be one of the following:

  • churn-prediction;
• args: a dictionary containing the arguments for the invocation. The arguments depend on the type of invocation you are performing.

The request must also include an header with the authorization token.

Invocations of type churn-prediction requires the following additional arguments:

• horizon: a positive integer value greater than 0 that represents the number of days into the future for which the likelihood of churn is predicted for each subscription.

In the example below, we send a churn prediction invocation for the collection my-collection-id.

Curl

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

Python

import requests
import json

url = "https://nostradamus.u-hopper.com/api/invocation"

payload = json.dumps({
    "collectionId": "my-collection-id",
    "invocationType": "churn-prediction",
    "args": {
        "horizon": 30
    }
})
headers = {
    'Authorization': 'Token my-secret-token',
    'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

2. Retrieve the request id

If the invocation request is successful (status code 202), the response will follow the InvocationRequest schema defined in the OpenApi documentation. The id field in the response contains the invocation request id that you will need to check the status of the invocation request, and the status field will be set to queued.

If the request is unsuccessful, the response will contain the error message.

An example of the response is shown below:

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

3. Poll the platform to check the status of the invocation request

To get the status of the invocation request with id requestId, you can send a GET request to the following endpoint:

/api/invocation/{requestId}

Here is an example of how to check the status of the append request with id my-invocation-request-id:

Curl

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

Python

import requests

url = "https://nostradamus.u-hopper.com/api/invocation/my-invocation-request-id"

payload = {}

headers = {
  'Authorization': 'Token my-secret-token'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

The response (if the request succeeded, i.e. status code 200) will follow the InvocationRequest schema defined in the OpenApi documentation. The status field in the response will indicate the status of the request.

The status can be one of the following values: queued, in_progress, completed, error. In particular:

• a status queued indicates that the request has been received by the platform and is waiting to be processed;
• a status in_progress indicates that the request is being processed;
• a status completed indicates that the invocation process is successfully terminated and the predictions or analyses are ready to be retrieved;
• a status error indicates that the invocation process terminated with errors; the failure motivation will appear in the field invocationErrors of the response.

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

An example of the response is shown below:

{
    "id": "my-invocation-request-id",
    "collectionId": "my-collection-id",
    "invocationType": "churn-prediction",
    "args": {
        "horizon": 30
    },
    "status": "completed",
    "message": null,
    "invocationErrors": null,
    "invocationResults": {
        "data": {
            "primaryResult": true,
            "status": "completed",
            "jsonAvailable": true,
            "csvAvailable": true,
            "xlsxAvailable": true
        }
    }
}