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"
}
]
City Search
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”,
}
]
Location Search
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.
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)