--- title: "Bulk Data Operations: Import" slug: "bulk-data-operations-import" updated: 2025-10-28T13:33:07Z published: 2025-10-28T13:33:07Z canonical: "docs.unqork.io/bulk-data-operations-import" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # Bulk Data Operations: Import > [!WARNING] > 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](/v1/docs/testing-api-endpoints-using-third-party-applications) article. > [!TIP] > 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/bulkOperations/import. Replace {environment} with the name of your Unqork environment. > [!WARNING] > Import jobs are limited to 100 MB. > [!NOTE] > 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](/v1/docs/testing-api-endpoints-using-third-party-applications?Highlight=postman#Creating) article. ```json {"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. > [!TIP] > To find a Data Model's ID value, view our [How to: Query Data Model Records Data](/v1/docs/how-to-query-data-model-records-data) article. | Yes | | fallbackRecordOwner | string (no spaces) | Enter the userId of the Unqork Service User or Express Access Credential that has authorized access to the workspace. > Create new Express Credentials using the [API Access Management](/v1/docs/api-access-management) page. | Yes | | fileFormat | CSV ZIPWITHCSV JSON ZIPWITHJSON ZIPWITHMULTIPLEJSON | Specify the file format you want to extract. File formats include: - **CSV**: Import records from a single file. - **ZIPWITHCSV**: Import records from a ZIP file containing a single file. - **JSON**: Import records from a single JSON Lines file. - **ZIPWITHJSON**: Import records from a ZIP file containing a single JSON Lines file. - **ZIPWITHMULTIPLEJSON**: Import records from a ZIP file containing JSON files where each JSON file is one single record. > [!NOTE] > The value must be uppercase. | Yes | | fileLocation | string | Enter the Unqork Cloud file address. For example, `unqorkResource/export/f22047aa-13d3-4070-8def-a8a1a401afff/0.json.gz`. > Learn how to upload a file and > > create an Unqork Cloud file address in our [Bulk Operations: Upload-Link](/v1/docs/bulk-operations-upload-link) article. | 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](/v1/docs/record-collections-viewer-job-tracker-tool) column. | Yes | | storeInData | Boolean | When set to `true`, records from the incoming file are stored under the `data` property in submission record. When set to `false`, records from the incoming file are treated as a full submission record, including the full submission data and Unqork metadata. > [!WARNING] > Unqork recommends setting this property to `true`. | Yes | ### Example Response Below is an example response of importing records: ```json    "id": "67169684ec1bf4776fa760a5",    "created": 1729533572882,    "modified": 1729533572882,    "createdBy": "creatorAccount@creatorCompany.com",    "modifiedBy": "creatorAccount@creatorCompany.com",    "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/bulkOperations/job/{jobId}` endpoint and the method. Copy the import response's `id` value and replace the job detail's `{jobId}` placeholder. For example, `https://{environment}.unqork.io/fbu/uapi/bulkOperations/job/67169684ec1bf4776fa760a5`. ### Example Response Below is an example of a Job Details endpoint response: ```json {    "id": "6711511ab056c32e103b11e5",    "created": 1729188122233,    "modified": 1729188196285,    "createdBy": "creatorName@creatorCompany.com",    "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 `data` object. When troubleshooting, review the `status` property contained in each `stepType` in the `steps` array. This value is also reflected in the [Job Tracker's Job Status](/v1/docs/record-collections-viewer-job-tracker-tool) column. Status values include: - `inProgress`: The import operation is still processing the file(s). - `completed`: The import is complete. - `canceled`: The import has been manually stopped by the user. - `partiallyCompleted`: The import is complete, but has reported issues. - `failed`: The import failed. Review each `stepType's status` value to determine which process failed. | ```json { "data": { "type": "EXPORT", "collection": "658c3c6b70573db027a0f3a2", "dataLocation": {}, "name": "Example Export 2", "steps": [], "status": "completed" }} ``` | | docs | Located in the `details` object, the `docs` objects displays the following properties: - `processed`: The amount of records successfully processed by the operation. - `total`: The total records processed. | ```json "details": {"dataLocation": {},"chunks": [],"docs": { "total": 4, "processed": 4 }}} ``` | Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. Includes the Short Answer component, Long Answer component, Select Boxes, Radio component, Dropdown, Number component and Single Checkbox. APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections. The HTTP POST method is used to send data to a server to create or update a resource, typically including the data in the body of the request. HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML. Schema is a declarative language that defines the structure, content, and constraints of the data. Unqork Service Users are server-side only credentials used in API calls and authorizations. Unlike regular express users, service users are not tied to a person. Instead, they are managed by the company account. Service users have been replaced by Express Credentials created in the API Access Management administration page. A zip file is a file format that can contain multiple files combined and compressed into one file. Since it's a type of compressed file, a zip file can be smaller in size than the files it contains. JSON Lines is a format for storing structured data that may be processed one record at a time. It works with unix-style text processing tools and shell pipelines. JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data.