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, Sales Forecasting will train AI models that you can use to obtain predictions.

When creating a new collection, there is no data in it. To request Sales Forecasting 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 Sales Forecasting.

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 Sales Forecasting in order to get predictions.

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: SalesForecasting;
  • timezone: the default timezone for the collection.

Additionally you can specify:

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

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​

Sales Forecasting supports one data type: deals. 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: deals.

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 deals via curl and python.

curl --location'https://nostradamus.u-hopper.com/api/collection/{my-collection-id}/data/deals/append' \
--header 'Authorization: Token my-secret-token' \
--form 'file=@"my-data-path/my-deals-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 deals via curl and python.

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

Sales Forecasting 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 Sales Forecasting​

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

Sales Forecasting supports only one invocation type: sales-forecasting (ask for a Sales Forecasting); it requires deals data.

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: the number of months for which you want to predict the revenue. Should be an integer between 1 and 12.
    • (optional) first_month_to_predict: a month in YYYY-MM format indicating when the forecast should begin. If not specified, forecasting will automatically start from the month immediately following the last month in your data.
warning

Sales Forecasting relies on machine learning models, which require training on your data before generating predictions. If you are using Sales Forecasting on a collection for the first time, a model will not be available immediately after uploading data. In such cases, Sales Forecasting will apply a simpler algorithm that estimates revenue based on the expected closure date of the deals.

Invocation example: sales-forecasting​

Here you can find an example in which a sales-forecasting invocation is requested for the collection my-collection-id.

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": "sales-forecasting",
    "args": {
    "horizon": 2
    }
}'

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: sales-forecasting​

{
    "id": "my-invocation-request-id",
    "collectionId": "my-collection-id",
    "invocationType": "sales-forecasting",
    "args": {
    "horizon": 2
    },
    "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.