developer guide for account apifiles.delorme.com/support/inreachwebdocs/account api.pdf3 account api...
TRANSCRIPT
Developer Guide for Account API
V 20 Updated 12182018
2 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Contents Revision History 8
Account API 10
Updates to this Document 10
Online (Live) Documentation 10
REpresentational State Transfer (REST) Web Services 11
JavaScript Object Notation 11
Costs 11
Authentication 11
Dates 11
HTTPS 11
Web Service Objects 11
User Object 12
User Example 13
User Collection 14
Device Object 15
Device Example 16
Device Collection 16
Call Data Record Object 17
Devices 17
Device 17
MessageDetails 17
MessageInstance 17
Settings 20
SyncURL 21
Work Flow 21
Creating a User 21
Request 21
Assigning the Device to a User 21
Activating a Device 22
Setting a Device Name 22
3 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Password Synchronization 22
Users 22
Usersuserid (GET) Get User by Identifier 23
Request Object 23
Response Object 23
Example 23
Response Content 23
Users (GET) Get All Users 23
Request Object 23
Response Object 23
Example 23
Response Content 24
Usersreferenceid=referenceid (GET) Get All Users with Reference ID 24
Request Object 24
Response Object 24
Example 24
Response Content 24
Usersusername=username (GET) Get All Users with User Name 24
Request Object 24
Response Object 24
Example 25
Response Content 25
Usersimei=imei (GET) Gets User Assigned to Device 25
Request Object 25
Response Object 25
Example 25
Response Content 25
Users (POST) Create User 25
Request Object 25
Response Object 25
Example 26
Response Content 26
Users (PUT) Update User Information 26
4 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Request Object 26
Response Object 26
Example 26
Response Content 26
Usersidsuspend=suspend (PUT) Suspend User 27
Response Object 27
Example 27
Response Content 27
Userspassword=password (GET) Validates Password Meets 27
Request Object 28
Response Object 28
Example 28
Response Content 28
Sub Users 29
SubUsersparentUserId=parentUserId (GET) Get All Sub Users 29
Request Object 29
Response Object 29
Example 29
Response Content 29
SubUsersparentUserId=parentUserId (POST) Create a new Sub User 29
Request Object 30
Example 30
Response Object 30
SubUsersparentUserId=parentUserId (PUT) Update a Sub User 30
Request Object 30
Example 30
Response Object 30
SubUsersuserIdparentUserId=parentUserId (DELETE) Delete a Sub User 31
Request Object 31
Example 31
Response Object 31
SubUsersuserIdparentUserId=parentUserIdampsuspend=suspend (PUT) Suspend a Sub User 31
5 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Request Object 32
Example 32
Response Object 32
Devices 32
Devicesimei (GET) Get Device by IMEI 32
Request Object 32
Response Object 32
Example 32
Devices (GET) Get All Devices 32
Request Object 33
Response Object 33
Example 33
Response Content 33
Devicesimeiauthcode=authcode (GET) Validate IMEI and Auth Code 33
Request Object 33
Response Object 33
Example 33
Response Content 34
Devicesimeiuserid=userid (PUT) Assign User to Device 34
Request Object 34
Response Object 34
Example 34
Response Content 34
Devicesimeiplan=planid (PUT) Activate Device with Plan 34
Request Object 35
Response Object 35
Example 35
Response Content 35
Devicesimei (DELETE) Deactivate Device 35
Request Object 35
Response Object 35
Example 36
Response Content 36
6 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
SubUserDevices 36
DevicesSubUsersuserIdparentUserId=parentUserIdampimei=imei (PUT) Assign a device to a sub user 36
DevicesSubUsersuserIdparentUserId=parentUserId (DELETE) Unassigns any device from the sub user 37
Plans 38
Plans (GET) Get All Device Plans 38
Request Object 38
Response Object 38
Example 38
Response Content 39
Time Zones 40
TimeZones (GET) Get All Device Plans 40
Request Object 40
Response Object 40
Example 40
Response Content 41
Call Data Records 42
CallDataRecordsstartdate=startdateampenddate=enddate (GET) Get All Call Data Records 42
Request Object 42
Response Object 42
Example 42
Response Content 43
CallDataRecordsstartdate=startdateampenddate=enddateampimei=imei (GET) Get All Call Data Records 43
Request Object 43
Response Object 43
Example 43
Response Content 44
CallDataRecordsstartdate=startdateampenddate=enddate ampuserid=userid (GET) Get All Call Data Records 44
Request Object 45
Response Object 45
Example 45
7 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Response Content 45
Settings 46
Settings (GET) Get Reseller Settings 46
Request Object 46
Response Object 46
Example 46
Response Content 46
Settings (PUT) Update Reseller Settings 46
Request Object 46
Response Object 46
Example 47
Response Content 47
SyncURL 48
SyncURLIMEI=imei (GET) Get SyncURL for imei 48
URL 48
Request Content 48
Response Content 48
HTTP Status Codes 48
Errors 49
Error Codes 49
JSON Error Object 49
Example Error Result 50
8 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Revision History Date Version Description Author 2012-06-14 001 Initial Draft Version EBS 2012-06-25 002 Updated based on feedback
- Added Reference ID to User - Added Password to User - Added Country Code to User Contacts - Updated User DisplayName description If the
DisplayName value is null the API will default the value to a combination of the users first and last name For example ldquoFirstName LastNamerdquo or ldquoJohn Smithrdquo
- Changed AssignmentStatus and NetworkStatus from String to Number value
- Documented the AssignmentStatus and NetworkStatus enumeration types
- Added pending statuses to NetworkStatus - Fixed Document Links - Added method to Validate Password - Change Date Format to ISO-8601
EBS
2012-06-28 003 Added Reference ID to User GET and PUT requests
EBS
2012-07-09 004 Corrected error in documentation of NetworkStatus Change from String to Number
EBS
2012-07-10 005 - Documented the Users and Devices Collection - Removed user name reference id and IMEI from user GET and PUT requests - Added new methods to query for users by name reference id or IMEI - Changed made URLs plural - Changed User DeviceIMEI to Devices with an array of IMEIs - Small changes to the device IMEI+ auth code and password validation methods
EBS
2012-08-01 006 - Updates URLs - Added Plans service - Updated User Object (UserName Email Alternative Phone Numbers Country Codes) - Updated Device Object (Changed Network Status values) - Updated Plans Object (Changed UnitType to Number) - Changes some URI schemas to match implementation - Added Work Flow
EBS
2012-08-015 007 -Update Product Object (PlanActivationFee PlanDescription PlanExtendedDescription PlanRecurringCharge PlanSwitchFee PlanContractTerm PlanCategory UnitOverageFee) - Removed the Country Code Dialing Codes from
MLL EBS
9 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Contacts and Emergency Contacts - Added method to suspend User Account - Added Time Zones and Call Data Records Services - Removes the AssignmentStatus parameter from Device object
2012-09-05 008 -Update Device Object to include TransferredDate - Added methods for getting and setting Reseller settings
2012-09-12 009 - Fixed name in CDR from MessagesUsed to Messages -Updated Device Object to include RequiresFirmwareUpdate object
MLL
2012-09-24 0010 - Removed LastFirmwareUpdateDate from Device object
EBS
2012-10-18 0011 - Added New Settings for Billing Redirect Password Synchronization Customer Care Error Message
EBS
2013-05-17 100 -Added New SyncURL Service DSA 2013-10-30 101 -Corrected Sandbox URLs JHG 2013-12-18 101 -Added example JSON for CDR methods NDD 2015-1-21 11 Added device name access MDG 2015-2-11 12 Refine Devices controller methods MDG 2015-02-24 13 Added Sub User related methods SubUserDevices
methods added link to live Swagger documentation
NDD
2015-11-23 14 Clarify that a User is an account admin Subusers are users with an account
MDG
2018-12-18 20 Garminized and Validated Document JL
10 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Account API The Account API is a collection of RESTful web services for managing users and devices in the Explore site The web services rely utilize JSON (JavaScript Object Notation) for requests and responses The API is comprised of web services that are currently available at the following URLs Production httpsaccount-apiinreachgarmincomV1Users httpsaccount-apiinreachgarmincomV1SubUsers httpsaccount-apiinreachgarmincomV1Devices httpsaccount-apiinreachgarmincomV1DevicesSubUsers httpsaccount-apiinreachgarmincomV1Plans httpsaccount-apiinreachgarmincomV1TimeZones httpsaccount-apiinreachgarmincomV1CallDataRecords httpsaccount-apiinreachgarmincomV1SyncURL Sandbox httpsaccount-api-testinreachgarmincomV1Users httpsaccount-api-testinreachgarmincomV1SubUsers httpsaccount-api-testinreachgarmincomV1Devices httpsaccount-api-testinreachgarmincomV1DevicesSubUsers httpsaccount-api-testinreachgarmincomV1Plans httpsaccount-api-testinreachgarmincomV1TimeZones httpsaccount-api-testinreachgarmincomV1CallDataRecords httpsaccount-api-testinreachgarmincomV1SyncURL
Updates to this Document The current version of this document is always available at httpfilesdelormecomsupportinreachwebdocsAccount APIpdf
Online (Live) Documentation This API is transitioning to use a web-based live documentation system based on Swagger (httpswaggerio) Swagger is a tool to auto generate REST documentation and client code The current documentation is available at the root Account API URL httpsaccount-apiinreachgarmincom
11 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
REpresentational State Transfer (REST) Web Services REST is a set of architectural principles for the transfer of resources using Hypertext Transfer Protocol (HTTP) It is focused on accessing named resources through a single consistent interface The interface interaction relies on the HTTP request methods to define the access to the resource For example an HTTP-GET request will retrieve a resource and a HTTP-PUT will update a resource More information about REST can be found online httpenwikipediaorgwikiRepresentational_state_transfer
JavaScript Object Notation JSON is a text-based open standard for representing simple data structures Structures in JSON are either namevalue pairs or an ordered list of values A value can be a string number object array true false or null String values are wrapped in double quotations marks (ldquoexamplerdquo) The REST web services use JSON to describe resources in the system Object values begin with a left brace () and end with a right brace () Arrays begin with a left square bracket ([) and end with a right square bracket (]) The system requires that all requires use the applicationjson content-type Please refer to RFC 4627 for a more descriptive definition of JSON httptoolsietforghtmlrfc4627
Costs Commands that deal with device activation status or plan changes have a cost associated with them The HTTP-GET requests are used to query resources at exploregarmincom and incur no costs The POST request methods generally result in commands that create a resource The only resource that can be created is a user Devices are assigned to the account by Garmin The PUT request is idempotent Use these requests to update or set a resource From example use PUT to assign a device to a user
Authentication The API uses basic access authentication to pass credentials to the web service The username and password should be Base64 encoded and passed in the HTTP header See httptoolsietforghtmlrfc1945section-111 for more information
Dates All dates and times are in UTC and follow ISO-8601 2012-06-25T050423Z
HTTPS To increase security and prevent unauthorized use the Account API does not support insecure HTTP transactions Instead all transactions require secure HTTPS
Web Service Objects A default JSON schema is used in the web service to describe users and devices Below is a detailed description of both schemas The web method documentation will link back to these descriptions
12 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
User Object The JSON object that represents a single user in the system Name Type Description ID Number The unique identifier assigned to the user This identifier is
assigned by the Explore website and is immutable This cannot be null for POST or PUT requests
ReferenceID String Storage for an identifier that references an external system The identifier does not have to be unique and is mutable
UserName String The username is a unique email address that is used to login to explore This must be unique
Password String The userrsquos password This parameter is only used when the user account is created or updated If the password is null when the user is created the user will receive an email with a randomly generated password If the password is null when the user updates their account the password will not be changed A HTTP-GET request will return null
DisplayName String The display name used in the Explore website While viewing the map the display name is visible This can be changed If the DisplayName is null the value will default to a combination of the contactrsquos First and Last name
ActivationDate Date The UTC timestamp associated with the date and time the user was activated See Dates for more information about the format used to represent dates This is immutable
DeactivationDate Date The UTC timestamp associated with the date and time the user was deactivated See Dates for more information about the format used to represent dates Cannot be changed
TimeZone String A string the represents the current time zone set in Explore The supported time zones can be queried from the TimeZones service Pass the time zone identifier to set the time zone
Contact Object An object that represents the user contact information EmergencyContact1 Object An object that represents the first emergency contact EmergencyContact2 Object An object that represents the second emergency contact EmergencyNotes String Any notes that the user would like the emergency response team
to see in the event of an emergency Suspended Boolean Whether or not the user account is currently suspended Call the
PUT Usersidsuspend=suspend method to modify Devices Array An array of device IMEIs that are assigned to the user A single
user can have multiple devices A value of null indicates that there are no devices assigned to the user The IMEI is a unique 15 digit number that is assigned to all device Use the devices web service to add or remove devices
The contact object has the following structure Name Type Description FirstName String First name of the user LastName String Last name of the user StreetAddress String Userrsquos street address City String Userrsquos city
13 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
StateOrProvince String The state or province of the user ZipOrPostalCode String The zip or postal code PhoneNumber String The userrsquos phone number MobilePhoneNumber String An optional mobile phone number CountryCode String The two-letter country code Please refer to ISO
3166-1 alpha-2 for more information Email String The userrsquos email address The emergency object has the following structure Name Type Description FirstName String The emergency contactrsquos first name LastName String The emergency contactrsquos last name Relationship String The emergency contactrsquos relationship Spouse
Relative Friend Co-worker or Other PhoneNumber String The emergency contactrsquos phone number MobilePhoneNumber String An alternative phone number This is optional Email String The emergency contactrsquos email address
User Example The following is an example of a single user ID 1253 ReferenceID EXT-16576 UserName usergarmincom Password null DisplayName User ActivateDate 2012-06-22T050423Z DeactivateDate null TimeZone Eastern Standard Time Contact FirstName User LastName Smith StreetAddress 2 DeLorme Drive City Yarmouth StateOrProvince ME ZiporPostalCode 04096 PhoneNumber 8005615105 MobilePhoneNumber 8005615094 CountryCode US Email usergarmincom EmergencyContact1 FirstName Bob LastName Smith Relationship Relative PhoneNumber 12075551234 Email bobsmithemailcom EmergencyContact2 FirstName Jill LastName DeLorme Relationship Spouse Phonenumber 12075554123
14 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Email jillgarminemailcom EmergencyNotes No allergies please call spouse first Suspended false Devices [ IMEI 100000000000000 ]
User Collection Some user GET requests will return a collection of users as the response content The collection or array contains one or more User objects that are comma separated The root name for the array is Users Below is an example with one User object in the array Please see Web Service Objects User Object for details Users [ ID 1253 ReferenceID EXT-16576 UserName userdelormecom Password null DisplayName User ActivateDate 2012-06-22T050423Z DeactivateDate null TimeZone Eastern Standard Time Contact FirstName User LastName Smith StreetAddress 2 DeLorme Drive City Yarmouth StateOrProvince ME ZiporPostalCode 04096 PhoneNumber 8005615105 MobilePhoneNumber 8005615094 CountryCode US Email userdelormecom EmergencyContact1 FirstName Bob LastName Smith Relationship Relative PhoneNumber 12075551234 Email bobsmithemailcom EmergencyContact2 FirstName Jill LastName DeLorme Relationship Spouse Phonenumber 12075554123 Email jilldelormeemailcom EmergencyNotes No allergies please call spouse first Suspended false Devices null
15 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
]
Device Object The JSON object that represents a single device in the system Name Type Description IMEI Number A 15 digit unique identifier assigned to the device AuthCode String The authorization code which can be used to initially
activate the device Type String The device (hardware board) type Recent board types
support more than one product for example the 2_5 board can be used to manufacture either an ldquoSErdquo or an ldquoExplorerrdquo
Product String For recent devices the product as determined during manufacturing (otherwise ldquoUnknownrdquo)
AssignedUserID Number The unique user id that the device is assigned to or null if the device is not assigned
NetworkStatus Number The current status of the device Please refer to definitions below
ActivationDate String The UTC timestamp associated with the date and time the device was activated See Dates for more information about the format used to represent dates
DeactivationDate Object The UTC timestamp associated with the date and time the device was deactivated See Dates for more information about the format used to represent dates
FirmwareVersion Number The current majorminorrevision firmware version number PlanID Number The identifier for the plan that the device is currently
activated under PlanName String The name of the plan that the device is currently activated
under Usage Object An object that describes the device usages See below TransferredDate String UTC date the device was transferred to its current Owner
(only used if device was not originally owned by a reseller) RequiresFirmwareUpdate Boolean True if firmware update is required The usage object has the following structure Name Type Description UnitType String The plans unit type Either messages or bytes UnitsAllotted Number The number of messages or bytes allotted under the plan UnitsUsed Number The current usages in messages or bytes This is updated on a 24
hour cycle BillingCycleDay Number The date that the units used are reset Descriptions and values for NetworkStatus Name Type Value Description Inactive Number 0 The device has not been activated Activation Pending Number 1 The device is in the process of activation Activated Number 2 The device is activated Suspension Pending Number 3 The device is in the process of being suspended
16 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Suspended Number 4 The device is suspended Unsuspension Pending Number 5 The device is in the process of unsuspension Deactivation Pending Number 6 The device is in the process of deactivation RMA Number 7 The device has been RMArsquoed Deferred Activation Number 8 The device is in deferred activation This means that
is assigned to a user account but not activated ManufacturingComplete
Number 9 The device has completed manufacturing but has not been placed in inventory
LockError Number 10 An attempt was made to lock the device against being activated (such as prior to shipping) but this failed
MoveToDeLormeError Number 11 An attempt was made to give ownership of the device to DeLorme but this failed
Device Example The following is an example of a single device IMEI 100000000000000 AuthCode 12345 Type inReach_25 Product Explorer AssignedUserID 1234 NetworkStatus 1 PlanID 9 PlanName ldquoDeLorme 1rdquo ActivationDate 2014-06-22T050423Z DeactivationDate null FirmwareVersion 2742864 Usage UnitType Bytes UnitsAllotted 1500 UnitsUsed 15 BillingCycleDay 7 TransferredDate 0001-01-01T000000 RequiresFirmwareUpdate false DeviceName My Device
Device Collection Some device GET requests will return a collection of devices as the response content The collection or array contains one or more Device objects that are comma separated The root name for the array is Devices Below is an example Please see Web Service Objects Device Object for details Devices [ IMEI 100000000000000 hellip IMEI 100000000000023 hellip
17 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
]
Call Data Record Object
Attributes Attribute Name Attribute Description Example TotalUnits The sum of units or
bytes for all devices registered with customer The example to the right would be equal to 27101 bytes
TotalUnits=27101
TotalMessages The total number of message instances for all devices registered with customer
TotalMessages=1774
Devices The devices element holds the collection of devices
Device This element represents a single device
Attributes Attribute Name Attribute Description Example IMEI The 15-digit IMEI or unique
identifier for an inReach device IMEI=5000000000000001
Units The number of units or bytes used by a single device The example to the right would be equal to 1635 bytes
Units=rdquo1635rdquo
Messages The number of messages used by a single device
Messages=rdquo109rdquo
MessageDetails The element holds the collection of MessageInstances
MessageInstance This element contains information about an instance of device usage
Attributes Attribute Name Attribute Description Example Direction The direction of the message
Can be either MO (Mobile Direction=MO
18 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Originated data from device to portal) or MT (Mobile Terminated data from portal to device)
MessageTime The date and time the message was sent from the device in MO messages and from the app serverIPC outbound in MT messages
MessageTime =2012-03-23T183511
GatewayTime The date and time the message was received at the Garmin gateway
GatewayTime=2012-03-23T183512
Type The type of message See MOMT Message Types tables for all possible message types
Type=Tracking
Status The status of the message Can be either ldquoPendingrdquo ldquoSuccessrdquo or ldquoFailedrdquo
Status=Success
Units The number of units or bytes that were used in this instance
Units=15
Status If the status is pending compare to the next report to determine the final result
MO Message Types MO Message Type MO Message Description Tracking Sent by inReach for an existing tracking event Location Sent by the inReach in response to an MT
message requesting the current location Text Message Sent when there is a free text message being
transmitted Emergency Confirmation Confirms an unconfirmed SOS Emergency Cancellation Stops an SOS event Emergency Declaration Declares an emergency state Reference Point Send a non-GPS location Track Start Begins a tracking process on the server Check-in Response to a scheduled or unscheduled check-
in Track IntervalChange Changes the tracking interval Track Stop Ends a tracking process on the server Puck Message1 Sends the first of three inReach message button
events Puck Message2 Sends the second of three inReach message
button events Puck Message3 Sends the third of three inReach message button
events MapShare Sends a MapShare message
19 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
MT Message Types MT Message Type MT Message Description Unknown Unknown message Check-in Reminder Sent by the app to alert the device user they have
missed their scheduled checkin Check-in Request Sent by the app to request a checkin from the
device user Text Message Sent by the app as an MT message for the
device user and includes GPS data form the MO message Used for device to device messaging
Reference Point Sent by the app and includes GPS data form the MO message
Location Request Sent by the app to request the current location of the unit The unit should respond with the current location of the device without user intervention
Response Loc Request Sent by the app to the device for a device that has requested the location of another device user The GPS is from the MO locate message of the located user Used in a device to device request
Enable Tracking Sent by app to instruct the device to enter tracking mode The device should respond with a tracking start MO message
Disable Tracking Sent by app to instruct the device to exit tracking mode The device should respond with a tracking end MO message
Tracking Interval Sent by app to instruct the device to alter the tracking interval The device should respond with a tracking interval MO message
Initiate Emergency Sent by emergency services to set device into in emergency state
Close Emergency Sent by emergency services to cancel emergency
Confirm Emergency Sent by the server in response to the Declare Emergency MO events Sent continually until Garmin unit sends confirm emergency MO event
Emergency Cancelled Sent by app to acknowledge the device has canceled the Emergency
EmergencyDeclareECC Sent by app to instruct the unit to enter emergency mode Device should behave like it has initiated the declare event
EmergencyAcknowledgementECC Sent by the ECC ndash manually triggered ack in response to a new Declare Emergency event
EmergencyCancellationECC A sent by app to instruct the unit to exit emergency mode Device should return to normal state Manually triggered
20 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
ECC Emergency Contact Center
Settings This element represents all of the settings for the current reseller
Attributes Attribute Name Attribute Description Example ActivationRedirectURI The URI that users will
arrive at when redirected from the Garmin activation wizard to the reseller
httpsinreach[reseller]cominreachactivationredirectIMEI=IMEIampAuthorizationCode=AuthCode
BillingRedirectURI The URI that users will arrive at when redirected from the Garmin Explore site to the reseller
httpsinreach[reseller]cominreachbillingredirectReferenceId=
PasswordSyncURL The URL that will be used to synchronize the user account and password with the resellerrsquos account records This will be in the form of a POST back request that contains the full user object with password as the content Includes basic authentication header To disable this feature set the property to NULL
httpsinreach[reseller]cominreachpasswordsync
CustomerCareErrorMsg An error message that tells the user to contact customer care This message will be appended to the end of a relevant system error An example would be when password sync POST back fails
For assistance contact Garmin Technical Support 1-800-293-2389 Professionalsupportgarmincom
21 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
SyncURL This element represents the URL to use for device sync operations
Attribute SyncURL The URL to use in device sync operations
Work Flow The Account Web API is a RESTful web service For testing all of the GET requests can be accomplished with a web browser The rest of the work flow is a more complicated Please follow the steps below to create a user assign the device to a user and activate the device
Work Flow Order
Create UserCreate User
Assign DeviceAssign Device
Activate DeviceActivate Device
Creating a User A user can be created by sending a HTTP-POST request to the Users service The content-type for the request is ldquoapplicationjsonrdquo The content must be a single User object The Users web service will validate content If an error occurs during validation the web service will respond with an error Json object Otherwise the web service will respond with the new userrsquos unique identifier This unique identifier is used for most requests
Request Request Type POST Content Type applicationjson Content User Object URL httpsaccount-apiinreachgarmincomV1Users
Assigning the Device to a User Assigning a device to a user can be accomplished using the Devices web service The web service requires that the device is not activated before assignment If successful the device will go into deferred activation status Otherwise the service will respond with an error Json object The HTTP request does not require any content and requires the Device IMEI and User ID parameters Use the HTTP-PUT request type to the URI DevicesIMEIuserid=userid web method Substitute the 15 digit device IMEI for IMEI and the userrsquos unique identifier for userid
22 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
For example to assign device 100000000000000 to user 1 the URL would be httpsaccount-apiinreachgarmincomV1Devices100000000000000userid=1
Activating a Device A device can be activated when it has been assigned to a user and is in the inactive state As with device assignment the HTTP request does not require any content It does require the Device IMEI and Plan ID The Plan ID is the unique identifier for the plan that the device will be activated on A list of plans can be requested from the Plans web service Use the HTTP-POST request type to the URI DevicesIMEIplanid=planid web method to activate the device Substitute the 15 digit device IMEI for IMEI and the planrsquos unique identifier for planid For example to activate device 100000000000000 on plan 5 the URL would be httpsaccount-apiinreachgarmincomV1Devices100000000000000planid=5
Setting a Device Name Optionally a device can be given a name (sometimes called an ldquoaliasrdquo) which may be more convenient to recognize than the IMEI The device name appears occasionally in the Explore web portal such as in the device grid The value can be changed by the user The device name (if any) appears in the Device object returned by other methods of this API The name should not exceed 30 characters To change the device name through this API use a PUT call such as this example httpsaccount-apiinreachgarmincomV1Devices100000000000000name=myname or to clear the name use httpsaccount-apiinreachgarmincomV1Devices100000000000000name=
Password Synchronization An optional feature of the Account API is user account password synchronization If the user changes their password in the Garmin Explore site the site will attempt to synchronize the change with the resellerrsquos records This is accomplished through a HTTP-POST directed at the resellerrsquos password synchronization URL The URL is configurable through the Settings methods Setting the URL to NULL disables password synchronization The request will include the basic authentication header with the resellerrsquos account credentials The content of the request is a populated User Object with the password property filled in The resellerrsquos web service should respond to the request with a HTTP status code 200 This indicates success Any other status codes will be considered an error In the event of an error the user will be prompted with an error message that includes the customer care error message from the Settings The userrsquos password will not be rolled back
Users This service provides the ability to manage the admin users accessible to an account Users can be queried updated and created The same User JSON schema is used to represent users for all of the web service methods Please see Web Service Objects User Object for details To retrieve information about users within an account use one of the Subusers methods
23 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Usersuserid (GET) Get User by Identifier This web method will return a single user that is defined by the userid parameter The userid is a unique identifier that is assigned to all users The unique identifier is automatically assigned to the user by Garmin and is immutable Action GET Parameters The userrsquos unique identifier Content None Returns A single user associated with the request or error Cost None
Request Object None
Response Object Please see Web Service Objects User Object for details
Example The following example requests a single user with the user id 1253
URL httpsaccount-apiinreachgarmincomV1Users1253
Response Content Please see Web Service Objects User Object for details
Users (GET) Get All Users This method returns the admin user accessible to the account Action GET Parameters None Content None Returns A collection of admin users Cost None
Request Object None
Response Object Name Type Description Users Array A collection of user objects Please see Web Service Objects Users
Collection
Example The following example requests the admin user accessible to the account
URL httpsaccount-apiinreachgarmincomV1Users
24 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Response Content An array of Users Please see Web Service Objects Users Collection for details
Usersreferenceid=referenceid (GET) Get All Users with Reference ID This method returns a collection of users that match the reference id parameter Action GET Parameters Reference ID Content None Returns A collection of users that contain the same reference ID as the parameter Cost None
Request Object None
Response Object Name Type Description Users Array A collection of user objects Please see Web Service Objects Users
Collection
Example The following example requests all of the users associated with the account that have the given reference id value
URL httpsaccount-apiinreachgarmincomV1Usersreferenceid=EXT-16576
Response Content An array of Users Please see Web Service Objects Users Collection for details
Usersusername=username (GET) Get All Users with User Name This method returns a collection of the admin user with a user name The username is the same as the user login or email address Action GET Parameters User Login Name Content None Returns A collection of users that contain the same user name as the parameter Cost None
Request Object None
Response Object Name Type Description Users Array A collection of user objects Please see Web Service Objects Users
Collection
25 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Example The following example requests all of the users with the given username
URL httpsaccount-apiinreachgarmincomV1Usersusername=johnsmithgarmincom
Response Content An array of Users Please see Web Service Objects Users Collection for details
Usersimei=imei (GET) Gets User Assigned to Device This method returns a collection of an admin user assigned to the device Action GET Parameters Device IMEI Content None Returns A single user in an array that is assigned to the device Cost None
Request Object None
Response Object Name Type Description Users Array A collection of user objects Please see Web Service Objects Users
Collection
Example The following example requests all of the users associated with the given IMEI
URL httpsaccount-apiinreachgarmincomV1Usersimei=100000000000000
Response Content An array of Users Please see Web Service Objects Users Collection for details
Users (POST) Create User Creates a new user and assigns that user a unique identifier The service responds with a user ID if successful Action POST Parameters None Content A user object Please see Web Service Objects User Object for details Returns A JSON response object with the new system User ID or an error response Cost There is no cost associated with this request
Request Object Please see Web Service Objects User Object for details
Response Object An object with the new user identifier
26 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Name Type Description UserID Number A new unique user identifier
Example The following example creates a new user
URL httpsaccount-apiinreachgarmincomV1Users
Request Content Please see Web Service Objects User Object for details
Response Content Successful true UserID 1253
Users (PUT) Update User Information This method updates the user information The service responds with the user identifier of the user that was updated The ID value in the User Object is used to determine which user will be updated Action PUT Parameters None Content A user object Please see Web Service Objects User Object for details Returns A JSON response object with a user id or an error response Cost There is no cost associated with this request
Request Object Please see Web Service Objects User Object for details
Response Object An object with the user identifier Name Type Description UserID Number A new unique user identifier Successful Boolean True if successful
Example The following example request updates the user with ID 1253
URL httpsaccount-apiinreachgarmincomV1Users
Request Content Please see Web Service Objects User Object for details
Response Content
27 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Successful true UserID 1253
Usersidsuspend=suspend (PUT) Suspend User This method suspends or de-suspends a user account A suspended user cannot log into the Explore website This method does not deactivate the device Action PUT Parameters User Id Boolean (true suspends and false de-suspends) Content None Returns A JSON response object with a user id or an error response Cost There is no cost associated with this request
Response Object An object with the user identifier Name Type Description UserID Number A new unique user identifier Successful Boolean True if successful
Example The following example suspends the user with ID 1253
URL httpsaccount-apiinreachgarmincomV1Users1253suspend=true
Request Content Please see Web Service Objects User Object for details
Response Content Successful true UserID 1253
Userspassword=password (GET) Validates Password Meets This method validates that a password meets the minimum requires for an Explore account Action GET Parameters The password that is validated Content None Returns A JSON response object with a Boolean that indicates success or failure If false a message that describes why the password is not valid Cost There is no cost associated with this request
28 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Request Object None
Response Object An object with the results of the password evaluation Name Type Description Valid Boolean True if valid otherwise false Refer to Message if false Message String A human readable string that describes why the password is not
valid
Example The following example values the password Password
URL httpsaccount-apiinreachgarmincomV1userspassword=Password
Request Content None
Response Content Valid false Message Password must contain at least one non-letter
29 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Sub Users This interface provides methods to manage sub users Sub users are child user objects that are ldquoownedrdquo by the User objects created and maintained through the Users interface
SubUsersparentUserId=parentUserId (GET) Get All Sub Users Gets all users owned by the given Parent User Action Get Query string parameters Parameter Name Value parentUserId The ldquoOwningrdquo user ID This is the ID of the user
that was created or retrieved through the ldquoUsersrdquo interface
Content none Returns A collection of user objects Cost There is no cost associated with this request
Request Object None
Response Object Name Type Description Users Array A collection of user objects Please see Web Service Objects Users
Collection
Example URL httpsaccount-apiinreachgarmincomV1SubUsersparentUserId=47
Response Content An array of Users Please see Web Service Objects Users Collection for details
SubUsersparentUserId=parentUserId (POST) Create a new Sub User Creates a new sub user under the given parent User account Action POST Query string parameters Parameter Name Value parentUserId The ldquoOwningrdquo user ID This is the ID of the user
that was created or retrieved through the ldquoUsersrdquo interface
Content A User Object Returns A JSON object with the new sub user ID or an error object Cost There is no cost associated with this request
30 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Request Object Please see Web Service Objects User Object for details
Example URL httpsaccount-apiinreachgarmincomV1SubUsersparentUserId=47 Response Object Successful true UserID 1253
SubUsersparentUserId=parentUserId (PUT) Update a Sub User Creates a new sub user under the given parent user account Requires the ID field of the requested User Object to be a valid previously generated Sub User ID Action PUT Query string parameters Parameter Name Value parentUserId The ldquoOwningrdquo user ID This is the ID of the user
that was created or retrieved through the ldquoUsersrdquo interface
Content A User Object Returns A JSON object with the edited user ID or an error object Cost There is no cost associated with this request
Request Object Please see Web Service Objects User Object for details
Example URL httpsaccount-apiinreachgarmincomV1SubUsersparentUserId=47 Response Object Successful true UserID 1253
31 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
SubUsersuserIdparentUserId=parentUserId (DELETE) Delete a Sub User Creates a new sub user under the given parent user account Requires the ID field of the requested User Object to be a valid previously generated Sub User ID Action PUT Query string parameters Parameter Name Value parentUserId The ldquoOwningrdquo user ID This is the ID of the user
that was created or retrieved through the ldquoUsersrdquo interface
Content None Returns A JSON object with the deleted user ID or an error object Cost There is no cost associated with this request
Request Object None
Example URL httpsaccount-apiinreachgarmincomV1SubUsers1234parentUserId=47
Response Object Successful true UserID 1253
SubUsersuserIdparentUserId=parentUserIdampsuspend=suspend (PUT) Suspend a Sub User Suspend or unSuspend the specified Sub User account Action PUT Query string parameters Parameter Name Value parentUserId The ldquoOwningrdquo user ID This is the ID of the user
that was created or retrieved through the ldquoUsersrdquo interface
Suspend ldquotruerdquo or ldquofalserdquo Suspends or unsuspends the specified User Id
Content None Returns A JSON object with the suspended user ID or an error object Cost There is no cost associated with this request
32 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Request Object None
Example URL httpsaccount-apiinreachgarmincomV1SubUsersparentUserId=47ampsuspend=true
Response Object Successful true UserID 1253
Devices This interface provides methods to request devices
Devicesimei (GET) Get Device by IMEI Gets a single device that matches the IMEI parameter Action Get Parameter The device IMEI Content none Returns A device object Cost There is no cost associated with this request
Request Object None
Response Object Please see Web Service Objects Device Object for details
Example The following example requests a single device associated with the account
URL httpsaccount-apiinreachgarmincomV1Devices100000000000000 Response Content Please see Web Service Objects Device Object for details
Devices (GET) Get All Devices Returns a collection of devices that are associated with the account Action Get Parameter none
33 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Content none Returns An array of devices Cost There is no cost associated with this request
Request Object None
Response Object An array of devices Name Type Description Devices Array A collection of device objects Please see Web Service Objects
Device Collection for details
Example The following example requests all of the devices associated with the account and the response contains no devices
URL httpsaccount-apiinreachgarmincomV1Devices
Response Content Please see Web Service Objects Device Collection for details
Devicesimeiauthcode=authcode (GET) Validate IMEI and Auth Code This method returns the device object if valid or null if the IMEI and Authorization Code to not match Action GET Parameters Device IMEI and the authorization code Content None Returns A JSON object with the validation result Cost There is no cost associated with this request
Request Object None
Response Object A JSON object that describes whether the IMEI and authorization code are valid Name Type Description Valid Boolean True if valid otherwise false Message String A message that explains when the IMEI is not valid
Example The following example request validates a device IMEI and authorization code
URL httpsaccount-apiinreachgarmincomV1Devices100000000000000authcode=47788
34 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Request Content None
Response Content Valid true Message ldquordquo
Devicesimeiuserid=userid (PUT) Assign User to Device This method assigns a specific user to a device Action PUT Parameters Device IMEI and the User ID Content None Returns A JSON object with the result Cost There is no cost associated with this request
Request Object None
Response Object An object with the new user identifier Name Type Description Success Boolean True if valid otherwise false IMEI Number The IMEI of the device that was updated
Example The following example assigned a user 1253 to device 100000000000000
URL httpsaccount-apiinreachgarmincomV1Devices100000000000000userid=1253
Request Content None
Response Content Success true IMEI 100000000000000
Devicesimeiplan=planid (PUT) Activate Device with Plan Activates or changes the device on a specific plan The process is asynchronous Please query the device to get network status
35 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Action PUT Parameters Device IMEI and the Plan ID Content None Returns A JSON object with the result Cost There is a cost associated with activating or changing the plan for a device
Request Object None
Response Object A JSON object that indicates success or failure message Name Type Description Success Boolean True if the process has started IMEI Number The IMEI of the device that was updated
Example The following example activate device 100000000000000 on plan 9
URL httpsaccount-apiinreachgarmincomV1Devices100000000000000planid=9
Request Content None
Response Content Success true IMEI 100000000000000
Devicesimei (DELETE) Deactivate Device Deactivates a device The process is asynchronous Please query the device to get network status Action Delete Parameters Device IMEI Content None Returns A JSON object with the result Cost There is a cost associated with activating or deactivating a device
Request Object None
Response Object A JSON object that indicates success or failure message Name Type Description Success Boolean True if the process has started
36 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
IMEI Number The IMEI of the device that was updated
Example The following example deactivates device 100000000000000
URL httpsaccount-apiinreachgarmincomV1Device100000000000000
Request Content None
Response Content Success true IMEI 100000000000000
SubUserDevices This interface provides methods to control device assignment to sub users It cannot be used to activate or deactivate devices Devices must be activated or deactivated through the Devices interface
DevicesSubUsersuserIdparentUserId=parentUserIdampimei=imei (PUT) Assign a device to a sub user Assigns the specified device to the given sub user Action PUT Query string parameters Parameter Name Value parentUserId The ldquoOwningrdquo user ID This is the ID of the user
that was created or retrieved through the ldquoUsersrdquo interface
imei The IMEI of the already-activated device that is already owned by the parentUserId This will be assigned to the userId (Sub User)
Content None Returns A JSON object with the assigned user ID or an error object Cost There is no cost associated with this request
37 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
DevicesSubUsersuserIdparentUserId=parentUserId (DELETE) Unassigns any device from the sub user This method unassigns any assigned device from the specified sub user ID Action DELETE Query string parameters Parameter Name Value parentUserId The ldquoOwningrdquo user ID This is the ID of the user
that was created or retrieved through the ldquoUsersrdquo interface
Content None Returns A JSON object with the un-assigned user ID or an error object Cost There is no cost associated with this request
38 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Plans This interface provides methods to request available device plans Note that all costs and fees are returned in US Dollars
Plans (GET) Get All Device Plans Returns a list of plans that are available to the account Action GET Parameters None Content None Returns A JSON object with an array of plans Cost There is no cost associated with this request
Request Object None
Response Object An array of plan objects Name Type Description Plans Array An array of plan objects A plan object Name Type Description PlanID Number A unique identifier for the plan PlanName String The name of the plan PlanActivationFee Number The cost to activate this device PlanDescription String A general description of the plan PlanExtendedDescription String A more verbose description of the plan PlanRecurringCharge Number The recurring monthly cost of the plan PlanSwitchFee Number The cost associated with changing plans PlanContractTerm Number The number of months the device will be under contract UnitType Number The unit type 0 = Messages 1 = Bytes UnitsAllotment Number The total units allotted for one billing cycle PlanOverageFee Number The fee associated with byte overages PlanCategory String The name of the category the plan is in All costs and fees are returned in US Dollars
Example The following example request gets an array of device plans
URL httpsaccount-apiinreachgarmincomV1Plans
Request Content None
39 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Response Content Plans [ PlanID 9 PlanName DeLorme 1 PlanActivationFee 25 PlanDescription PlanExtendedDescription PlanRecurringCharage 15 PlanSwitchFee 30 PlanContractTerm 12 UnitType 2 UnitAllotment 1500 UnitOverageFee 00060 PlanCategory Wholesale Rate Plans ]
40 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Time Zones This interface provides methods to request available user time zones
TimeZones (GET) Get All Device Plans Returns a list of time zones that are available to the account Action GET Parameters None Content None Returns A JSON object with an array of time zones Cost There is no cost associated with this request
Request Object None
Response Object An array of time zones objects Name Type Description TimeZones Array An array of time zone objects A plan object Name Type Description UtfOffsetInHours Number The offset in hours from UTC DaylightName String The name during daylight saving time DisplayName String The text that should be displayed to a user ID String The unique identifier for the time zone Use this when
creating a user StandardName String The standard name for the time zone SupportsDaylightSavingTime Boolean Whether or not the time zone supports daylight saving
time True if supported or false if not supported
Example The following example request gets an array of device plans
URL httpsaccount-apiinreachgarmincomV1TimeZones
Request Content None
41 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Response Content TimeZones [ UtcOffsetInHours -12 DaylightName Dateline Daylight Time DisplayName (UTC-1200) International Date Line West ID Dateline Standard Time SupportsDaylightSavingTime Dateline Standard Time PlanRecurringCharage false ]
42 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Call Data Records This interface provides methods to request available call data records
CallDataRecordsstartdate=startdateampenddate=enddate (GET) Get All Call Data Records Returns a collection of call data records The start and end date are the range for the query They should be in ISO-8601 format Action GET Parameters Start and End Date Content None Returns A JSON object with an array of call data records for all users Cost There is no cost associated with this request
Request Object None
Response Object
Example The following example request gets an array of call data records
URL
httpsaccount-apiinreachgarmincomv1CallDataRecordsstartdate=11262013ampenddate=12272013
Request Content None
43 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Response Content Devices [ IMEI 300234010571020 PlanID 0 Units 0 Messages 0 MessageDetails [] IMEI 300234011306220 PlanID 11 Units 13 Messages 1 MessageDetails [ Direction MO MessageTime 2013-11-26T000454 GatewayTime 2013-11-26T000455503 Type Tracking Status Success Units 13 MessageCode 0 ] ] TotalUnits 13 TotalMessages 1
CallDataRecordsstartdate=startdateampenddate=enddateampimei=imei (GET) Get All Call Data Records Returns a collection of call data records for the user of the device IMEI passed as the parameter The start and end date are the range for the query They should be in ISO-8601 format Action GET Parameters Start and End Date Content None Returns A JSON object with an array of call data records for a single user Cost There is no cost associated with this request
Request Object None
Response Object
Example The following example request gets an array of call data records for device 100000000000000
44 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
URL
httpsaccount-apiinreachgarmincomv1CallDataRecordsstartdate=11262013ampenddate=11272013ampimei=300434060103480
Request Content None
Response Content Devices [ IMEI 300434060103480 PlanID 3 Units 31 Messages 2 MessageDetails [ Direction MO MessageTime 2013-11-26T211024 GatewayTime 2013-11-26T211030883 Type Track Start Status Success Units 18 MessageCode 16 Direction MO MessageTime 2013-11-26T212027 GatewayTime 2013-11-26T21202982 Type Tracking Status Success Units 13 MessageCode 0 ] ] TotalUnits 31 TotalMessages 2
CallDataRecordsstartdate=startdateampenddate=enddate ampuserid=userid (GET) Get All Call Data Records Returns a collection of call data records for a single user The start and end date are the range for the query They should be in ISO-8601 format Action GET Parameters Start and End Date Content None Returns A JSON object with an array of call data records for a single user Cost There is no cost associated with this request
45 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Request Object None
Response Object
Example The following example request gets an array of call data records
URL
httpaccount-apiinreachgarmincomV1CallDataRecordsstartdate=2012-06-20T050423Zampenddate=2012-08-10T050423Zampuserid=1253
Request Content None
Response Content Devices [ IMEI 300434060103480 PlanID 3 Units 31 Messages 2 MessageDetails [ Direction MO MessageTime 2013-11-26T211024 GatewayTime 2013-11-26T211030883 Type Track Start Status Success Units 18 MessageCode 16 Direction MO MessageTime 2013-11-26T212027 GatewayTime 2013-11-26T21202982 Type Tracking Status Success Units 13 MessageCode 0 ] ] TotalUnits 31 TotalMessages 2
46 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Settings This service provides the ability to manage settings for the current reseller Please see Web Service Objects Settings Object for details
Settings (GET) Get Reseller Settings This web method will return the current settings for the authenticated Account API requestor Action GET Parameters None Content None Returns A single settings object or error Cost None
Request Object None
Response Object Please see Web Service Objects Settings Object for details
Example The following example requests the settings for the currently authenticated user
URL httpsaccount-apiinreachgarmincomV1Settings
Response Content Please see Web Service Objects Settings Object for details
Settings (PUT) Update Reseller Settings This method updates the settings for the authenticated Account API requestor The service responds with a Boolean success or failure Action PUT Parameters None Content A Settings object Please see Web Service Objects Settings Object for details Returns A JSON response object with a Boolean success or error response Cost There is no cost associated with this request
Request Object Please see Web Service Objects Settings Object for details
Response Object An object with the success or failure of the operation Name Type Description Successful Boolean True if successful Message String A human readable string that describes why the settings were not
saved successfully
47 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Example The following example request updates the currently authenticated requestorrsquos settings
URL httpsaccount-apiinreachgarmincomV1Settings
Request Content Please see Web Service Objects Settings Object for details
Response Content Successful true Message
48 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
SyncURL This service provides an optional ability to use a redirect URL to for Device Sync information
SyncURLIMEI=imei (GET) Get SyncURL for imei Returns a URL to use for synchronizing device information Action GET Parameters imei Content None Returns A JSON object with a URL to use for device sync requests
URL httpsaccount-apiinreachgarmincomV1SyncURLIMEI=000000000000000
Request Content None
Response Content SyncURL httpstestURLcom
HTTP Status Codes The web services return standard HTTP status codes to reflect the success or failure of the requested action The web services will generally return one of the following status codes
bull 200 Success This status will be returned by all API calls if completed successfully The JSON object contained within is dependent on the API call
bull 401 Unauthorized This status will be returned if the username and password are not present The JSON object contained will be an error object
bull 403 Forbidden This status will be returned if the username and password are incorrect The JSON object contained will be an error object
bull 422 Unprocessable Entity This status will be returned when the command is well-formed but cannot be executed due to a semantic error The JSON object contained will be an error object
bull 429 Too Many Requests This status will be returned when too many requests have been made to the Account web services To ensure the web services function satisfactorily under heavy demand the services will automatically throttle disproportionate usage Generally waiting a few seconds and trying again should resolve the issue
49 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
The response will contain the Retry-After header which will contain the number of seconds the client should wait until it tries again The JSON object contained will be an error object
bull 500 Internal Error This status will be returned when there is an internal failure in the inReach API The JSON object contained will be an error object
bull 501 Not Implemented This status will be returned by any unimplemented API function The JSON object contained will be an error object
Errors When a web service request fails it will return a JSON error object containing detailing the error
Error Codes The following error codes are defined Future error codes will be appended to the end of this list Code Name Description 1 InternalError An unexpected error occurred
This will be returned when the error does not fall into any other category
2 TooManyRequestsError Too many concurrent requests are being processed This error will be returned when the server is under heavy usage and cannot satisfy your request Waiting a few seconds and trying again should generally resolve the issue The web services automatically throttle usage from all customers to ensure that a single customer does not saturate the serverrsquos capacity and negatively affect the performance for all
3 AuthenticationError Invalid username or password Either the basic access authentication header is missing or the passed credentials are invalid
4 UnknownDeviceError The specified IMEI does not belong to the tenant Only devices belonging to the tenant can be used by the API
5 UnknownUserError The message length is invalid A text message may not be empty and has a maximum possible length of 160 When sending a reference point with a non-empty label the length of the locationrsquos label counts towards this limit
6 InvalidTimestampError The message timestamp is invalid The timestamp of the message must be on or after Jan 1 2011 and cannot be in the future
7 InvalidUserError The user object contains invalid values 8 InvalidDeviceError The device object contains invalid values 9 Not Implemented The method has not been implemented 10 UnknownPlanError The specific plan does not belong to the owner
JSON Error Object Upon error the following error object will be returned Name Type Description Code Number An error code from Error Codes Description String An optional description of the error
50 Account API This information is confidential and proprietary and many not be reproduced in whole or part unless authorized by an authorized representative of Garmin copy 2012-2019 Garmin
Message String A textual representation of the error code URL String The URL of the web request that failed IMEI Array An array of IMEIs that the request was unable to act upon and
caused the request to fail
Example Error Result Code 4 Description The IMEI 300234010000000 is invalid Message The specified IMEI does not belong to the tenant URL httpsinreachgarmincomAccountV1device
- V 20 Updated 12182018
- Revision History
- Account API
-
- Updates to this Document
-
- Online (Live) Documentation
- REpresentational State Transfer (REST) Web Services
- JavaScript Object Notation
-
- Costs
- Authentication
- Dates
- HTTPS
-
- Web Service Objects
-
- User Object
- User Example
- User Collection
- Device Object
- Device Example
- Device Collection
- Call Data Record Object
-
- Attributes
-
- Devices
- Device
-
- Attributes
-
- MessageDetails
- MessageInstance
-
- Attributes
- MO Message Types
- MT Message Types
-
- Settings
-
- Attributes
-
- SyncURL
-
- Attribute
-
- Work Flow
-
- Creating a User
-
- Request
-
- Assigning the Device to a User
- Activating a Device
- Setting a Device Name
-
- Password Synchronization
- Users
-
- Usersuserid (GET) Get User by Identifier
-
- Request Object
- Response Object
- Example
-
- URL
-
- Response Content
-
- Users (GET) Get All Users
-
- Request Object
- Response Object
- Example
-
- URL
-
- Response Content
-
- Usersreferenceid=referenceid (GET) Get All Users with Reference ID
-
- Request Object
- Response Object
- Example
-
- URL
-
- Response Content
-
- Usersusername=username (GET) Get All Users with User Name
-
- Request Object
- Response Object
- Example
-
- URL
-
- Response Content
-
- Usersimei=imei (GET) Gets User Assigned to Device
-
- Request Object
- Response Object
- Example
-
- URL
-
- Response Content
-
- Users (POST) Create User
-
- Request Object
- Response Object
- Example
-
- URL
- Request Content
-
- Response Content
-
- Users (PUT) Update User Information
-
- Request Object
- Response Object
- Example
-
- URL
- Request Content
-
- Response Content
-
- Usersidsuspend=suspend (PUT) Suspend User
-
- Response Object
- Example
-
- URL
- Request Content
-
- Response Content
-
- Userspassword=password (GET) Validates Password Meets
-
- Request Object
- Response Object
- Example
-
- URL
- Request Content
-
- Response Content
-
- Sub Users
-
- SubUsersparentUserId=parentUserId (GET) Get All Sub Users
-
- Request Object
- Response Object
- Example
- Response Content
-
- SubUsersparentUserId=parentUserId (POST) Create a new Sub User
-
- Request Object
- Example
-
- SubUsersparentUserId=parentUserId (PUT) Update a Sub User
-
- Request Object
- Example
-
- SubUsersuserIdparentUserId=parentUserId (DELETE) Delete a Sub User
-
- Request Object
- Example
- Response Object
-
- SubUsersuserIdparentUserId=parentUserIdampsuspend=suspend (PUT) Suspend a Sub User
-
- Request Object
- Example
- Response Object
-
- Devices
-
- Devicesimei (GET) Get Device by IMEI
-
- Request Object
- Response Object
- Example
-
- URL
-
- Devices (GET) Get All Devices
-
- Request Object
- Response Object
- Example
-
- URL
-
- Response Content
-
- Devicesimeiauthcode=authcode (GET) Validate IMEI and Auth Code
-
- Request Object
- Response Object
- Example
-
- URL
- Request Content
-
- Response Content
-
- Devicesimeiuserid=userid (PUT) Assign User to Device
-
- Request Object
- Response Object
- Example
-
- URL
- Request Content
-
- Response Content
-
- Devicesimeiplan=planid (PUT) Activate Device with Plan
-
- Request Object
- Response Object
- Example
-
- URL
- Request Content
-
- Response Content
-
- Devicesimei (DELETE) Deactivate Device
-
- Request Object
- Response Object
- Example
-
- URL
- Request Content
-
- Response Content
-
- SubUserDevices
-
- DevicesSubUsersuserIdparentUserId=parentUserIdampimei=imei (PUT) Assign a device to a sub user
- DevicesSubUsersuserIdparentUserId=parentUserId (DELETE) Unassigns any device from the sub user
-
- Plans
-
- Plans (GET) Get All Device Plans
-