How to Upload Data to Project
One of the main scenarios to interact with Timeline API is to automate the process of uploading data to the project. Follow the guideline below to create a new project and upload data there.
Important. You need CSV files with the data to upload. These files should meet certain conditions. For details on the file structure and what is the mapping process, see Data Requirements and Mapping.
1. Create a project to upload.
To create a new project, send a POST request to the endpoint:
{your.timeline.instance}.com/api/ext/1.0/project
In the request body, provide a project name. Example:
{
"name": "New project"
}
This project will have the Timeline API data source enabled by default. You become a project Owner. The process is similar to if you create a project in the Timeline UI.
In response to this request, you will receive a projectId parameter. This value is needed for future upload actions.
CURL request example:
curl --location --request POST 'https://online.timelinepi.com/api/ext/1.0/project' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer b2SampleTokenF1dGg6ODBkNTQ4MjgtMGVlDKDKFOA1LThlZjUtZGE1ZTQ0MTFkOjc1OGNFJFJFJtNDI4Zi1iNGU4LTdjNzczZDc5M2E1OQ==' \ --data '{ "name": "New project" }'
Response:
{
"id": 6723,
"name": "New project",
"role": "OWNER",
"url": "https://online.timelinepi.com/project/6723/"
}
2. Generate an upload URL with the temporary storage for a file.
Send a POST request to generate and retrieve an upload URL to transmit files. In the request, specify projectId of the created project. Endpoint:
{your.timeline.instance}.com/api/ext/1.0/project/{projectId}/merge/upload-url
In the request body, provide a file name. Example:
{
"fileName": "new_data.csv"
}
In response, you will get a URL that will be a temporary storage for uploaded files. The files will be loaded to Timeline from this storage.
CURL request example:
curl --location --request POST 'https://online.timelinepi.com/api/ext/1.0/project/6723/merge/upload-url' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer b2SampleTokenF1dGg6ODBkNTQ4MjgtMGVlDKDKFOA1LThlZjUtZGE1ZTQ0MTFkOjc1OGNFJFJFJtNDI4Zi1iNGU4LTdjNzczZDc5M2E1OQ==' \ --data '{ "fileName": "new_data.csv" }'
Response:
{
"url": "https://online.timelinepi.com/timelinepi-project-upload-devtpi/uploads/projects/6963/1693414962910/new_data.csv?Expires=1693416162&Key-Pair-Id=APKAJJKHFKJHJHHWCD6WJ7Q&Signature=OvrUVnbD8-Z31hp8dyIiwQZvgG7XCVb9SEiSmXl-AEFpivtAb1nRIwj7PqljHVhAg8LUdCD3z0AcGa2vwVJBKFDFKDHianvm0MvYMVtiwdKVnAK48OdU6XwI6vxYq5fympbnw1wVwN3PHanjNMyg9l~Pe~~iL9KtvUzJ7gUcFBgHsYHMUvhxYkogE46AzjDDP-QGlqE60jVzuSZcurE0yhdDBXp2pWdUEu4dUsM2g3A9q3xNHXDDkdDAkJzF9A2Z1w3t0bSOxdeiMbttV1MFlt6tsll69IXugydkfdsfjJJfkBdPmhs1MOksvfS7-b0KtvPDthXwPMMIk2g__",
"key": "projects/6723/1693414962910/new_data.csv",
"headers": {
"x-amz-acl": "bucket-owner-full-control"
}
}
3. Transfer files to the temporary storage.
Send a PUT request to the URL generated in step 2 to upload the file to the temporary storage. Include the headers received along with the URL and provide the raw CSV file data as the request body.
CURL request example:
curl --location --request PUT 'https://online.timelinepi.com/timelinepi-project-upload-devtpi/uploads/projects/6963/1693414962910/new_data.csv?Expires=1693416162&Key-Pair-Id=APKAJJKHFKJHJHHWCD6WJ7Q&Signature=OvrUVnbD8-Z31hp8dyIiwQZvgG7XCVb9SEiSmXl-AEFpivtAb1nRIwj7PqljHVhAg8LUdCD3z0AcGa2vwVJBKFDFKDHianvm0MvYMVtiwdKVnAK48OdU6XwI6vxYq5fympbnw1wVwN3PHanjNMyg9l~Pe~~iL9KtvUzJ7gUcFBgHsYHMUvhxYkogE46AzjDDP-QGlqE60jVzuSZcurE0yhdDBXp2pWdUEu4dUsM2g3A9q3xNHXDDkdDAkJzF9A2Z1w3t0bSOxdeiMbttV1MFlt6tsll69IXugydkfdsfjJJfkBdPmhs1MOksvfS7-b0KtvPDthXwPMMIk2g__' \ --header 'x-amz-acl: bucket-owner-full-control' \ --header 'Content-Type: text/csv' \ --header 'Authorization: Bearer b2SampleTokenF1dGg6ODBkNTQ4MjgtMGVlDKDKFOA1LThlZjUtZGE1ZTQ0MTFkOjc1OGNFJFJFJtNDI4Zi1iNGU4LTdjNzczZDc5M2E1OQ==' \ --data '@/C:/Users/myname/Desktop/new_data.csv'
4. Load data from temporary storage to the project.
Send a POST request to load files from temporary storage to the project. In the request, specify projectId of the needed project. Endpoint:
{your.timeline.instance}.com/api/ext/1.0/project/{projectId}/merge/process
In the request body, provide a file key and a column mapping for this file. fileKeys should be the same as a "key" value returned in step 2 in response. Follow How to Map Files in Request to learn more about column mapping.
In response, you will get a processingId.
CURL request example:
curl --location --request POST 'https://online.timelinepi.com/api/ext/1.0/project/6723/merge/process' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer b2SampleTokenF1dGg6ODBkNTQ4MjgtMGVlDKDKFOA1LThlZjUtZGE1ZTQ0MTFkOjc1OGNFJFJFJtNDI4Zi1iNGU4LTdjNzczZDc5M2E1OQ==' \ --data '{ "fileKeys": [ "projects/6723/1693414962910/new_data.csv" ], "mapping": { "event_id": { "title": "Event name", "type": "String" }, "timeline_id": { "title": "TimelineID", "type": "String" }, "timestamp": { "title": "Timestamp", "type": "Date" }, "attributes": [ { "title": "Employee", "type": "String" } ] } }'
Response:
{
"processingId": "uojfdsddfdFD1pjxnvw3HA"
}
5. Monitor the upload process.
Send a GET request with the processingId returned by the request on step 4. Endpoint:
{your.timeline.instance}.com/api/ext/1.0/processing/{processingId}
Poll the processing endpoint until the status becomes FINISHED. As a result, the file will be loaded to the specified project.
CURL request example:
curl --location 'https://online.timelinepi.com/api/ext/1.0/processing/uojfdsddfdFD1pjxnvw3HA' \ --header 'Authorization: Bearer b2SampleTokenF1dGg6ODBkNTQ4MjgtMGVlDKDKFOA1LThlZjUtZGE1ZTQ0MTFkOjc1OGNFJFJFJtNDI4Zi1iNGU4LTdjNzczZDc5M2E1OQ=='
Response:
"id": "uojfdsddfdFD1pjxnvw3HA", "status": "FINISHED", "result": { "uploadId": 23355 },
05.09.2024 16:23:54