TruckDown

API Reference

Table of Contents

API Reference

User Info

Getting Basic User Information

Request Url End Point
https://www.truckdown.com/apiv2/user?key=api_key
Request Type:
GET
Scope Required:
Account
Request Query String Parameters:
None
HTTPS Required:
Yes
Response:
JSON Object
Field:
user_name
Description:
The user’s User Name (typically the same as the email). This is what the user uses when logging into TruckDown.com.
Field:
fname
Description:
The user’s first name as entered when they registered their account on TruckDown.com. This value cannot be blank.
Field:
lname
Description:
The user’s last name as entered when they registered their account on TruckDown.com. This value cannot be blank.
Field:
email
Description:
The user’s email address.
Field:
company_name
Description:
The user’s company name. This value can be blank.
Field:
phone
Description:
The user’s primary phone number. This is returned as a ten digit string of digits only.
Field:
ext
Description:
If applicable, an extension number associated with the user’s primary phone number. This value is a number or blank.
Field:
picture
Description:
The user’s profile picture. Thie image can be retrieved at http://www.truckdown.com/file/profile-picture/[picture].
Field:
tz
Description:
The user’s Time Zone
Field:
uofm
Description:
The user’s preferred unit of measure system. Possible values are Imperial or Metric.
Field:
radius
Description:
The radius to give premium vendors priority in any search results. This value is a number and represents the number of miles from the search point. Possible values are 0, 5, 10, 15, 20, 25, 50, or 100.
Field:
pri_radius
Description:
The radius to give private vendors priority in any search results. This value is a number and represents the number of miles from the search point. Possible values are 0, 5, 10, 15, 20, 25, 50, or 100.
Field:
pref_radius
Description:
The radius to give preferred vendors priority in any search results. This value is a number and represents the number of miles from the search point. Possible values are 0, 5, 10, 15, 20, 25, 50, or 100.
Field:
newsletter
Description:
A true/false value indicating if the user will receive the TruckDown newsletter.

Response Example:

                    
{
    user_name: “test_account”,
    fname: “Peter”,
    lname: “Gordon”,
    email: “pgordon@truckdown.com”, 
    company_name: “TruckDown Info International Inc.”,
    phone: “2044870470”, 
    ext: "" 
    picture: "" 
    tz: “Central Standard Time”,
    uofm: “Imperial”,
    radius: 25
    pri_radius: 100
    pref_radius: 25
    newsletter: true
}

The possible values for tz field are the names in the list found here.

State/Province List

Request Url End Point
http://www.truckdown.com/apiv2/region?key=api_key
Request Type:
GET
Scope Required:
None
Request Query String Parameters:
None
HTTPS Required:
No
Response:
JSON Array
Field:
cd
Description:
2 digit code for the State or Province.
Field:
n
Description:
The name of the State or Province
Field:
tn
Description:
If appplicable, the name of the tax applied within the given State or Province.
Field:
tr
Description:
The tax rate applied in the specified State or Province.
Field:
cc
Description:
The 2 digit code for the country.
Field:
cur
Description:
The currency used for the given State or Province (either USD or CAD)

Response Example:

                    
[
{
    cd: “MB”,
    n: “Manitoba”,
    tn: "GST"
    tr: 0.07
    cc: "CA"
    cur: "CAD"
},
{
    cd: “NC”,
    n: “North Carolina”,
    tn: ""
    tr: 0
    cc: "US"
    cur: "USD"
}
]

Request Url End Point: http://www.truckdown.com/apiv2/point?key=api_key

Request Type: GET

Scope Required: None

Request Query String Parameters:

Parameter:
region
Value:
The value for region can either be blank or a 2 digit code for the State or Province.
Description:
The 2 digit code for the state or province to search within.
Parameter:
term
Value:
This can be either the start of a city name, the whole city, a street address, or a set of coordinates in brackets. I.e. (lng,lat). TruckDown will search the internal city database first by matching the term with the start of any city name within the region specified. If no match is found, then TruckDown will perform an address search using Google® Geocoding unless a coordinate is provided.
Description:
The term to search for.

HTTPS Required: No

Response: JSON Array:

Field:
ct
Description:
City name (or street address).
Field:
rc
Description:
2 digit code for the State or Province.
Field:
cc
Description:
2 digit code for the Country.
Field:
po
Description:
A JSON Point Object representing a geo-coordinate

JSON Point:

Field:
Lat
Description:
Latitude
Field:
Lng
Description:
Longitude

Response Example:

                    
[
{
    ct: “Chicago”,
    rc: “IL”,
    cc: "US"
    po: {
        Lat: 41.85
        Lng: -87.65
    }
},
{
    ct: “Chicago Heights”,
    rc: “IL”,
    cc: "US"
    po: {
        Lat: 41.506111111
        Lng: -87.63555555
    }
}
]

Service and Dealer Network

Request Url End Point: http://www.truckdown.com/apiv2/service?key=api_key

Request Type: GET

Scope Required: None

