{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/terminal-telematics/json-schema/terminal-telematics-full-connection-schema.json",
  "title": "Full Connection",
  "description": "The connection your application has with your customer's TSP.",
  "x-generated": "2026-11-15",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/terminal.openapi.json#/components/schemas/FullConnection",
  "allOf": [
    {
      "title": "Connection Base",
      "type": "object",
      "description": "Fields shared by all connection records.",
      "properties": {
        "id": {
          "$ref": "#/$defs/ConnectionId"
        },
        "company": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Optional name of the connection."
            },
            "dotNumbers": {
              "type": "array",
              "description": "Optional DOT numbers associated with this connection.",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "account": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the account according to the provider."
            },
            "dotNumbers": {
              "type": "array",
              "description": "DOT numbers associated with the account according to the provider.",
              "items": {
                "type": "string"
              }
            },
            "user": {
              "type": "object",
              "description": "The user of the provider account that created the connection.",
              "properties": {
                "sourceId": {
                  "description": "The ID of the user in the provider's system.",
                  "type": "string"
                },
                "firstName": {
                  "type": "string"
                },
                "lastName": {
                  "type": "string"
                },
                "email": {
                  "type": "string"
                }
              }
            }
          }
        },
        "provider": {
          "type": "object",
          "required": [
            "code",
            "name"
          ],
          "properties": {
            "code": {
              "$ref": "#/$defs/ProviderCode"
            },
            "name": {
              "type": "string",
              "description": "The name of the Telematics Service Provider."
            }
          }
        },
        "externalId": {
          "type": "string",
          "description": "An optional ID from your system that can be used to reference connections."
        },
        "sourceId": {
          "$ref": "#/$defs/SourceId",
          "description": "The ID used in the source system to represent the account this connection has or had access to.\n\nThis may be an `organizationId` or `accountId`.\n\nNote: not all systems expose this information, in which case it may be undefined."
        },
        "syncMode": {
          "$ref": "#/$defs/SyncMode"
        },
        "token": {
          "type": "string",
          "pattern": "^con_tkn_\\S+$",
          "description": "This token is used when interacting with a connections' data."
        },
        "tags": {
          "type": "array",
          "description": "An optional list of tags from your system that can be used to reference connections.",
          "items": {
            "type": "string"
          }
        },
        "createdAt": {
          "$ref": "#/$defs/ISODateTime"
        },
        "updatedAt": {
          "$ref": "#/$defs/ISODateTime"
        }
      },
      "required": [
        "id",
        "company",
        "account",
        "provider",
        "syncMode",
        "token",
        "createdAt",
        "updatedAt"
      ]
    },
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "connected",
            "disconnected",
            "archived",
            "pending_deletion"
          ],
          "description": "The current status of the connection."
        },
        "options": {
          "$ref": "#/$defs/ProviderOptions"
        },
        "filters": {
          "$ref": "#/$defs/ConnectionFilters"
        },
        "linkUrl": {
          "type": "string",
          "format": "uri",
          "description": "The URL to send your user to in order to have them re-authenticate the connection."
        }
      },
      "required": [
        "status",
        "options",
        "linkUrl"
      ]
    }
  ],
  "$defs": {
    "ConnectionFilters": {
      "type": "object",
      "properties": {
        "vehicles": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "active",
                "inactive"
              ],
              "description": "Filter connection to only include data related to vehicles with a specified status"
            },
            "excludeIds": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/VehicleId"
              },
              "description": "IDs of vehicles to exclude from data ingestion"
            },
            "includeIds": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/VehicleId"
              },
              "description": "IDs of vehicles to include in data ingestion (takes priority over other filters)"
            }
          }
        },
        "drivers": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "active",
                "inactive"
              ],
              "description": "Filter connection to only include data related to drivers with a specified status"
            },
            "excludeIds": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/DriverId"
              },
              "description": "IDs of drivers to exclude from data ingestion"
            },
            "includeIds": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/DriverId"
              },
              "description": "IDs of drivers to include in data ingestion (takes priority over other filters)"
            }
          }
        }
      },
      "description": "Filters applied to connection data. Across all lists, the maximum is about 8,000 IDs. A larger update is rejected with 422 and is not saved. If one list contains most vehicles or drivers, use the opposite list: excludeIds for the ones to skip, or includeIds for the ones to keep."
    },
    "ConnectionId": {
      "title": "ConnectionId",
      "type": "string",
      "format": "ulid"
    },
    "DriverId": {
      "title": "DriverId",
      "description": "Unique identifier for the driver in Terminal.",
      "type": "string",
      "format": "ulid",
      "pattern": "^drv_[0-9A-HJKMNP-TV-Z]{26}$"
    },
    "ISODateTime": {
      "title": "ISODateTime",
      "type": "string",
      "format": "date-time",
      "description": "[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date"
    },
    "ProviderCode": {
      "type": "string",
      "description": "Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under [provider details](/providers)."
    },
    "ProviderOptions": {
      "type": "object",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "ingestHistoryFromSourceSystem": {
              "default": true,
              "description": "By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.",
              "type": "boolean"
            }
          },
          "required": [],
          "title": "Omnitracs Options"
        },
        {
          "type": "object",
          "properties": {
            "ingestHistoryFromSourceSystem": {
              "default": true,
              "description": "By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.",
              "type": "boolean"
            }
          },
          "required": [],
          "title": "Omnitracs ES Options"
        },
        {
          "type": "object",
          "properties": {
            "ingestHistoryFromSourceSystem": {
              "default": true,
              "description": "By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.",
              "type": "boolean"
            }
          },
          "required": [],
          "title": "Omnitracs XRS Options"
        }
      ]
    },
    "SourceId": {
      "title": "SourceId",
      "type": "string",
      "description": "The ID used to represent the entity in the source system."
    },
    "SyncMode": {
      "title": "SyncMode",
      "type": "string",
      "enum": [
        "automatic",
        "manual"
      ],
      "description": "Enum values:\n- `automatic`: Terminal will keep this connections data up to date\n- `manual`: Terminal will only sync data upon request",
      "default": "automatic"
    },
    "VehicleId": {
      "title": "VehicleId",
      "description": "Unique identifier for the vehicle in Terminal.",
      "type": "string",
      "format": "ulid",
      "pattern": "^vcl_[0-9A-HJKMNP-TV-Z]{26}$"
    }
  }
}