--- title: "Importing Data with the Ingest API" slug: "ingest-api-user-guide" description: "Import user or device data from CSV files into SysTrack with the Ingest API: build the schema, upload and process the file, and review the history." status: "update" updated: 2026-11-03T15:37:10Z published: 2026-11-03T15:37:10Z 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. Users may also refer to this process as data ingestion or data ingress. 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. This guide walks you through the recommended workflow, from schema design through audit review. > [!WARNING] > **IMPORTANT**: Currently, the Data Ingest feature is API-only. All operations run through REST API endpoints, and no dedicated UI is available. ## 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. After the first successful ingest run, the data is available through the `RPT_EnrichedDevices` and `RPT_EnrichedUsers` report views. 7. SysTrack associates each ingested device with its SysTrack system identifier (WGUID), optimized to run during off-hours to minimize impact. 8. Ingested users do not need to be associated with SysTrack data. To match ingested users with SysTrack data, use the same identifier format as the SysTrack column that you match. See [Match the User Identifier Format](/documentation/docs/ingest-api-user-guide#match-the-user-identifier-format-users-only). You can use the Ingest API to update your imported data as often as needed. ## Data Ingest Limitations - Only CSV files are supported. - Each row in a CSV file can be up to 2,000 bytes, counting all values and separators in UTF-8. - A CSV file can contain rows for up to 125% of the devices or users in your tenant at upload time. - In the schema, the sizes of all columns can total up to 2,048 bytes. Each column counts by its type: `int` 4 bytes, `double` 8 bytes, `datetime` 8 bytes, `guid` 16 bytes, `boolean` 1 byte, and `string` 2 bytes for each character of its `length`, plus 2 bytes. - The schema must be in the JSON format. ## Prerequisites Before you start, ensure you have: - A valid **Ingest** API key for authentication. Send the key in the `systrack-api-key` header of each request. See [Manage API Keys](/documentation/docs/manage-api-keys). - The base URL of your SysTrack API. The base URL depends on your SysTrack installation. The endpoints in this guide start after the base URL. - 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. - 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?sv=2026-02-06&spr=https&st=2026-11-08T16%3A44%3A40Z&se=2026-11-08T17%3A44%3A40Z&sr=c&sp=r&sig=qisdhDanNsKlnNdUfoDf%2Fh5nMNpM6ukMbXd5cQIZXQA%3D)IngestAPI_Devices_Template262 Byte[](https://cdn.document360.io/87d11426-6b1f-4b19-b593-b71e55a81af3/Images/Documentation/IngestAPI_Devices_Template.csv?sv=2026-02-06&spr=https&st=2026-11-08T16%3A44%3A40Z&se=2026-11-08T17%3A44%3A40Z&sr=c&sp=r&sig=qisdhDanNsKlnNdUfoDf%2Fh5nMNpM6ukMbXd5cQIZXQA%3D)[](https://cdn.document360.io/87d11426-6b1f-4b19-b593-b71e55a81af3/Images/Documentation/IngestAPI_Users_Template.csv?sv=2026-02-06&spr=https&st=2026-11-08T16%3A44%3A40Z&se=2026-11-08T17%3A44%3A40Z&sr=c&sp=r&sig=qisdhDanNsKlnNdUfoDf%2Fh5nMNpM6ukMbXd5cQIZXQA%3D)IngestAPI_Users_Template244 Byte[](https://cdn.document360.io/87d11426-6b1f-4b19-b593-b71e55a81af3/Images/Documentation/IngestAPI_Users_Template.csv?sv=2026-02-06&spr=https&st=2026-11-08T16%3A44%3A40Z&se=2026-11-08T17%3A44%3A40Z&sr=c&sp=r&sig=qisdhDanNsKlnNdUfoDf%2Fh5nMNpM6ukMbXd5cQIZXQA%3D) **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. To get valid device key values, use the [RPT_System_Config](/documentation/docs/system-configuration-information) report view: - For `SystemName`, use the `SystemId` column. - For `Serial`, use the `SerialNumber` column. Copy the values exactly as SysTrack stores them. In some environments, `SystemId` contains a fully qualified name. Do not shorten it. Devices without configuration inventory do not appear in `RPT_System_Config`. ### Match the User Identifier Format (Users Only) For user imports, SysTrack does not validate or change the user identifier value. You can ingest any format, for example email, UPN, or `DOMAIN\user`. To match ingested user data with SysTrack data in dashboards, groups, and queries, use the same format as the SysTrack column that you match it with. | Report View | Column | Format | | --- | --- | --- | | [RPT_User_Info](/documentation/docs/user-information-user-info) | `UserName` | `DOMAIN\user`. Local accounts on workgroup computers and macOS local users appear as `COMPUTERNAME\user`. | | [RPT_User_Active_Directory](/documentation/docs/user-active-directory-rpt-user-active-directory) | `UserEmail` | Email. Available only for users with Active Directory inventory. | | [RPT_User_Active_Directory](/documentation/docs/user-active-directory-rpt-user-active-directory) | `UserPrincipal` | UPN. Available only for users with Active Directory inventory. | ### Prepare the CSV File Prepare the CSV file for the Ingest API so that its headers match the schema and its values match the column types. A file that does not meet these requirements can fail processing. #### CSV File Format Save the CSV file with UTF-8 encoding and use a comma as the delimiter. Excel in regions that use a decimal comma saves CSV files with semicolons as delimiters. The Ingest API reads such a file as one column. #### CSV Header Names CSV header names must match the column names in the schema. Matching ignores letter case. The Ingest API does not remove spaces from header names. A header with a space before or after the name, for example `' PurchasePrice '`, does not match the schema column. In this case, the upload response lists the name with spaces under `added` and the schema column under `deleted`, and processing fails. A common cause is a space after each comma in a header line that you typed, or spaces in Excel header cells. #### CSV Values The Ingest API keeps spaces in values. In `string` columns, spaces count toward the column length. In the device key column, remove spaces before and after the values, or the device rows do not match. Every cell in an `int`, `double`, `datetime`, `guid`, or `boolean` column must have a value. An empty cell in these columns fails processing, even if the upload response does not show a problem. Cells in `string` columns can be empty. Values in number, date, and boolean columns must use these formats: | Data Type | Accepted Values | Values That Fail | | --- | --- | --- | | `int` | Whole numbers without separators, for example `1345`. | Numbers with separators, for example `1,345`. | | `double` | Numbers with a dot as the decimal separator and with the decimal part, for example `1345.00` or `1345.50`. | - Whole numbers without a decimal point, for example `1345`. - Numbers with a thousands separator, for example `1,345.50`. - Numbers with a currency symbol, for example `$1345.00`. | | `datetime` | ISO 8601 dates, for example `2022-03-14T00:00:00Z` or `2022-03-14`. | Dates in day-first order, for example `14/03/2022`. | | `boolean` | `true` or `false` in any letter case. Excel `TRUE` and `FALSE` values are accepted. | `Yes`, `No`, `1`, and `0`. | > [!WARNING] > **IMPORTANT**: In a `double` column, the Ingest API can accept the value `1,345` as 1.345 without an error. In a `datetime` column, dates are read in US order, so `03/04/2022` is read as March 4. #### Save the CSV File from Excel Excel saves each cell in a CSV file as it is shown on the screen. Before you save the file from Excel, format the columns: 1. Format number columns as **Number** with the required decimal places, and clear **Use 1000 Separator (,)**. Do not use the **Comma Style**, **Accounting**, or **Currency** formats. These formats add thousands separators and padding spaces. 2. Format date columns with a custom format, for example `yyyy-mm-dd`. 3. Before you paste the device key values, format the device key column (`SystemName` or `Serial`) as **Text**. Otherwise, Excel removes leading zeros and changes long numbers to scientific notation. 4. Save the file as **CSV UTF-8 (Comma delimited)**. ## 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. If you upload another CSV file before you start processing, the new file replaces the uploaded file. 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. ## 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. Values that do not match the type in the saved schema. 4. String values longer than schema length. The type in the upload response is a guess from the values in the CSV file. Processing checks each value against the type in the saved schema. A `string` column in the schema accepts any value up to its length. A type shown for a `string` column, for example `int` for numeric asset tags, does not stop processing. For other types, a value that does not match the schema type stops processing. 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`. - If processing cannot start, the response explains whether a run is already in progress, no schema exists yet, or the uploaded CSV file is missing. - If the endpoint reports that the file is already being processed, do not start another run. Use the ingestion ID from the error message to monitor the existing run. ## 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. > [!NOTE] > **NOTE**: The `RPT_EnrichedDevices` and `RPT_EnrichedUsers` report views are available only after the first ingest run for that table type completes successfully. Until then, dashboards, groups, and queries that use these views can show errors. Before you use the views, make sure that the run status shows a successful run. ## Step 7: 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. The filters are empty by default, so the history shows all runs. To get the next page of results, use `pageNumber`. The default is 1. Expected result: - You can confirm start time and end time of each run. ## Step 8: 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. Filter by `startDate` and `endDate`. 2. Filter by `runBy` for operator-specific auditing. 3. Filter by `actionType`. The filters are empty by default, so the audit shows all records. To get the next page of results, use `pageNumber`. The default is 1. Expected result: - You can see who ran ingest actions, from which IP address, and when. ## Remove Uploaded or Ingested Data If you need to reset the staged file or clear current ingested data, use the delete endpoint for the relevant table type. > [!CAUTION] > **WARNING**: The delete endpoint removes the uploaded file, the staged data, and the current ingested data for that table type. The schema stays. The call fails while an ingest run for that table type is in progress. Use one of these endpoints (see [Delete ingest data](/api/apidocs/delete-ingest-data)): - `DELETE /ingestapi/tabletype/devices` - `DELETE /ingestapi/tabletype/users` Expected result: - The uploaded file and the ingested data for the selected table type are removed. The schema stays. ## 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. | | No error message. The upload response lists the same column name under both `added` and `deleted`. The name under `added` has spaces, for example `' PurchasePrice '`. | The CSV header has spaces before or after the column name. | Remove the spaces from the header name in the CSV file and upload the file again. See [Prepare the CSV File](/documentation/docs/ingest-api-user-guide#prepare-the-csv-file). | ### Process Errors | Error Message | Reason | How to Fix | | --- | --- | --- | | The uploaded file could not be found. Please upload the file before processing. | 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. | | There is currently no schema defined, please call the schema generation endpoint. | The process endpoint was called before a schema was created for the selected table type. | 1. Submit the schema first by using the schema endpoint for the same table type. 2. Upload the CSV file if you have not already staged it. 3. Call the process endpoint again after the schema and staged file are in place. | | The file is already being processed. Please wait for it to return. The current ingestion id is '{ingestId}'. | A process run for the same table type is already starting or running. | 1. Do not call the process endpoint again for the same table type while that run is active. 2. Use the returned ingestion ID with `GET /ingestapi/status/{ingestId}` to monitor the existing run. 3. Start a new process request only after the current run reaches a final state. | | 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. Common causes: - In a `double` column, a thousands separator, a missing decimal part, a currency symbol, or spaces from an Excel number format. - An empty cell in an `int`, `double`, `datetime`, `guid`, or `boolean` column. - A date that is not in ISO 8601 format. See [Prepare the CSV File](/documentation/docs/ingest-api-user-guide#prepare-the-csv-file). | --- ### FAQ #### What is Data Ingest used for? Data Ingest is used to supplement SysTrack data with customer-provided user and device metadata, within tenant sizing and CSV import limits. #### Is Data Ingest available at no additional cost? Yes. Data Ingest is available at no additional cost if you have the required API access. #### Do you need special permissions to use Data Ingest? A valid API key is required to access and use Data Ingest. Once configured, imports and updates can be performed through the supported APIs. #### Which file formats are supported? Only CSV files are supported. #### What limitations apply to Data Ingest? For the limits, see [Data Ingest Limitations](/documentation/docs/ingest-api-user-guide#ingress-limitations). User and device imports are managed as separate CSV files and stored in separate report views. #### Can imported data be updated after upload? Yes. Imported data can be updated through the API as often as needed. #### What happens when a new CSV file is uploaded? Uploading a new CSV file allows you to update the existing imported data. The ingestion process converts the uploaded CSV file into a corresponding report view. If you upload a new CSV file before processing the previous staged file, the new upload replaces the earlier staged file. After data has been ingested, you can delete previously imported data or upload a new CSV file to replace or update the existing imported dataset. #### Does a new CSV file replace previously imported data? The imported dataset can be refreshed by uploading a new CSV file. The newly uploaded file becomes the source for the corresponding imported report view. #### How is imported data stored? - User imports are stored in a dedicated report view. - Device imports are stored in a separate report view. - Each import is maintained independently and can be managed separately.