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.

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:

You define the target schema for users or devices and send it to SysTrack.
You send a CSV file to SysTrack that matches the defined schema.
SysTrack analyzes the uploaded file and reports any differences between the CSV and the current schema.
You review the differences and decide how to proceed. This step ensures that you validate schema changes and data updates before ingestion.
You explicitly call the process endpoint to start ingestion.
SysTrack ingests the data and makes it available through the RPT_EnrichedDevices and RPT_EnrichedUsers report views.
SysTrack associates each ingested device with its WGUID, optimized to run during off-hours to minimize impact.
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.
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.
- 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.

IngestAPI_Devices_Template

262 Byte

IngestAPI_Users_Template

244 Byte

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:

{
   "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:

{
   "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

Create a JSON file for your schema in a text editor.
Add one schema column entry for each CSV header.
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.
For each string column, set length to a safe maximum expected value.

Add Device Key Mapping Explicitly (Devices Only)

Choose the matching strategy:
- SystemName if your CSV has stable system name values.
- Serial if your CSV has stable serial values.
Set keyColumn.name to that exact CSV header.
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):

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):

POST /ingestapi/tabletype/devices/csv
POST /ingestapi/tabletype/users/csv

What to do:

Send the CSV body with the text/csv content type.
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:

Header order does not have to match the schema order.
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:

added columns.
deleted columns.
Type mismatches.
String values longer than schema length.

What to do:

If the upload response shows no added or deleted columns and all isChanged values are false, proceed to the next step.
If the only change is shorter string values within the schema limit, proceed to the next step.
If the CSV is incorrect, fix the file and upload it again.
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):

POST /ingestapi/tabletype/devices/process
POST /ingestapi/tabletype/users/process

What to do:

Send the process request.
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)

What to do:

Poll the endpoint until the status reaches a final state.
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):

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)

Recommended uses:

Review recent runs.
Filter by category to focus on users or devices.
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)
GET /auditapi/ingest/actions/{actionType} (see Get ingest action audit records by type)

Recommended uses:

Review all ingest-related actions in a time range.
Filter by runBy for operator-specific auditing.
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.

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.	Upload the CSV file again. Retry processing. Or Check the process status. 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.	Remove the extra column from the CSV, or update the schema so that it includes that column. 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.	Correct the reported row so that it has the expected number of values. Check for extra delimiters, missing delimiters, or broken quoting. 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.	Correct the CSV value so it matches the schema type. If the schema type is wrong, update the schema first, then upload and process again.

Documentation Index

Importing Data with the Ingest API

What is Data Ingest?

How Ingest Works

Data Ingest Limitations

Prerequisites

Step 1: Build the Schema

Start From the Matching Template

Draft the Schema from Your CSV Headers

Add Device Key Mapping Explicitly (Devices Only)

Step 2: Submit the Schema

Step 3: Upload the CSV File

Step 4: Decide Whether to Adjust the Schema

Step 5: Start Processing

Step 6: Monitor the Run Status

Step 7: Remove Uploaded or Current Ingest Data When Needed

Step 8: Review Ingest History

Step 9: Review Audit Records

Ingest API Troubleshooting

Schema Errors

Upload Errors

Process Errors