Skip to main content

Invoke Datumo

Invoking Datumo means asking for a boosting, a deduplication, or the insights, 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:

    • boosting
    • deduplication,
    • insights;
  • 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.

Depending on the invocation type, there might be additional arguments that can be set in the args object in the request body:

  • boosting: You can specify a list of boosters to execute via the boosters argument. If omitted, all available boosters will be run.
  • deduplication: You can use the exclude_companies argument.
  • insights: No extra arguments are required.

For a better explanation of each invocation, refer to the dedicated sections.

In the example below, we send a boosting invocation for the collection my-collection-id. This will run all available boosters by default since the args are null.

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": "boosting",
    "args": null
}'

Example: Boosting with a Subset of Boosters​

You can choose to execute specific subset of boosters by providing a list of their names in the boosters argument. This is useful for targeted enrichments and faster processing times. 🚀

The available boosters are:

  • name_surname
  • human
  • language

Here's how to send a boosting invocation requesting only the name_surname booster.

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": "boosting",
    "args": {
        "boosters": ["name_surname"]
    }
}'

Deduplication Example​

Here is an example of a deduplication invocation that includes the exclude_companies argument.

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": "deduplication",
    "args": {
        "exclude_companies": true
    }
}'

Insights Example​

Here is an example of a insights invocation.

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": "insights",
    "args": null
}'

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": "boosting",
    "args": null,
    "status": "queued",
    "message": null,
    "invocationErrors": null,
    "invocationResults": null
}

If you specified arguments in the request, they will be reflected in the args field of the response. For instance, if you requested specific boosters, the response would look like this:

{
    "id": "my-invocation-request-id",
    "collectionId": "my-collection-id",
    "invocationType": "boosting",
    "args": {
        "boosters": ["name_surname"]
    },
    "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 --location 'https://nostradamus.u-hopper.com/api/invocation/my-invocation-request-id' \
--header 'Authorization: Token my-secret-token'

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 for a completed invocation is shown below:

{
    "id": "my-invocation-request-id",
    "collectionId": "my-collection-id",
    "invocationType": "boosting",
    "args": {
        "boosters": ["name_surname"]
    },
    "status": "completed",
    "message": null,
    "invocationErrors": null,
    "invocationResults": {
        "data": {
            "primaryResult": true,
            "status": "completed",
            "jsonAvailable": true,
            "csvAvailable": true,
            "xlsxAvailable": true
        },
        "datasetMask": {
            "primaryResult": false,
            "status": "completed",
            "jsonAvailable": false,
            "csvAvailable": true,
            "xlsxAvailable": false
        },
        "columnReport": {
            "primaryResult": false,
            "status": "completed",
            "jsonAvailable": true,
            "csvAvailable": false,
            "xlsxAvailable": false
        },
        "overallReport": {
            "primaryResult": false,
            "status": "completed",
            "jsonAvailable": true,
            "csvAvailable": false,
            "xlsxAvailable": false
        },
        "insights": {
            "primaryResult": false,
            "status": "completed",
            "jsonAvailable": true,
            "csvAvailable": false,
            "xlsxAvailable": false
        }
    }
}