Request Query String Parameters:

Parameter:
term
Value:
Optional: This can be either the start of a service name or a part of a service/dealer name or alternate description of the service/dealer.
Description:
The term to search for.

HTTPS Required: No

Response: JSON Array:

Field:
cd
Description:
2 - 5 alphanumeric code for the service or dealer network. Placeholders are included to seperate dealer networks from services. Any placeholder item has a blank value for cd.
Field:
n
Description:
Service or Dealer name.

Response Example:

                    
[
{
    cd: “TR”,
    n: “Truck Repair”,
},
{
    cd: “TOW”,
    n: “Heavy Duty Towing”,
}
]

Request Url End Point: http://www.truckdown.com/apiv2/search?key=api_key

Request Type: GET

Scope Required: None

Request Query String Parameters:

Parameter:
lng
Value:
Any value from -180 to 180. Only coordinates within Canada or the United States will return results.
Description:
The longitude coordinate of the search point.
Parameter:
lat
Value:
Any value from -90 to 90. Only coordinates within Canada or the United States will return results.
Description:
The latitude coordinate of the search point
Parameter:
service
Value:
Search codes used can be obtained through the Services or Delaer Network API call.
Description:
A space delimited list of service codes or dealer network codes to search for.
Parameter:
ams
Value:
Amenity names used can be obtained through the Services API.
Description:
A space delimited list of Amenity names used to filter the search results. (amenity names are returned as part of a search request).
Parameter:
page
Value:
Optional - This value should default to 1. To obtain more results of a given search, increment the page number by one.
Description:
The page of results to return.

HTTPS Required: No

Response: JSON Object:

Field:
id
Description:
A unique string representing the search request.
Field:
tot
Description:
The number of locations returned on the current search request.
Field:
max
Description:
The maximum number of locations available for the current search request. The can be used to determine the total number of pages available. The number of locations returned on the first page of results is dynamic but subsequent pages always return up to 10 locations.
Field:
ls
Description:
A JSON array of locations.
Field:
pro
Description:
A JSON object representing the featured promotion to display. This will return null if no featured promotion is available.
Field:
prCnt
Description:
The total number of additional promotions available for the given search results. If this number is greater than 0, then additional promotions are available.
Field:
ams
Description:
A JSON array of amenities available for the given search. This can be used to filter the results.
Field:
crat
Description:
A true/false value indicating if the current user can rate a location.
Field:
cerep
Description:
A true/false value indicating if the current user can close repairs in progress.
Field:
cent
Description:
A true/fale value indicating if the current user can edit notes.

NOTE: as per the TruckDown API Terms of Use Agreement, locations must be displayed in the order that they are returned (ls). Also, if a featured promotion is returned (pro), then the promotion (including both the title and the message) must be displayed to the end user and linked in some fashion to the location it is related to.

JSON Location:

Field:
_id
Description:
A unique string representing the location.
Field:
lid
Description:
A unique number representing the location. This number does not change over time and can be used on other API requests to retrieve notes, repairs, and/or ratings.
Field:
n
Description:
The name of the location.
Field:
wa
Description:
The locations website address (optional).
Field:
em
Description:
This will always be a null value and is not returned on the main search results.
Field:
ha
Description:
A true/false value specifying if the street address should be hidden. If this value is true, then the location either only provides mobile services or the location represents a centralized call-in service. The location’s street address should not be displayed to the end user.
Field:
nm
Description:
If ha is true, then this field specifies whether the location’s address is hidden as a result of being a mobile provider (false) or as a result of being a managed service (I.e. a call-in service) (true).
Field:
rv
Description:
A JSON object representing the locations Rating Value.
Field:
a
Description:
A JSON object representing the location’s address.
Field:
ba
Description:
This will always be a null value and is not returned on the main search results.
Field:
ns
Description:
This will always be a null value and is not returned on the main search results.
Field:
ld
Description:
A JSON object representing additional location details. This value can be null.
Field:
s
Description:
A JSON object representing the type of TruckDown location.
Field:
p
Description:
A JSON object representing the current user’s preference regarding the location. If no preference exists, this value can be null.
Field:
rs
Description:
This will always be a null value.
Field:
he
Description:
A true/false value. This will always be a false.
Field:
st
Description:
An integer value. This will always be a 0.

JSON Rating Value:

Field:
c
Description:
The total number of ratings that make up the value.
Field:
v
Description:
The aggregated rating value from 0 to 5 in 0.5 increments.

JSON Address:

Field:
l
Description:
The street address of the location. If the location has the ha field set to true, then this returns “Mobile Services”, or “Managed Service” if nm is also true.
Field:
l2
Description:
If applicable, the second line for the street address.
Field:
ct
Description:
The location’s City
Field:
rc
Description:
The location’s State or Province 2 digit code.
Field:
cc
Description:
The location’s Country 2 digit code
Field:
pc
Description:
The location’s Zip/Postal code. The value of this field is not set on search results.
Field:
po
Description:
A JSON object representing the location’s geo-coordinate
Field:
da
Description:
A string representation of the location’s city and region

