The Geotab Data Intake Gateway (DIG) API accepts telematics records from third-party devices directly into the MyGeotab platform. It uses JWT bearer token authentication and supports 12 distinct record types including GPS, acceleration, fault codes, driver changes, and VIN data.
openapi: 3.0.1
info:
title: Data Intake Gateway
version: v3.4.2
description: >-
Please see the
<a href='https://docs.google.com/document/d/15uNuPqwFcPLe6vKs_JgY5nPTy2isQ3WYUu4oyQ3cEfQ'>Data Intake Gateway Guide</a>
to learn more; there are important workflow and implementation details to consider for all endpoints.
paths:
/authentication/authenticate:
post:
tags:
- Authentication
summary: "Authenticate to the API"
description: "Authenticate against the API with credentials"
operationId: "authenticate"
requestBody:
description: "The username and password to authenticate with"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticateModel'
responses:
"200":
description: "Authentication successful"
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationSuccessResponse'
examples:
example:
$ref: '#/components/examples/AuthenticatedResponseExample'
"400":
description: "Request was missing all or part of the required parameters"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"401":
description: "Credentials provided could not be used to authenticate successfully"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"429":
description: "Too many requests; rate limit quota exceeded; see public documentation"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"503":
description: "Service is unavailable"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
/authentication/refresh-token:
post:
security:
- bearerAuth: []
tags:
- Authentication
summary: "Refresh tokens using refresh and bearer tokens"
description: ""
operationId: "refresh-token"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRefreshModel'
responses:
"200":
description: "Token refresh was successful"
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationSuccessResponse'
examples:
example:
$ref: '#/components/examples/AuthenticatedResponseExample'
"400":
description: "Request was missing all or part of the required parameters"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"401":
description: "Tokens provided could not be used to refresh successfully"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"403":
description: "Token was already refreshed and/or cannot be found"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"429":
description: "Too many requests; rate limit quota exceeded; see public documentation"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"503":
description: "Service is unavailable"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
/authentication/revoke-token:
post:
security:
- bearerAuth: []
tags:
- Authentication
summary: "Revoke current tokens"
description: ""
operationId: "revoke-token"
requestBody:
description: "Revoke the current set of tokens so they are no longer valid"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRefreshModel'
responses:
"202":
description: "Token revocation request was accepted"
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeTokenSuccessResponse'
example:
Error: []
Data: "Refresh token revoked and user bearer token enqueued as blocked."
"400":
description: "Request was missing all or part of the required parameters"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"401":
description: "Tokens provided could not be used to revoke successfully"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"403":
description: "Token has already been revoked and/or cannot be found"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"429":
description: "Too many requests; rate limit quota exceeded; see public documentation"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"503":
description: "Service is unavailable"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
/invalidrecords:
get:
security:
- bearerAuth: []
tags:
- Invalid Records
parameters:
- name: nextResultKey
in: query
schema:
type: integer
- name: numberOfResults
in: query
schema:
type: integer
minimum: 1
maximum: 50000
default: 1000
responses:
"200":
description: "Fetch batch of invalid records"
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRecordsResponse'
example:
Error: []
Data:
NextResultKey: 1002154023
CurrentResultKey: 1002152089
TotalNumberOfInvalidRecords: 16545
CurrentNumberOfInvalidRecords: 200
InvalidRecords:
- BaseRecord:
SerialNo: "2396122106100"
Type: "GenericStatusRecord"
DateTime: "2021-02-10T01:00:00.500Z"
Code: 7
Value: 0
Cause: "Reason message was rejected"
TimeStamp: "2021-02-10T02:00:00Z"
UserId: "[email protected]"
- BaseRecord:
SerialNo: "6605174986852"
Type: "StatusRecord"
DateTime: "2021-02-10T01:00:00.010Z"
Code: 12
Value: 5
Cause: "Reason message was rejected"
TimeStamp: "2021-02-10T02:01:00Z"
UserId: "[email protected]"
"400":
description: "Request was missing all or part of the required parameters"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"401":
description: "Tokens provided could not be used to authenticate successfully"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"503":
description: "Service is unavailable"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
/records:
post:
security:
- bearerAuth: []
tags:
- Records
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
anyOf:
- $ref: '#/components/schemas/AccelerationRecord'
- $ref: '#/components/schemas/BinaryRecord'
- $ref: '#/components/schemas/BluetoothRecord'
- $ref: '#/components/schemas/DriverChangeRecord'
- $ref: '#/components/schemas/GenericFaultRecord'
- $ref: '#/components/schemas/GenericStatusRecord'
- $ref: '#/components/schemas/GpsRecord'
- $ref: '#/components/schemas/J1708FaultRecord'
- $ref: '#/components/schemas/J1939FaultRecord'
- $ref: '#/components/schemas/ObdiiFaultRecord'
- $ref: '#/components/schemas/StatusRecord'
- $ref: '#/components/schemas/VinRecord'
maxItems: 5000
example:
- SerialNo: "2396122106100"
Type: "VinRecord"
DateTime: "2021-02-10T01:00:00Z"
VehicleIdentificationNumber: "1NZI3SA5WPAJE2YR3"
- SerialNo: "8378832278466"
Type: "StatusRecord"
DateTime: "2021-02-10T01:00:01.500Z"
Code: 12
Value: 5
responses:
"202":
description: "Records accepted for processing"
content:
application/json:
schema:
$ref: '#/components/schemas/RecordsResponse'
example:
Error: []
Data: "feeac962-4496-4458-a489-e2d9b4ea12ec"
"400":
description: "Request was missing all or part of the required parameters"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"413":
description: "Request payload was too large (size in bytes or too many records)"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
"503":
description: "Service is unavailable"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
example:
$ref: '#/components/examples/GenericErrorResponseExample'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
AuthenticationStatus:
type: object
properties:
Authenticated:
type: boolean
UserId:
type: string
BearerToken:
$ref: "#/components/schemas/Token"
RefreshToken:
$ref: "#/components/schemas/Token"
AuthenticationSuccessResponse:
type: object
properties:
Error:
$ref: "#/components/schemas/ResponseErrors"
Data:
$ref: '#/components/schemas/AuthenticationStatus'
RevokeTokenSuccessResponse:
type: object
properties:
Error:
$ref: "#/components/schemas/ResponseErrors"
Data:
type: string
InvalidRecordsResponse:
type: object
properties:
Error:
$ref: "#/components/schemas/ResponseErrors"
Data:
$ref: '#/components/schemas/InvalidRecordSet'
RecordsResponse:
type: object
properties:
Error:
$ref: "#/components/schemas/ResponseErrors"
Data:
type: string
format: uuid
ResponseErrors:
type: array
items:
type: string
ErrorResponse:
type: object
properties:
Error:
$ref: "#/components/schemas/ResponseErrors"
Data:
type: string
AuthenticateModel:
required:
- Password
- Username
type: object
properties:
Username:
type: string
Password:
type: string
additionalProperties: false
TokenRefreshModel:
required:
- BearerToken
- RefreshToken
type: object
properties:
BearerToken:
type: string
RefreshToken:
type: string
additionalProperties: false
Token:
type: object
properties:
TokenString:
type: string
Expires:
type: string
format: date-time
Created:
type: string
format: date-time
AccelerationRecord:
description: A data record class that contains acceleration data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
X:
type: integer
format: int16
description: The X-axis acceleration (forward or backward) in milli-g (1000 milli-g = 1 G Gravitational force).
Y:
type: integer
format: int16
description: The Y-axis acceleration (right or left) in milli-g (1000 milli-g = 1 G Gravitational force).
Z:
type: integer
format: int16
description: The Z-axis acceleration (up or down) in milli-g (1000 milli-g = 1 G Gravitational force).
BaseRecord:
type: object
description: An abstract data record class (all fields are required).
properties:
Type:
type: string
description: Indicates the type of record.
DateTime:
type: string
format: date-time
description: Date and time of the record in the ISO 8601 RFC3339, UTC zulu format yyyy-MM-ddTHH:mm:ss.ffffffZ is recommended. See DIG guide *Working with Dates* section for more details.
SerialNo:
type: string
description: Device serial number.
additionalProperties: false
BinaryRecord:
description: A data record class that supports arbitrary binary data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
Data:
type: string
format: byte
maxLength: 32745
description: Arbitrary binary payload, Base64 encoded. Maximum size of 32745 bytes.
DriverChangeRecord:
description: A data record class that contains driver change data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
KeyType:
type: integer
minimum: 0
maximum: 255
description: The key type.
DriverId:
type: string
format: byte
maxLength: 239
description: Driver ID, Base64 encoded.
GenericFaultRecord:
description: A data record class that contains generic fault data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
Code:
type: integer
minimum: 128
maximum: 1999
description: Diagnostic ID code (of type fault). (Range >=128, <=1999)
FaultStateActive:
type: boolean
description: A value indicating whether the fault state is active.
GenericStatusRecord:
description: A data record class that supports generalised data from a telematics device. Supports a specific set of codes.
allOf:
- $ref: '#/components/schemas/StatusRecord'
- type: object
GpsRecord:
description: A data record class that contains latitudinal and longitudinal location data and speed (km/h). Other ancillary flags are also supported.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
IsAuxiliary1On:
type: boolean
description: A value indicating whether the auxiliary is on.
IsAuxiliary2On:
type: boolean
description: A value indicating whether the auxiliary is on.
IsAuxiliary3On:
type: boolean
description: A value indicating whether the auxiliary is on.
IsAuxiliary4On:
type: boolean
description: A value indicating whether the auxiliary is on.
IsAuxiliary5On:
type: boolean
description: A value indicating whether the auxiliary is on.
IsAuxiliary6On:
type: boolean
description: A value indicating whether the auxiliary is on.
IsAuxiliary7On:
type: boolean
description: A value indicating whether the auxiliary is on.
IsAuxiliary8On:
type: boolean
description: A value indicating whether the auxiliary is on.
IsGpsValid:
type: boolean
description: A value indicating whether the GPS is valid.
IsIgnitionOn:
type: boolean
description: A value indicating whether the ignition is on.
Latitude:
type: number
format: float (4-bytes signed)
description: The latitude.
Longitude:
type: number
format: float (4-bytes signed)
description: The longitude.
Speed:
type: number
format: float (4-bytes signed)
description: The speed in kilometers per hour.
J1708FaultRecord:
description: A data record class that contains J1708 fault data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
MessageId:
type: integer
format: uint8
minimum: 0
maximum: 255
description: Identifier for the component sending the message.
ParameterId:
type: integer
format: uint16
minimum: 0
maximum: 511
nullable: true
description: Parameter identification without a related Subsystem ID.
SubsystemId:
type: integer
format: uint16
minimum: 0
maximum: 511
nullable: true
description: Identifies a section of the control system without a related Parameter ID.
FailureModeIdentifier:
type: integer
format: uint8
minimum: 0
maximum: 15
description: Failure mode identifier associated with a diagnostic trouble code.
OccurrenceCount:
type: integer
format: uint8
minimum: 0
maximum: 255
description: Number of faults.
FaultStateActive:
type: boolean
description: A value indicating whether the fault state is active.
J1939FaultRecord:
description: A data record class that contains J1939 fault data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
SuspectParameterNumber:
type: integer
description: Unique number assigned to every suspect parameter number (SPN).
FailureModeIdentifier:
type: integer
format: uint8
minimum: 0
maximum: 255
description: Failure mode identifier associated with a diagnostic trouble code.
OccurrenceCount:
type: integer
format: uint8
minimum: 0
maximum: 255
description: Number of times this fault has been recorded.
SourceAddress:
type: integer
format: uint8
minimum: 0
maximum: 255
description: The address of a controller application.
MalfunctionLamp:
type: boolean
description: Lamp to indicate when there is an emission related trouble code active (MIL).
RedStopLamp:
type: boolean
description: Lamp to indicate a problem that is severe enough to warrant stopping the vehicle (RSL).
AmberWarningLamp:
type: boolean
description: Lamp to indicate a problem with the vehicle system but the vehicle does not need to be stopped immediately (AWL).
ProtectWarningLamp:
type: boolean
description: Lamp to indicate a problem with a vehicle system that is most likely not electronic subsystem related (PL).
FaultStateActive:
type: boolean
description: A value indicating whether the fault state is active.
ObdiiFaultRecord:
description: A data record class that contains OBD-II fault data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
Code:
type: string
description: Trouble code.
FaultStateActive:
type: boolean
description: A value indicating whether the fault state is active.
StatusRecord:
description: A data record class that contains status data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
Code:
type: integer
description: The diagnostic code (of type status). (Range <=127, >=2000)
Value:
type: integer
description: The value of the diagnostic. (valid values depend on diagnostic code)
VinRecord:
description: A data record class that contains vehicle identification data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
VehicleIdentificationNumber:
type: string
description: Vehicle Identification Number.
BluetoothRecord:
description: A data record class that contains bluetooth data.
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
properties:
Address:
type: string
description: The string MAC address of the Bluetooth sensor (e.g. FF:FF:FF:00:AA:9B).
Data:
type: number
format: float (4-bytes signed)
description: The floating point value of the data. The meaning and unit of measure is dependent on data type.
DataType:
type: integer
minimum: 0
maximum: 255
description: Identifies the type of bluetooth data contained in the data field.
InvalidRecordSet:
type: object
description: A data record class that contains invalid record data.
properties:
NextResultKey:
type: integer
format: int64
description: Cursor pointing to the next record after the current set.
CurrentResultKey:
type: integer
format: int64
description: Cursor pointing to the start of the current results.
TotalNumberOfInvalidRecords:
type: integer
format: int64
description: Total number of invalid records for the current user.
CurrentNumberOfInvalidRecords:
type: integer
format: int64
description: Number of invalid records in the current set.
InvalidRecords:
type: array
items:
$ref: '#/components/schemas/InvalidRecord'
description: Array of InvalidRecords.
additionalProperties: false
InvalidRecord:
type: object
description: A data record class that contains data which is not accepted by the API.
properties:
BaseRecord:
$ref: '#/components/schemas/BaseRecord'
Cause:
type: string
nullable: true
description: Reason the record was rejected.
TimeStamp:
type: string
format: date-time
description: Date and time the record was marked invalid in the ISO 8601 RFC3339 format.
UserId:
type: string
nullable: true
description: ID of the user who owns this record.
additionalProperties: false
examples:
GenericErrorResponseExample:
summary: "Sample of a generic error response"
description: "Note that Error and Data are mutually exclusive. In error condition Error is populated with one or more errors; Data will be empty."
value:
Error: [ "Error message here" ]
Data: {}
AuthenticatedResponseExample:
summary: "Sample of a successful authenticated response."
value:
Error: [ ]
Data:
Authenticated: true
UserId: "[email protected]"
BearerToken:
TokenString: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImRpZ0BnZW8udGFiIiwibmJmIjoxNjEyODQ2ODEwLCJleHAiOjE2MTMxMDYwMTAsImlhdCI6MTYxMjg0NjgxMH0.pXS0ehnRCwZSzGNLSYGlh_oJCnXieFZBu7HBV6y0b5Q"
Created: "2019-07-26T00:00:10"
Expires: "2019-07-26T00:00:10"
RefreshToken:
TokenString: "m=+tunBX6uDBY/Rk9OUQeZdCdmaQgzPHdGvVH2B3cuCXwjADdqvD44vyCr0Z"
Created: "2019-07-26T00:00:10"
Expires: "2019-07-26T00:00:10"