After a connection is created, Terminal syncs and normalizes data incrementally to ensure it is always up-to-date. Use the /connections/current
or /syncs
endpoints to track when data is synced from the source system to Terminal before querying for data.
Terminal connections can be configured to sync data automatically or manually:
syncMode
to automatic
.syncMode
to manual
.A sync can be requested at any time for a connection by calling the POST /syncs
endpoint. This endpoint will return an id
that can be used to check the status of the sync
Terminal provides 2 types of data: dynamic and event.
Syncing Dynamic Data
Dynamic data is data that may change. Examples include vehicles, drivers and HOS logs.
Use the modifiedAfter
timestamp filter to only ingest data that has changed since the start time of when you last synced. This filter is important to ensure you only pull data that has been modified (or created) since the last time you synced.
Continue to pull data until the response does not include a next
cursor.
Example
If you last started syncing at 2022-01-01T00:00:00.000Z
you should make the following request
Note: Ensure you store the start time of the last sync as data can change while you are syncing. This will ensure you never miss a change.
Syncing Event Data
Event data refers to records with a timestamp that are typically immutable, such as vehicle locations and stats.
For most event data endpoints, a modifiedAfter
filter is not available.
Instead, these endpoints provide startAt
and endAt
timestamp filters that allow you to request data for a specific time window. Records are returned in ascending order by timestamp.
startAt
and endAt
parameters to define the desired time range.Note: Ensure you store the next cursor of the last request in order resume syncing from where you left off.
modifiedAfter
filter instead of startAt
and endAt
for endpoints where supported (such as safety events), as this will capture both new and updated records.Setup a scheduled job on your backend to sync data periodically for each connection.
Some of our endpoints (ex: historical vehicle locations) require that you query them by vehicle. We recommend syncing vehicles first and then scheduling jobs to pull data for each vehicle.
Currently our system schedules syncs every 2 hours so please note that data will only be updated upon completion of syncing in our system.
For maintaing the most up to date information, we recommend initiating a sync after receiving a sync.complete
webhook (learn more). Alternativley, you can use the /syncs
or /connections/current
endpoints to know when data has been synced from the source system to Terminal.
If you need data more frequently - please reach out to our team and we’d be happy to help support your use case.