JSON Point:

Field:
Lat
Description:
Latitude.
Field:
Lng
Description:
Longitude.
Field:
d
Description:
A string representation of the location’s distance from the search point in the measure unit for the currently logged in user. (i.e. 4.9 mi.)

JSON Location Details:

Field:
ti
Description:
A unique identifier for the location’s thumbnail logo. This thumbnail can be access at http://www.truckdown.com/file/thumb/[ti]
Field:
tl
Description:
A tag line (if applicable) to display with the location.

JSON Location Type:

Field:
pr
Description:
A true/false value indicating if the location is private to the currently logged in user.
Field:
pi
Description:
A string value indicating what Pin Icon used on TruckDown.com map displays. Possible values are “white”, “paleblue”, or “blue”
Field:
t
Description:
A string representation of the type of listing on TruckDown.com. Possible values are “preferred” (TruckDown Preferred), “LevelTwo” (TruckDown Elite), “LevelOne” (TruckDown Pro), or “Default” (TruckDown Stock).
Field:
t2
Description:
A string representation of the default type of listing on TruckDown.com. Does not include the “preferred” option.

JSON Preference:

Field:
locid
Description:
A unique string representing the location.
Field:
lid
Description:
A unique number representing the location. This number does not change over time and can be used on other API requests to retrieve notes, repairs, and/or ratings.
Field:
p
Description:
The priority for the preference, if applicable. Possible values are 1 (high priority) to 10 (lower priority).
Field:
ics
Description:
An array of strings representing what service categories the preference is related to (if any). Possible values are: “icon-serv-ir” – Repairs, “icon-serv-it” – Tires, “icon-serv-itow” – Towing, “icon-serv-imr” – Mobile Repairs, “icon-serv-imt” – Mobile Tires, and “icon-serv-aux” – Auxilliary.
Field:
svs
Description:
An array of strings representing what services the preference is related to (if any).
Field:
t
Description:
The type preference. 1 is Preferred, 2 is Do Not Use, and 0 is no preference.
Field:
rad
Description:
The radius to use when prioritizing this preferred location in search results (in miles)

JSON Amenity:

Field:
cd
Description:
The Amenity code.
Field:
n
Description:
The name of the Amenity.

JSON Promotion:

Field:
id
Description:
A unique identifier for the promotion.
Field:
lid
Description:
A unique identifier for the location to which this promotion is linked.
Field:
Title
Description:
The title of the promotion.
Field:
Message
Description:
The promotional message
Field:
ln
Description:
The name of the location to which this promotion is linked.
Field:
ld
Description:
A string representation of the location’s distance from the search point in the measure unit for the currently logged in user. (i.e. 4.9 mi.)

Phone Lookup

Request Url End Point: http://www.truckdown.com/apiv2/phone?key=api_key&id=_id

Request Type: GET

Scope Required: None

Request Query String Parameters: None

HTTPS Required: No

Response: JSON Array:

Field:
id
Description:
Unique string for the location.
Field:
l
Description:
The type of number. Possible values include Phone (office line), Mobile, After Hours, and Toll Free.
Field:
n
Description:
A ten digit string representing the phone number.

Response Example: 

                    
[
{
    id: “4d0c0ca5b73427072c98a7f3”,
    l: “Phone”,
    n: "5555555555"
},
{
    id: “4d0c0ca5b73427072c98a7f3”,
    l: “After Hours”,
    n: "5555555555"
}
]

Location Details

Request Url End Point: http://www.truckdown.com/apiv2/location?key=api_key&id=lid

Request Type: GET

Scope Required: None

Request Query String Parameters: none

HTTPS Required: No

Response: JSON Location Detail:

Field:
_id
Description:
A unique string representing the location.
Field:
d
Description:
A text description included with the location describing the services provided.
Field:
pr0
Description:
A JSON object representing a current promotion if applicable.
Field:
srvs
Description:
An Array of JSON objects listing all of the services that this location provides with amenities.
Field:
dlrs
Description:
An Array of strings specifying all of the Dealer Networks to which this location is a member.
Field:
imgs
Description:
An array of unique identifiers for photographs attached to the location. These images can be accessed at http://www.truckdown.com/file/photo/[id]
Field:
repc
Description:
The number of repairs attached to this location for the current user
Field:
ratc
Description:
The number of ratings attached to this location
Field:
nc
Description:
The number of notes attached to this location for the current user
Field:
crat
Description:
A true/false value indicating if the current user can rate a location.
Field:
cerep
Description:
A true/false value indicating if the current user can close repairs in progress.
Field:
cent
Description:
A true/false value indicating if the current user can edit notes.
Field:
hours
Description:
A JSON object representing the Hours of Operation data of this location.

NOTE: as per the TruckDown API Terms of Use Agreement, if a promotion is returned (pro), then the promotion (including both the title and the message) must be displayed to the end user and linked in some fashion to the location it is related to.

