Skip to main content

Override Data

Override data endpoint allows you to override the historical data in your collection with new data. The new data will replace the existing dataset of that type: all data previously present in the collection are deleted.

If the collection does not contain any data of the specified type, override data will behave like append data.

The data to be uploaded must be in csv format, with specific columns depending on the type of data you are uploading. For more information on the schema of the data, please refer to the Data Schemas section.

At each override request, the platform validates the data to ensure they conform to the schema. If the data do not conform, the override request is rejected with the validation errors that caused the non-conformity, and the existing data in the collection will not be modified.

The procedure to override the data of a collection is as follows:

  1. send a POST request to the override data endpoint with the csv file containing the data to be uploaded;
  2. retrieve the requestId from the response;
  3. poll the platform periodically to check the status of the override request with the requestId to ensure that the data override is successful.

1. Send a POST request​

To override data, you need to send a POST request to the override data endpoint:

/api/collection/{collectionId}/data/{dataType}/override

This endpoint requires the following parameters:

  • collectionId: the identifier of the collection into which you want to upload the data;
  • dataType: the type of data you want to override. Available values are: 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. ",").

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

An example of the request to override deals data to the collection my-collection-id is shown below. In the example, the csv file containing the data we want to upload is located at my-data-path/my-deals-data.csv and has a structure similar to the following:

id,name,description,status,stage,currentStageStartDatetime,value,lastUpdateDatetime,numberOfSentEmails,numberOfEmailOpens,numberOfReceivedEmails,numberOfMeetings,lastInteractionDatetime,creationDatetime,accountId,accountAverageResponseTime,companyId,companyNumberOfEmployees,companyRevenue,companyIndustry,companyType,companyDescription,companyTechnologies,companyCity,companyCountry,companyIsCustomer,contactId,contactNumberOfConversions,contactEmailDomainType,contactEmailOptedOut,contactAverageResponseTime,note1,lastSyncedAt
1,"Deal with Company X",Partnership agreement,closed_won,Negotiation,2024-06-10T09:15:30,1000.00,2024-06-18T12:30:45,5,20,5,10,2024-06-18T12:30:45,2024-05-01T08:00:00,x,5,123,50,1000060.50,Technology,private,"Leading AI solutions...",AI;Machine Learning;web,Oslo,Norway,true,456,5,company,true,5,,2024-06-18T12:30:45
2,"Deal with Company Y",Consulting agreement,closed_lost,Proposal,2024-03-15T14:20:00,5000.00,2024-04-22T09:45:15,10,30,8,5,2024-04-22T09:45:15,2024-02-01T11:30:00,y,3,456,100,5000000.00,Finance,public,"Global financial services...",finance;banking;compliance,London,United Kingdom,false,789,2,company,false,2,"X said: ""seems a great idea!""",2024-06-18T12:30:45
curl --location'https://nostradamus.u-hopper.com/api/collection/{my-collection-id}/data/deals/override' \
--header 'Authorization: Token my-secret-token' \
--form 'file=@"my-data-path/my-deals-data.csv"' \
--form 'separator=","'

2. Retrieve the override request id​

If the override request is successful (status code 202), the response will follow the UploadRequest schema defined in the OpenApi documentation. The id field in the response will contain the identifier of the override request you just sent, and the status field will be set to queued. You will need the identifier to check the status of the override request.

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

An example of the response is shown below:

{
    "id": "my-upload-request-id",
    "collectionId": "my-collection-id",
    "dataType": "deals",
    "separator": ",",
    "dumpDatetime": "2024-08-20T12:53:24.134179Z",
    "status": "queued",
    "message": null,
    "validationErrors": null
}

3. Poll the platform to check the status of the override request​

To retrieve the status of an override request, you can send a GET request to the following endpoint, replacing my-upload-request-id with the id of the override request:

/api/collection/{collectionId}/data/{dataType}/override/{my-upload-request-id}

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

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

The response (if the request succeeded, i.e. status code 200) will follow the UploadRequest 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 validation process is successfully terminated and your data upload has been accepted by the platform, causing the override of the existing data in the collection;
  • a status error indicates that the validation process terminated with errors; the failure motivation will appear in the field validationErrors of the response; the existing data in the collection will not be modified.

An example of the response is shown below:

{
    "id": "my-upload-request-id",
    "collectionId": "my-collection-id",
    "dataType": "deals",
    "separator": ",",
    "dumpDatetime": "2024-08-20T12:53:24.134179Z",
    "status": "completed",
    "message": null,
    "validationErrors": null
}

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

warning

Ensure that your override 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).