All BDO endpoints are only accessible to Creator and Express Administrator users in Unqork.
The Bulk Data Operations (BDO) Import API endpoint lets you import your submission data into the Unqork platform. You can make an import request using curl, Postman, or any other service that supports a POST request.
To discover how to set up API calls using a third-party program, view our Testing API Endpoints Using Third-Party Applications article.
You can test the BDO Import endpoint using the Unqork Services page. To access the Unqork Services page, enter the following address into your browser:
https://{environment}.unqork.io/fbu/uapi/docs/documentation/#/Bulk%20Operations/import. Replace{environment}with the name of your Unqork environment.
Importing Submission Data Using Bulk Data Operations
The BDO Import method uses the HTTP POST method and the following endpoint: https://{environment}.unqork.io/fbu/uapi/bulk-operations/import. Replace {environment} with the name of your Unqork environment.
Import jobs are limited to 100 MB.
To make calls using third-party programs, you must add an authorization key/value pair to the header. To learn more, view our Testing API Endpoints Using Third-Party Applications article.
{"dataModelOrModuleId": "string","fallbackRecordOwner": "string","fileFormat": "CSV","fileLocation": "string","name": "string","storeInData": "false"}The following parameters are available for the Bulk Data Import schema:
Key | Possible Values | Description | Required |
|---|---|---|---|
dataModelOrModuleId | string (no spaces) | Specify the Data Model ID, or Module ID, containing the data you want to import.
| Yes |
fallbackRecordOwner | string (no spaces) | Enter the userId of the Unqork Service User or Express Access Credential that has authorized access to the workspace.
| Yes |
fileFormat | CSV ZIPWITHCSV JSON ZIPWITHJSON ZIPWITHMULTIPLEJSON | Specify the file format you want to extract. File formats include:
| Yes |
fileLocation | string | Enter the Unqork Cloud file address. For example,
| Yes |
name | string | Enter a value to name the import operation by. Names can include spaces. This value also displays in the Job Tracker's File Name column. | Yes |
storeInData | Boolean | When set to When set to
| Yes |
Example Response
Below is an example response of importing records:
{
"id": "67169684ec1bf4776fa760a5",
"created": 1729533572882,
"modified": 1729533572882,
"createdBy": "[email protected]",
"modifiedBy": "[email protected]",
"data": {
"type": "UPDATE",
"collection": "658c3c6b70573db027a0f3a2",
"dataLocation": {
"database": "unqork",
"collection": "submissions",
"entityType": "MODULE"
},
"name": "Import API Test 1",
"steps": [
{
"stepType": "UNZIP",
"status": "created",
"options": {
"type": "UPDATE",
"update": {
"upsert": true,
"uniqueKey": "",
"metaOverride": {
"form": "658c3c6b70573db027a0f3a2",
"owner": "express-access-user"
},
"storeInData": false
}
},
"files": [
{
"source": {
"name": "0.json.gz",
"location": "unqorkResource/export/f22047aa-13d3-4070-8def-a8a1a401afff/0.json.gz",
"format": "ZIPWITHJSON"
},
"destination": {
"location": "unqorkResource/update/0f8eabed-2926-405c-801d-020fd80ee79c.json",
"format": "JSON"
}
}
],
"collection": "658c3c6b70573db027a0f3a2"
},
{
"stepType": "UPDATE",
"status": "created",
"options": {
"update": {
"headers": [],
"delimiter": ",",
"uniqueKey": "",
"upsert": true,
"metaOverride": {
"form": "658c3c6b70573db027a0f3a2",
"owner": "express-access-user"
},
"storeInData": false
}
},
"files": [
{
"source": {
"name": "0f8eabed-2926-405c-801d-020fd80ee79c.json",
"location": "unqorkResource/update/0f8eabed-2926-405c-801d-020fd80ee79c.json",
"format": "JSON"
}
}
],
"collection": "658c3c6b70573db027a0f3a2",
"dataLocation": {
"database": "unqork",
"collection": "submissions",
"entityType": "MODULE"
}
},
{
"stepType": "CLEARDATA",
"status": "created",
"files": [
{
"source": {
"location": "unqorkResource/update/0f8eabed-2926-405c-801d-020fd80ee79c.json",
"format": "JSON"
}
}
],
"collection": "658c3c6b70573db027a0f3a2"
}
]
}}Viewing a Bulk Data Import Operation Job's Details
After starting a Bulk Data Import, you can view the job details using the /fbu/uapi/bulk-operations/job/{jobId} endpoint and the GET method. Copy the import response's id value and replace the job detail's {jobId} placeholder. For example, https://{environment}.unqork.io/fbu/uapi/bulk-operations/job/67169684ec1bf4776fa760a5.
Example Response
Below is an example of a Job Details endpoint response:
{
"id": "6711511ab056c32e103b11e5",
"created": 1729188122233,
"modified": 1729188196285,
"createdBy": "[email protected]",
"modifiedBy": null,
"data": {
"type": "UPDATE",
"collection": "658c3c6b70573db027a0f3a2",
"dataLocation": {
"database": "unqork",
"collection": "submissions",
"entityType": "MODULE"
},
"name": "Import Example 1",
"steps": [
{
"stepType": "UPDATE",
"id": "6711512eb056c32e103b11e6",
"status": "completed",
"files": [
{
"source": {
"name": "0.csv",
"location": "unqorkResource/export/78b9abdc-df4a-42e0-8b02-1ce0377a1a61/0.csv",
"format": "CSV"
}
}
],
"options": {
"update": {
"headers": [],
"delimiter": ",",
"uniqueKey": "",
"upsert": true,
"metaOverride": {
"form": "658c3c6b70573db027a0f3a2",
"owner": "test-authenticated-user"
},
"storeInData": true
}
},
"dataLocation": {
"database": "unqork",
"collection": "submissions",
"entityType": "MODULE"
},
"collection": "658c3c6b70573db027a0f3a2",
"details": {
"dataLocation": {
"database": "unqork",
"collection": "submissions",
"entityType": "MODULE"
},
"chunks": [
{
"status": "completed",
"chunkQueueId": "1",
"chunkRecord": {
"start": 2,
"end": 5
},
"docs": {
"total": 4,
"processed": 4
},
"chunkFileKey": "bulkDataOperation/update/unqorkResource/export/78b9abdc-df4a-42e0-8b02-1ce0377a1a61/0.csv-0.csv",
"auditFileKey": "unqorkResource/audit/6711512eb056c32e103b11e6/1.json.gz",
"startTime": "2024-10-17T18:02:54.728Z",
"endTime": "2024-10-17T18:02:55.200Z"
}
],
"docs": {
"total": 4,
"processed": 4
}
}
}
],
"status": "completed"
}}Using the above example response, the following properties might be important for Creator processes or pipeline development:
Response Property | Description | Example |
|---|---|---|
status | The current status of the operation. The overall operation status is displayed at the bottom of the Status values include:
|
|
docs | Located in the
|
|