JSON Service:

Field:
cd
Description:
The code of the service.
Field:
n
Description:
The name of the service.
Field:
ams
Description:
An array of strings listing all of the amenity names included for the specified service at the given location

JSON Dealer Network:

Field:
cd
Description:
The code of the network.
Field:
n
Description:
The name of the network.

JSON Promotion:

Field:
id
Description:
A unique identifier for the promotion.
Field:
lid
Description:
A unique identifier for the location to which this promotion is linked.
Field:
Title
Description:
The title of the promotion.
Field:
Message
Description:
The promotional message
Field:
ln
Description:
The name of the location to which this promotion is linked.
Field:
ld
Description:
A string representation of the location’s distance from the search point in the measure unit for the currently logged in user. (i.e. 4.9 mi.)

JSON Hours of Operation:

Field:
id
Description:
A unique string representing the hours of operation for this location.
Field:
lid
Description:
A unique string representing this location.
Field:
rc
Description:
The location's State or Province 2 letter code.
Field:
cntry
Description:
The location's Country 2 letter code.
Field:
aid
Description:
A unique string representing the location's account
Field:
mh
Description:
A string representing how a location typically operates during major holidays. One of either "Regular Hours", "Closed" or "Limited Services"
Field:
hids
Description:
A JSON array of unique strings representing major holidays and an integer representing the major holiday condition hours, one of either -- 0 = Regular Hours, 1 = Closed, 2 = Limited Services.
Field:
t
Description:
The type of Hours of Operation for the location. One of either "SelectHours", "AlwaysOpen", "Closed", or "Unknown"
Field:
entries
Description:
If the Hours of Operation Type ("t") is "SelectHours", this field will contain an array of JSON Objects for each day of the week. See "JSON Hours of Operation Select Hours" section below.
Field:
tz
Description:
A string representing the time zone this location's hours are in.
Field:
ex
Description:
A JSON Array of JSON objects of Hour of Operation Exceptions that can override the existing Hours of Operations for a specified date. See "JSON Hours of Operation Exceptions" section below.

JSON Hours of Operation Select Hours

Field:
en
Description:
A true/false value indicating if the Hours of Operation for this day of the week are enabled.
Field:
ah24
Description:
A true/false value indicating if the location offers 24HR After Hours service outside of the regular hours.
Field:
entries
Description:
A JSON Array of JSON Objects representing a time block of hours for the day and the time block's type. Each time block entry has the following fields:

JSON Hours of Operation Select Hours Entries

Field:
st
Description:
A string in a 12H format representing the time block's start time.
Field:
et
Description:
A string in a 12H format representing the time block's end time.
Field:
t
Description:
A string representing the time block's type - One of either, "Open", "AfterHours", or "Closed".

JSON Hours of Operation Exceptions:

Field:
id
Description:
A unique string representing the Hours of Operation Exception.
Field:
n
Description:
A string name value for the exception.
Field:
lids
Description:
A JSON Array of strings representing the unique location ids that this exception applies to.
Field:
exd
Description:
The date of the exception.
Field:
en
Description:
A true/false value indicating if the exception is enabled.
Field:
t
Description:
The type value for the Hours of Operation Exception, one of either "SelectHours", "AlwaysOpen", "Closed", or "Unknown".
Field:
data
Description:
If the Hours of Operation Type is SelectHours, this field will contain an object with the data for the exception. See "JSON Hours of Operation Select Hours" section above.

Search Promotions

If, after running a Location Search, the response object has a value greater than 0 for the proCnt field, then you can submit this request to get additional serach promotions related to the search results. Please note, if you submit this request, then you must show the results to your end users as per the Terms and Conditions.

Request Url End Point: http://www.truckdown.com/apiv2/deals?key=api_key&id=search_id

Request Type: GET

Scope Required: None

Request Query String Parameters: None

HTTPS Required: No

Response: JSON Object:

Field:
tot
Description:
The total number of Search Promotions returned for the request
Field:
p
Description:
An array of JSON objects representing the list of promotions to display.

JSON Promotion:

Field:
id
Description:
A unique identifier for the promotion.
Field:
lid
Description:
A unique identifier for the location to which this promotion is linked.
Field:
Title
Description:
The title of the promotion.
Field:
Message
Description:
The promotional message
Field:
ln
Description:
The name of the location to which this promotion is linked.
Field:
ld
Description:
A string representation of the location’s distance from the search point in the measure unit for the currently logged in user. (i.e. 4.9 mi.)

Personal Notes

Retrieving Notes

Request Url End Point: http://www.truckdown.com/apiv2/notes?key=api_key

Request Type: GET

Scope Required: Search

Request Query String Parameters:

Parameter:
lid
Value:
A numeric value representing the location.
Description:
The unique identifier for the location.

HTTPS Required: No

Response: JSON Object:

Field:
tot
Description:
The total number of notes returned.
Field:
max
Description:
The maximum number of notes available (this can be used to calculate the total number of pages).
Field:
pns
Description:
A JSON array of notes.

