Introduction

Welcome to the Ctrack Maxx API. Here's a quick introduction to help you get started.

• The External API has been developed using Windows Communication Foundation (WCF) and allows communication via SOAP 1.2 (XML) or JSON.
• All API functions require a valid security token. A token can be obtained by calling the AcquireSecurityToken function in the API.
• Security tokens expire if they are not used for 10 minutes. This is important to developers calling the API irregularly rather than continuously as part of an automatic process. In this case, consider:
  • Calling ValidateToken and checking the response before making further requests - this also resets the token's idle timer.
  • Designing your consuming application to handle SessionExpiredFault.

Formats & Measurements

• Distances are in meters (m).
• Speeds are in kilometers per hour (kph).
• Durations are in seconds (s).
• Latitudes and longitudes are in decimal format, to 5 decimal places.
• DateTime values are expressed in YYYY-MM-DD HH:MM:SS format.
• All DateTimes (both as request parameters and response values) are in the UTC time zone.

Limits

• Each API call is limited to a certain number of calls per hour, per user account.
• The limit is calculated based on the last 60 minutes and does not reset hourly.
• Where a DateTime range is required, a maximum of 48 hours is supported unless otherwise stated.
• When supplying lists of driver or vehicle identifiers, there is no predefined limit on the number that may be requested in a single call unless otherwise stated.
  However, to improve performance you may wish to consider splitting requests for more than 2000 items into multiple smaller ones.

TLS 1.2 Support

With the upgrade to .Net Framework 4.7.2 comes additional support for TLS v1.2. TLS v1.1 and 1.0 (backwards compatible with SSLv3.0) are also supported. This is handled transparently by the .Net Framework so that the most secure supported communication mode will automatically be used. Keep in mind that at least eight layers of hardware, software and configuration must support any given communication mode in order for it to be used:

1. Physical infrastructure, for example any packet inspection or network hardware, at either the server or client end.
2. Server Operating System.
3. Server Web Server.
4. Server .Net Framework runtime.
5. Server application (in this case the External API.)
6. Client operating system.
7. Client application.
8. Any supporting components or libraries used for web communication.

With the update to 4.7.2. from the previous 4.5.1 the following cipher suites are explicitly not supported for security reasons:

• SSL_RSA_WITH_RC4_128_SHA
• SSL_RSA_WITH_RC4_128_MD5

All other ciphersuites should work given proper support in other dependencies.

Quick Start

• The service definition (WSDL) files for WCF SOAP requests are linked below and can be imported via SoapUI.
• Brief guides are available demonstrating use of the SOAP and REST API's.

• Membership Service - Authentication, Business Structure (Service / WSDL)
• Drivers Service - Driver Lists/Details, Vehicle Assignment (Service / WSDL)
• TrackingUnit Service - Vehicles, Vehicle Trips, Status Events (Service / WSDL)

• Given a WCF service endpoint ~/Membership.svc/AcquireSecurityToken, the JSON equivalent may be found at ~/Membership.svc/Rest/AcquireSecurityTokenRest.

  Parameters for JSON requests are passed as part of the URL. You may find Postman useful as a testing tool.

API Call List

The standard Ctrack API package contains all the calls you need to get started and build a feature rich application. Why not try out building a client and explore the possibilities?

• AcquireSecurityToken
• ReleaseSecurityToken
• ValidateToken
• GetAllCostCenterDetailsbyBusinessGroupId
• GetAllCostCenterDetailsbyUserID
• GetBusinessGroups
• GetUserDetails
• GetDriverMappingsByKeys
• GetAllDriversByBusinessGroupID
• GetDriverDetailsByDriverID
• GetDriverCustomFieldsByDriverID
• GetDriverIDSwipesByVehicleIDDriverIDAndDateRange
• GetDriverStateByIds
• GetFullTripSummary
• GetBusinessPrivateFullTripSummary
• GetLatestVehicleStatesById
• GetListStatusEventsByVehicleIDAndDateRange
• GetTripPositionById
• GetTripSummaryById
• GetTripSummaryExtended
• GetAlarmCountByDateRange
• GetAlarmDetailsByDateRange
• GetVehicleMappingsBySerialNumbers
• GetVehicleMappingsBySerialNumbersExtended
• GetVehicleMappingsByVehicleRegistrations
• GetVehicleMappingsByVehicleRegistrationsExtended
• GetVehicleMappingsByVinNumbers
• GetVehicleCurrentRunningDataByIds
• GetVehicleDetailsByIds
• GetVehicleDriverCurrentAssignment
• GetVehicleOdometerByIdAndDatetime

Additional API Calls

The standard set can be expanded with the calls listed within this website marked with an Advanced Tag. If access to additional functionality is required, please contact your account manager.

This API documentation also contains details of Bespoke calls (marked with a Bespoke tag) that are not made available as part of the standard API package. Access to these calls is restricted to users with particular integration requirements.

For futher information on Bespoke API calls, contact your account manager.