--- title: "Importing Data with the Ingest API" slug: "ingest-api-user-guide" updated: 2026-06-25T16:20:13Z published: 2026-06-25T16:20:13Z canonical: "documentation.lakesidesoftware.com/ingest-api-user-guide" --- > ## Documentation Index > Fetch the complete documentation index at: https://documentation.lakesidesoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # Importing Data with the Ingest API ## What is Data Ingest? Data Ingest is a feature in SysTrack that allows cloud customers to import external user or device data into SysTrack from CSV files and make it available through report views in dashboards, groups, and queries. A typical use case is enriching SysTrack data with business-owned attributes such as department, asset tag, purchase date, employee ID, or other fields that are maintained outside SysTrack. > [!WARNING] > **IMPORTANT**: Currently, the Data Ingest feature is API-only. All operations run through REST endpoints, and no dedicated UI is available. This guide describes the recommended workflow, from schema design through audit review. ## How Ingest Works The Ingest API uses a staged process to provide validation and feedback that helps prevent failed or incorrect imports: 1. You define the target schema for users or devices and send it to SysTrack. 2. You send a CSV file to SysTrack that matches the defined schema. 3. SysTrack analyzes the uploaded file and reports any differences between the CSV and the current schema. 4. You review the differences and decide how to proceed. This step ensures that you validate schema changes and data updates before ingestion. 5. You explicitly call the process endpoint to start ingestion. 6. SysTrack ingests the data and makes it available through the [RPT_EnrichedDevices](/documentation/docs/enriched-devices-ingest-rpt-enricheddevices) and [RPT_EnrichedUsers](/documentation/docs/enriched-users-ingest-rpt-enrichedusers) report views. 7. SysTrack associates each ingested device with its WGUID, optimized to run during off-hours to minimize impact. 8. Ingested users do not need to be associated with SysTrack data. Use email as a unique identifier to map user data. You can use the Ingest API to update your imported data as often as needed. ## Data Ingest Limitations - Only CSV files are supported. - You can upload up to 2,000 bytes of metadata per row in a CSV file. - A CSV file can contain rows for up to 125% of your current device or user count. - The schema must be in the JSON format. ## Prerequisites Before you start, ensure you have: - A valid **Ingest** API key for authentication. See [Manage API Keys](/documentation/docs/manage-api-keys). - A CSV file with data you are importing: users or devices. - For devices, a key column type defined for mapping: - Use `SystemName` when device rows should be matched by system name. - Use `Serial` when device rows should be matched by serial number. - A validated column design: - Column names contain only letters, digits, and underscores. - Column names does not match [SQL reserved words](https://support.microsoft.com/en-us/access/sql-reserved-words). - Supported data types are `int`, `double`, `datetime`, `guid`, `boolean`, and `string`. - String columns have a `length` value greater than 0. ## Step 1: Build the Schema If you do not have a saved schema, create one from your CSV file during the following steps or use the provided examples. ### Start From the Matching Template - If importing devices, start from `IngestAPI_Devices_Template.csv`. - If importing users, start from `IngestAPI_Users_Template.csv`. [](https://cdn.document360.io/87d11426-6b1f-4b19-b593-b71e55a81af3/Images/Documentation/IngestAPI_Devices_Template.csv)IngestAPI_Devices_Template262 Byte[](https://cdn.document360.io/87d11426-6b1f-4b19-b593-b71e55a81af3/Images/Documentation/IngestAPI_Devices_Template.csv)[](https://cdn.document360.io/87d11426-6b1f-4b19-b593-b71e55a81af3/Images/Documentation/IngestAPI_Users_Template.csv)IngestAPI_Users_Template244 Byte[](https://cdn.document360.io/87d11426-6b1f-4b19-b593-b71e55a81af3/Images/Documentation/IngestAPI_Users_Template.csv) **Example device schema mapping for `IngestAPI_Devices_Template.csv`** `IngestAPI_Devices_Template.csv` headers: - `SystemName` — the key column - `AssetTag` - `DepartmentGuid` - `SupportTier` - `PurchasePrice` - `PurchaseDate` - `IsLoaner` Example device schema: ```json {   "keyColumn": {      "name": "SystemName",      "keyType": "SystemName"   },   "columns": [      {         "name": "SystemName",         "type": "string",         "length": 100      },      {         "name": "AssetTag",         "type": "string",         "length": 50      },      {         "name": "DepartmentGuid",         "type": "guid"      },      {         "name": "SupportTier",         "type": "int"      },      {         "name": "PurchasePrice",         "type": "double"      },      {         "name": "PurchaseDate",         "type": "datetime"      },      {         "name": "IsLoaner",         "type": "boolean"      }   ] } ``` **Example user schema mapping for `IngestAPI_Users_Template.csv`** `IngestAPI_Users_Template.csv` headers: - `Username` - `EmployeeId` - `Department` - `HireDate` - `IsManager` Example user schema: ```json {   "columns": [      {         "name": "Username",         "type": "string",         "length": 100      },      {         "name": "EmployeeId",         "type": "int"      },      {         "name": "Department",         "type": "string",         "length": 50      },      {         "name": "HireDate",         "type": "datetime"      },      {         "name": "IsManager",         "type": "boolean"      }   ] } ``` ### Draft the Schema from Your CSV Headers 1. Create a JSON file for your schema in a text editor. 2. Add one schema column entry for each CSV header. 3. Infer type per column using real sample values: - `boolean`: values like `true` or `false`. - `int`: whole numbers only. - `double`: decimal numbers. - `datetime`: ISO-like timestamps such as `2025-01-15T00:00:00Z`. - `guid`: GUID format values. - `string`: anything else. 4. For each `string` column, set `length` to a safe maximum expected value. ### Add Device Key Mapping Explicitly (Devices Only) 1. Choose the matching strategy: - `SystemName` if your CSV has stable system name values. - `Serial` if your CSV has stable serial values. 2. Set `keyColumn.name` to that exact CSV header. 3. Make sure that same column is also present in `columns` with the required type. ## Step 2: Submit the Schema Call the schema endpoint in two situations: before your first upload for a given table type, and any time you need to change the schema (adding, removing, or modifying columns). Use one of these endpoints (see [Update an ingest schema](/api/apidocs/update-an-ingest-schema)): - `PUT /ingestapi/tableType/devices/schema` - `PUT /ingestapi/tableType/users/schema` Paste your schema JSON as the request body. Expected result: - SysTrack accepts the schema update. - Old ingested records remain (if any). ## Step 3: Upload the CSV File Upload the CSV file as raw `text/csv` content. Use one of these endpoints (see [Upload a CSV file](/api/apidocs/upload-a-csv-file)): - `POST /ingestapi/tabletype/devices/csv` - `POST /ingestapi/tabletype/users/csv` What to do: 1. Send the CSV body with the `text/csv` content type. 2. Review the response sections: - `added` - `deleted` - `existing` with `isChanged: false` and `isChanged: true` Expected result: - The upload succeeds. - The response shows a schema-difference analysis that indicates whether you can continue. - Upload does not automatically start processing. - If you upload a second CSV before processing the first, it replaces the first file. ## Step 4: Decide Whether to Adjust the Schema If the upload response shows unexpected added, deleted, or changed columns, stop and correct the schema or the CSV before processing. Accepted for processing: 1. Header order does not have to match the schema order. 2. String values may be shorter than the schema length. In this case, the column still appears under `existing` with `isChanged: true`. Not accepted for processing: 1. `added` columns. 2. `deleted` columns. 3. Type mismatches. 4. String values longer than schema length. What to do: 1. If the upload response shows no added or deleted columns and all `isChanged` values are `false`, proceed to the next step. 2. If the only change is shorter string values within the schema limit, proceed to the next step. 3. If the CSV is incorrect, fix the file and upload it again. 4. If the schema is outdated, update it and upload the CSV again. Expected result: - The upload response reflects the expected structure. ## Step 5: Start Processing Once the uploaded CSV looks correct, start the ingest run. Use one of these endpoints (see [Process a CSV file](/api/apidocs/process-a-csv-file)): - `POST /ingestapi/tabletype/devices/process` - `POST /ingestapi/tabletype/users/process` What to do: 1. Send the process request. 2. Save the returned `ingestId`. It is required to track the run result. Expected result: - The response returns a new `ingestId`. ## Step 6: Monitor the Run Status Use the `ingestId` to check the run state. Use: - `GET /ingestapi/status/{ingestId}` (see [Get ingest status](/api/apidocs/get-ingest-status)) What to do: 1. Poll the endpoint until the status reaches a final state. 2. If the run fails, start it again. Expected result: - You know whether the run completed successfully or failed. ## Step 7: Remove Uploaded or Current Ingest Data When Needed If you need to reset the staged file or clear current ingested data, use the delete endpoint for the relevant table type. Use one of these endpoints (see [Delete ingest data](/api/apidocs/delete-ingest-data)): - `DELETE /ingestapi/tabletype/devices` - `DELETE /ingestapi/tabletype/users` Use this endpoint carefully. It removes the current uploaded file and ingested data for that table type. Expected result: - The current ingest data for the selected table type is removed. ## Step 8: Review Ingest History Use the history endpoint to confirm completed work and review prior runs. Use: - `GET /ingestapi/history` (see [Get ingest history](/api/apidocs/get-ingest-history)) Recommended uses: 1. Review recent runs. 2. Filter by `category` to focus on `users` or `devices`. 3. Filter by `startTime` and `endTime` when investigating a specific time range. Expected result: - You can confirm start time and end time of each run. ## Step 9: Review Audit Records Use the Audit API to verify who performed ingest actions. Use: - `GET /auditapi/ingest/actions` (see [Get ingest action audit records](/api/apidocs/get-ingest-action-audit-records)) - `GET /auditapi/ingest/actions/{actionType}` (see [Get ingest action audit records by type](/api/apidocs/get-ingest-action-audit-records-by-type)) Recommended uses: 1. Review all ingest-related actions in a time range. 2. Filter by `runBy` for operator-specific auditing. 3. Filter by `actionType`. Expected result: - You can see who ran ingest actions, from which IP address, and when. ## Ingest API Troubleshooting ### Schema Errors | Error Message | Reason | How to Fix | | --- | --- | --- | | KeyColumn is required for tableType 'devices'. | A device schema was submitted without a device key column. | Add `keyColumn` to the device schema request. | | Length is required for string column '{columnName}'. | A string column was defined without a length. | Add a positive `length` value for that string column. | | The key column was defined with name '{name}' and KeyType '{keyType}'. No column was found with the name '{name}' and type '{requiredType}'. | The declared device key column does not match a valid column definition in the schema. | Make sure the key column also appears in `columns` with the same name and the required type. | ### Upload Errors | Error Message | Reason | How to Fix | | --- | --- | --- | | The column name 'WGUID' is reserved and cannot be used. | The CSV header included `WGUID`, which is reserved for the internal mapping process. | Remove the `WGUID` column from the CSV. For device imports, use the configured key column such as `SystemName` or `Serial` instead. | | The number of the header columns does not match with the row '{rowNum}'. | At least one data row has a different number of values than the header. | - Make sure every row has the same number of fields as the header row. - Check for extra commas, missing values, or broken quoting in the reported row. | ### Process Errors | Error Message | Reason | How to Fix | | --- | --- | --- | | The blob does not exist. | Processing was started before a CSV was uploaded, or the staged upload is no longer present. | 1. Upload the CSV file again. 2. Retry processing. Or 1. Check the process status. 2. If it’s `Success`, no need to process again. | | The column '{column}' in csv was not found in the table definition. | The uploaded CSV contains a column that is not defined in the saved ingest schema. | 1. Remove the extra column from the CSV, or update the schema so that it includes that column. 2. Upload again after making the correction. | | The number of columns in the CSV do not match a number of columns that previously were defined. Line: '{currentLineNumber}' | A data row does not match the number of columns expected from the saved schema. | 1. Correct the reported row so that it has the expected number of values. 2. Check for extra delimiters, missing delimiters, or broken quoting. 3. Upload and process again after the correction. | | The data '{value}' of the column '{columnName}' cannot be parsed to '{dataType}' data type. Line: '{currentLineNumber}' | A value does not match the type defined in the saved schema. | 1. Correct the CSV value so it matches the schema type. 2. If the schema type is wrong, update the schema first, then upload and process again. |