JSON Note:

Field:
_id
Description:
A unique identifier for the note. Leave blank if adding a note.
Field:
type
Description:
The type of note to enter. Submit "update_listing" to enter an update listing request otherwise (for a personal note) leave blank.
Field:
lid
Description:
A unique number for the location to add the note to.
Field:
name
Description:
The name of the user that entered the note - only required if not logged in and adding an update listing request.
Field:
email
Description:
The email address of the user that entered the note - only required if not logged in and adding an update listing request.
Field:
phone
Description:
The phone number of the user that entered the note - only required if not logged in and adding an update listing request.
Field:
subject
Description:
A subject for the note.
Field:
msg
Description:
The note entered.

Adding or Editing a Note

Request Url End Point: http://www.truckdown.com/apiv2/notes?key=api_key

Request Type: POST

Scope Required: Search

Request Query String Parameters: None

POST Parameters:

Field:
nid
Value:
The unique identifier for the note to edit. If adding a new note, this can be left blank.
Description:
The unique identifier for the note.
Field:
lid
Value:
The numeric identifier for the location (as returned in the search results)
Description:
The unique identifier for the location.
Field:
comment
Description:
The Note to either add or the updated note for the edit.

HTTPS Required: No

Response: JSON Object:

Field:
ok
Description:
A true/false value indicating of the operation was successful.
Field:
cd
Description:
If not successful, an error code.
Field:
msg
Description:
If not successful, an error message.

Deleting a Note

Request Url End Point: http://www.truckdown.com/apiv2/notes?id=api_key&id=note_id

Request Type: DELETE

Scope Required: Search

Request Query String Parameters: None

HTTPS Required: No

Response: JSON Object:

Field:
ok
Description:
A true/false value indicating of the operation was successfull.
Field:
cd
Description:
If not successful, an error code.
Field:
msg
Description:
If not successful, an error message.

Repairs

Retrieving Repairs

Request Url End Point: http://www.truckdown.com/api/repairs?key=api_key

Request Type: GET

Scope Required: Search

Request Query String Parameters:

Field:
lid
Value:
A numeric value representing the location.
Description:
The unique identifier for the location.

HTTPS Required: No

Response: JSON Object:

Field:
tot
Description:
The total number of repairs returned.
Field:
max
Description:
The maximum number of repairs available (this can be used to calculate the total number of pages).
Field:
rps
Description:
A JSON array of repairs.

JSON Repair:

Field:
_id
Description:
A unique identifier for the repair.
Field:
lid
Description:
The location’s unique identifier.
Field:
uid
Description:
A unique identifier for the user that entered the repair.
Field:
n
Description:
The name of the repair.
Field:
d
Description:
A string representation of the date of the repair in the users local time zone.
Field:
t
Description:
The truck unit attached to the repair.
Field:
s
Description:
The status of the repair. Possible values include “Open” (i.e. Repair in Progress) or “Closed”
Field:
est
Description:
A string representation of the total estimated cost of the repair. If no estimate was entered, then this field returns “N/A”
Field:
est_t
Description:
A string representation of the total estimated response time (hours) for the repair. If no estimate was entered, then this field returns “”
Field:
act
Description:
A string representation of the total actual cost of the repair. If no estimate was entered, then this field returns “N/A”
Field:
act_t
Description:
A string representation of the total actual response time (hours) for the repair. If no estimate was entered, then this field returns “”
Field:
c
Description:
The comment entered on the repair.
Field:
ce
Description:
A true/false value indicating if the current user has the rights to edit the repair.

Getting Repair Details

Request Url End Point: http://www.truckdown.com/apiv2/repairs?key=api_key

Request Type: GET

Scope Required: Search

Request Query String Parameters:

Field:
rid
Value:
A string.
Description:
The unique identifier for the repair.
Field:
lid
Value:
A numeric value representing the location.
Description:
The unique identifier for the location.

HTTPS Required: No

Response: JSON Object:

Field:
rid
Description:
A unique identifier for the repair.
Field:
lid
Description:
The location’s unique identifier.
Field:
n
Description:
The name of the repair.
Field:
t
Description:
The truck unit attached to the repair.
Field:
c
Description:
The comment entered on the repair.
Field:
close
Description:
A true/false value specifying if the repair is closed.
Field:
est_t
Description:
The total estimated cost for the repair
Field:
est_h
Description:
The total estimated labor hours for the repair (if applicable)
Field:
est_r
Description:
The estimated labor rate on the repair (if applicable)
Field:
est_p
Description:
The total estimated parts cost on the repair (if applicable)
Field:
est_l
Description:
The total estimated labor costs on the repair (if applicable)
Field:
est_ti
Description:
The estimated response time (hours) for the repair (if applicable)
Field:
act_t
Description:
The total actual cost for the repair
Field:
act_h
Description:
The total actual labor hours for the repair (if applicable)
Field:
act_r
Description:
The actual labor rate on the repair (if applicable)
Field:
act_p
Description:
The total actual parts cost on the repair (if applicable)
Field:
act_l
Description:
The total actual labor costs on the repair (if applicable)
Field:
act_ti
Description:
The actual response time (hours) for the repair (if applicable)

Closing or Opening a Repair

Request Url End Point: http://www.truckdown.com/apiv2/repairs?key=api_key

Request Type: PUT

Scope Required: Search

Request Query String Parameters:

Field:
id
Value:
The unique identifier for the repair.
Description:
The unique identifier for the repair.

HTTPS Required: No

Response: JSON Object:

Field:
ok
Description:
A true/false value indicating if the operation was successfull.
Field:
cd
Description:
If not successfull, an error code.
Field:
msg
Description:
If not successfull, an error message.

Note: if the repair submitted is currently in progress then it will be switched to closed. If the repair is closed, then is will be switched to Repair in Progress.

Deleting a Repair

Request Url End Point: http://www.truckdown.com/apiv2/repairs?key=api_key

Request Type: DELETE

Scope Required: Search

Request Query String Parameters:

Field:
id
Value:
The unique identifier for the repair.
Description:
The unique identifier for the repair.

HTTPS Required: No

Response: JSON Object:

Field:
ok
Description:
A true/false value indicating if the operation was successfull.
Field:
cd
Description:
If not successfull, an error code.
Field:
msg
Description:
If not successfull, an error message.

Starting or Editing a Repair

Request Url End Point: http://www.truckdown.com/apiv2/repairs?key=api_key

Request Type: POST

Scope Required: Search

POST Parameters:

Field:
rid
Value:
A string. If starting a new repair, this should be left blank.
Description:
The unique identifier for the repair.
Field:
lid
Value:
A numeric value representing the location.
Description:
The unique identifier for the location.
Field:
n
Description:
Optional - The name of the repair.
Field:
t
Value:
If the truck unit # does not exist, it will be created automatically.
Description:
Optional - The truck unit # to assign to the repair.
Field:
close
Value:
If true, then the repair will be closed when created.
Description:
true/false value.
Field:
est_t
Value:
The total estimated cost for the repair.
Description:
Optional – number. If est_p or est_l is provided, then this value gets calculated based on the more detailed values.
Field:
est_h
Value:
The total estimated number of labor hours for the repair.
Description:
Optional – number.
Field:
est_r
Value:
The total estimated labor rate for the repair.
Description:
Optional – number.
Field:
est_p
Value:
The total estimated parts cost for the repair.
Description:
Optional – number.
Field:
est_l
Value:
The total estimated labor cost for the repair.
Description:
Optional – number. If est_h and est_r is provided, then this value gets calculated based on the more detailed values.
Field:
est_ti
Value:
The estimated response time in hours for the repair.
Description:
Optional – number.
Field:
act_t
Value:
The total actual cost for the repair.
Description:
Optional – number. If act_p or act_l is provided, then this value gets calculated based on the more detailed values.
Field:
act_h
Value:
The total actual number of labor hours for the repair.
Description:
Optional – number.
Field:
act_r
Value:
The total actual labor rate for the repair.
Description:
Optional – number.
Field:
act_p
Value:
The total actual parts cost for the repair.
Description:
Optional – number.
Field:
act_l
Value:
The total actual labor cost for the repair.
Description:
Optional – number. If act_h and act_r is provided, then this value gets calculated based on the more detailed values.
Field:
act_ti
Value:
The actual response time in hours for the repair.
Description:
Optional – number.
Field:
c
Value:
The comment to add to the repair.
Description:
Optional

HTTPS Required: No

Response: JSON Object:

Field:
ok
Description:
A true/false value indicating if the operation was successfull.
Field:
cd
Description:
If not successfull, an error code.
Field:
msg
Description:
If not successfull, an error message.

Ratings

Retrieving Ratings for a Given Location

Request Url End Point: http://www.truckdown.com/apiv2/ratings?key=api_key

Request Type: GET

Scope Required: Search

Request Query String Parameters:

Field:
lid
Value:
A numeric value representing the location.
Description:
The unique identifier for the location.

HTTPS Required: No

Response: JSON Object:

Field:
tot
Description:
The total number of ratings returned.
Field:
max
Description:
The maximum number of ratings available (this can be used to calculate the total number of pages).
Field:
rts
Description:
A JSON array of ratings.
Field:
req_con
Description:
A true/false value indicating if a request for contact has already been submitted.
Field:
dis_rat
Description:
A true/false value indicating if a rating dispute has already been submitted.

JSON Rating:

Field:
_id
Description:
A unique identifier for the rating.
Field:
lid
Description:
The location’s unique identifier.
Field:
uid
Description:
A unique identifier for the user that entered the rating.
Field:
n
Description:
The name of the user that entered the rating.
Field:
d
Description:
A string representation of the date that the rating was entered, in the current user’s time zone.
Field:
c
Description:
The comment entered with the rating.
Field:
s
Description:
The status of the rating. Possible values include “Archived” (i.e. Historical rating that is not counted in the rating value on the location), “Internal” (i.e. rating that can be accessed only because the current user or account entered it), “Shared” (i.e. a rating that has been shared with the location), or “Active” (i.e. a rating that was not shared with the location but is counted in the location rating value).
Field:
v
Description:
The value of the rating from 0.5 to 5.0 in 0.5 increments.
Field:
cs
Description:
An array of strings representing the categories entered for the rating.

Rating a Location

Request Url End Point: http://www.truckdown.com/apiv2/ratings?key=api_key

Request Type: POST

Scope Required: Search

POST Parameters:

Field:
id
Value:
This can be blank for adding a new rating.
Description:
The unique identifier for the rating to modify (if applicable).
Field:
lid
Value:
A numeric value representing the location.
Description:
The unique identifier for the location.
Field:
val
Value:
A value from 0.5 to 5.0 in 0.5 increments.
Description:
The value of the rating submitted.
Field:
cats
Value:
Possible values include: “Price”, “Customer Service”, “Technical Service”, “Timeliness”
Description:
A space delimited list of categories associated with the rating.
Field:
ispub
Value:
true/false value
Description:
If true, the current users contact info along with the rating details will be shared with the location being rated.
Field:
closeRep
Value:
If left blank, then no repair will be closed. If closeRep is set to “ALL”, then all open repairs for the provided location will be closed.
Description:
The unique identifier for the repair to close (if any).
Field:
updatepref
Value:
true/false value
Description:
If true, the system will update the network preference option for the given location. Only applicable if user has necessary rights to manage network preferences.
Field:
pref
Value:
true/false value
Description:
If true, then the location will be added to the user’s Preferred Vendor list (provided dnu is false). Only applicable if user has necessary rights to manage repairs and updatepref is true.
Field:
dnu
Value:
true/false value
Description:
If true, then the location will be added to the user’s Do Not Use list (overrides the pref value if true). Only applicable if user has necessary rights to manage repairs and updatepref is true.
Field:
priority
Value:
Optional – number from 1 to 10.
Description:
Optional - Ignored if updatepref is false.
Field:
svs
Value:
Optional - A space delimited list of Service Codes.
Description:
Optional - Ignored if updatepref is false.
Field:
rad
Value:
Possible values are: 5, 10, 15, 20, 25, 50, or 100. (Specifies miles). If no value is entered, then the user preference option is used.
Description:
Optional - Ignored if updatepref is false.

HTTPS Required: No

Response: JSON Object:

Field:
ok
Description:
A true/false value indicating if the operation was successful.
Field:
cd
Description:
If not successful, an error code.
Field:
msg
Description:
If not successful, an error message.

Preferred or Do Not Use Vendor Lists

Synchronizing Service Networks

The TruckDown API provides a mechanism for your application to synchronize your user’s preferred and do not use vendor lists with TruckDown’s core system. When submitting a request to synchronize the lists, your application must send the date of the last time your application synchronized, the page you want returned (first request would be page 1), and the number of records you want returned per page. The result you will get will include the total number of records to process, the current date of the current sync (from the server’s clock), and the list of preferred or do not use vendors in the current page.

You can then use the date returned to loop through each page of results to synchronize the full list. The preferred vendors list returned returns only changes made since the last synchronization.

Request Url End Point: http://www.truckdown.com/apiv2/preferences?key=api_key

Request Type: GET

Scope Required: Search

Request Query String Parameters:

Field:
lastSync
Value:
If this is the first time a synchronization has been done for the user, then you can submit 1990-01-01T00:00:00.0Z. Dates can be sent and are received in ISO8601 format.
Description:
The date of the last synchronization. The results will not return any location preferences that have been modified before or on this date and time.
Field:
currSync
Value:
If you are returning the first page of results, then this value can be left blank but for subsequent pages, then this value should be the “sDate” field returned in the first request. This field is required to ensure that the list returned across pages remains consistent. Dates can be sent and are received in ISO8601 format.
Description:
The date of the current synchronization. The results will not return any location preferences that have been modified after this date and time.
Field:
pg
Value:
A number, should be set to 1 for the first request.
Description:
The page number to return.
Field:
pgcnt
Value:
A positive number. If you enter 0 or a number less than 0, then the value defaults to 25. This value must be consistent across requests for multiple pages.
Description:
The number of records to return for each “page” of results.

Example URL:

Page One Request:

http://www.truckdown.com/apiv2/preferences?lastSync=1990-01-01T00%3a00%3a00.0Z&currSync=&pg=1&pgcnt=25

Page Two Request:

http://www.truckdown.com/apiv2/preferences?lastSync=1990-01-01T00%3a00%3a00.0Z&currSync=2013-09-24T13%3a50%3a01.3591658Z&pg=2&pgcnt=25

HTTPS Required: No

Response: JSON Object:

Field:
cnt
Description:
The number of location preferences returned in the current request.
Field:
max
Description:
The total number of location preferences available for the current sync. Taking the ceiling of max / pgcnt, you can calculate the total number of pages available.
Field:
pg
Description:
The current page number.
Field:
pgcnt
Description:
The maximum number of records returned per page of results.
Field:
sDate
Description:
The date of the current sync. This can be used for requests for subsequent pages. Dates are received in ISO8601 format.
Field:
prefs
Description:
An array of Location Preferences. Each location preference is it’s own JSON object as defined below.

JSON Location Preference:

Field:
lid
Description:
The Location Id – an integer unique to the location.
Field:
locid
Description:
The unique string associated with the location.
Field:
p
Description:
A number specifying the priority, from 1 (most important) to 10 (not as important). This value can be blank. A blank priority is the least important. This is only applicable to Preferred Locations.
Field:
ics
Description:
An array of strings representing what service categories the preference is related to (if any). Possible values are: “icon-serv-ir” – Repairs, “icon-serv-it” – Tires, “icon-serv-itow” – Towing, “icon-serv-imr” – Mobile Repairs, “icon-serv-imt” – Mobile Tires, and “icon-serv-aux” – Auxilliary.
Field:
svs
Description:
An array of strings representing what services the preference is related to (if any).
Field:
t
Description:
The type preference. 1 is Preferred, 2 is Do Not Use, and 0 is no preference.
Field:
rad
Description:
The radius to use when prioritizing this preferred location in search results (in miles)

Retrieving Service Network Data For Location

Request Url End Point: http://www.truckdown.com/apiv2/preferences

Request Type: GET

Scope Required: Search

Request Query String Parameters:

Field:
lid
Value:
A number
Description:
The Location Id of the location you are requesting preference data for.

Example URL:

http://www.truckdown.com/apiv2/preferences?lid=35789

HTTPS Required: No

Response: JSON Object:

Field:
lid
Description:
The Location Id – an integer unique to the location.
Field:
locid
Description:
The unique string associated with the location.
Field:
p
Description:
A number specifying the priority, from 1 (most important) to 10 (not as important). This value can be blank. A blank priority is the least important. This is only applicable to Preferred Locations.
Field:
ics
Description:
An array of strings representing what service categories the preference is related to (if any). Possible values are: “icon-serv-ir” – Repairs, “icon-serv-it” – Tires, “icon-serv-itow” – Towing, “icon-serv-imr” – Mobile Repairs, “icon-serv-imt” – Mobile Tires, and “icon-serv-aux” – Auxilliary.
Field:
svs
Description:
An array of strings representing what services the preference is related to (if any).
Field:
t
Description:
The type preference. 1 is Preferred, 2 is Do Not Use, and 0 is no preference.
Field:
rad
Description:
The radius to use when prioritizing this preferred location in search results (in miles)

Submitting Service Network Data For Location

Request Url End Point: http://www.truckdown.com/apiv2/preferences

Request Type: POST

Scope Required: Search

POST Parameters:

Field:
lid
Description:
The Location Id – an integer unique to the location.
Field:
p
Description:
Optional - A number specifying the priority, from 1 (most important) to 10 (not as important). This value can be blank. A blank priority is the least important. This is only applicable to Preferred Locations.
Field:
ics
Description:
Optional - An array of strings representing what service categories the preference is related to (if any). Possible values are: “icon-serv-ir” – Repairs, “icon-serv-it” – Tires, “icon-serv-itow” – Towing, “icon-serv-imr” – Mobile Repairs, “icon-serv-imt” – Mobile Tires, and “icon-serv-aux” – Auxilliary.
Field:
svs
Description:
Optional - An array of strings representing what services the preference is related to (if any).
Field:
t
Description:
The type preference. 1 is Preferred, 2 is Do Not Use, and 0 is no preference.
Field:
rad
Description:
Optional - The radius to use when prioritizing this preferred location in search results (in miles)

HTTPS Required: No

Response: JSON Object:

If the location preference is added successfully, then the same preference data submitted is returned in the response:

Field:
lid
Description:
The Location Id – an integer unique to the location.
Field:
locid
Description:
The unique string associated with the location.
Field:
p
Description:
A number specifying the priority, from 1 (most important) to 10 (not as important). This value can be blank. A blank priority is the least important. This is only applicable to Preferred Locations.
Field:
ics
Description:
An array of strings representing what service categories the preference is related to (if any). Possible values are: “icon-serv-ir” – Repairs, “icon-serv-it” – Tires, “icon-serv-itow” – Towing, “icon-serv-imr” – Mobile Repairs, “icon-serv-imt” – Mobile Tires, and “icon-serv-aux” – Auxilliary.
Field:
svs
Description:
An array of strings representing what services the preference is related to (if any).
Field:
t
Description:
The type preference. 1 is Preferred, 2 is Do Not Use, and 0 is no preference.
Field:
rad
Description:
The radius to use when prioritizing this preferred location in search results (in miles)