SoilDirect.com : SoilDirect API Documentation for version 1.1

Apply to use API

If you are interested in apply to use the Soil Direct API, fill out the form below

Introduction

Soil Direct has a rich API that allows suppliers and developers to display and sell products on their own website and/or application.

In order to use the Soil Direct API, you must be a registered user of the Soil Direct Network.

This is Soil Direct's API Documentation, version 1.1.

This documentation is compatible with the following API versions: 3.0.1, 3.0.2.

Authentication

All API requests are logged and monitored for security purposes and abuse.

All API requests must be HTTPS requests. All HTTP requests will fail.

Every API request must have a valid API key and request token*.

API Keys are unique and are issued to account holders once they have been approved

Request tokens are created at the start of each session and must be established for 'each' user. The instructions on how to generate a token, refer to the get_token method.

Please keep your API key secret. If you suspect it was compromised, let us know immediately, and we'll issue a new one.

* get_token method does NOT require a token

Response Format

All API responses are returned in JSON. For more information on JSON, please reference the official website.

Methods

get_token

Use this method to get a token for a shopping session. This token will be required for all other API requests in the shopping session.

Tokens expire after one day. If your token expires, use this method to get a new one.

Parameter	Values	Required?	Description
a	get_token	Yes	Method requested
api_key	variable	Yes	Supplied API key

Formatted call

https://www.soildirect.com/api/?a=get_token&api_key=[API_KEY]

Formatted response (click inside code to reveal entire response)

{
	"token":"sample",
	"success":1,
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_token",
		"tracking":"sample",
		"cart_id":null
	}
}

Jump to Top

get_cats

Use this method to find out what product categories are available for delivery to a specific address.

Parameter	Values	Required?	Description
a	get_cats	Yes	Method requested
address	variable	Yes	Requested delivery address
city	variable	Yes	Requested delivery city
state	variable	Yes	Requested delivery state
zipcode	variable	Yes	Requested delivery zip code
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_cats&address=[ADDRESS]&city=[CITY]&state=[STATE]&zipcode=[ZIPCODE]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your request returned 6 categories",
	"num_results":6,
	"results":[{
		"category_seo":"amended-topsoil",
		"category_desc":"Amended Topsoil",
		"image_path":"https:\/\/www.soildirect.com\/images\/c2\/amended-topsoil.jpg"
	},{
		"category_seo":"base",
		"category_desc":"Base",
		"image_path":"https:\/\/www.soildirect.com\/images\/c20120712200226.jpg"
	},{
		"category_seo":"compost",
		"category_desc":"Compost",
		"image_path":"https:\/\/www.soildirect.com\/images\/c2\/c20120712200357.jpg"
	},{
		"category_seo":"decomposed-granite",
		"category_desc":"Decomposed Granite",
		"image_path":"https:\/\/www.soildirect.com\/images\/c2\/c20120620151208.jpg"
	},{
		"category_seo":"dirt",
		"category_desc":"Dirt",
		"image_path":"https:\/\/www.soildirect.com\/images\/c2\/c20120617144604.jpg"
	},{
		"category_seo":"gravel-decorative-rock",
		"category_desc":"Gravel\/ Decorative Rock ",
		"image_path":"https:\/\/www.soildirect.com\/images\/c2\/c20120617145209.jpg"
	}],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_cats",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_subcats

Use this method to find out what product subcategories are available for delivery to a specific address and category.

Parameter	Values	Required?	Description
a	get_subcats	Yes	Method requested
category	variable	Yes	Category key of requested product
address	variable	Yes	Requested delivery address
city	variable	Yes	Requested delivery city
state	variable	Yes	Requested delivery state
zipcode	variable	Yes	Requested delivery zip code
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_subcats&category=[CATEGORY_KEY]&address=[ADDRESS]&city=[CITY]&state=[STATE]&zipcode=[ZIPCODE]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your request returned 4 subcategories",
	"num_results":4,
	"results":[{
		"measurement_type_desc":"cubic yards",
		"subcategory_seo":"flower-vegetable-mix",
		"subcategory_desc":"Flower Vegetable Mix",
		"long_desc":"The flower vegetable mix is composed of 30% screened soil and  70% nitro compost. It makes beautiful flowers and delicious vegetables.",
		"category_desc":"Amended Topsoil",
		"category_seo":"amended-topsoil",
		"image_path":"https:\/\/www.soildirect.com\/images\/size00\/organic-soil-for-vegetable-gardens.jpg",
		"thumb_path":"https:\/\/www.soildirect.com\/images\/size02\/organic-soil-for-vegetable-gardens.jpg"
	},{
		"measurement_type_desc":"cubic yards",
		"subcategory_seo":"topsoil-30-70",
		"subcategory_desc":"Topsoil 30\/70",
		"long_desc":"The topsoil 30\/70 is 30% screened soil and 70% compost. It makes great planting soil because it is a well draining light weight soil.",
		"category_desc":"Amended Topsoil",
		"category_seo":"amended-topsoil",
		"image_path":"https:\/\/www.soildirect.com\/images\/size00\/p174-s43-04-20100125-113303.jpg",
		"thumb_path":"https:\/\/www.soildirect.com\/images\/size00\/p174-s43-02-20100125-113303.jpg"
	},{
		"measurement_type_desc":"cubic yards",
		"subcategory_seo":"topsoil-50-50",
		"subcategory_desc":"Topsoil 50\/50",
		"long_desc":"The topsoil 50\/50 is a mix of 50% screened soil and 50% compost. This product is mostly used for planting sod or seed for depths up to 6 inches.",
		"category_desc":"Amended Topsoil",
		"category_seo":"amended-topsoil",
		"image_path":"https:\/\/www.soildirect.com\/images\/size00\/p80-43-02-20081021-120412.jpg",
		"thumb_path":"https:\/\/www.soildirect.com\/images\/size00\/p80-43-02-20081021-120412.jpg"
	},{
		"measurement_type_desc":"cubic yards",
		"subcategory_seo":"topsoil-70-30",
		"subcategory_desc":"Topsoil 70\/30",
		"long_desc":"The topsoil 70\/30 Mix is 70% screened soil and 30% compost. This material is used for sod or seed preparation for depths between 6 inches and 12 inches.",
		"category_desc":"Amended Topsoil",
		"category_seo":"amended-topsoil",
		"image_path":"https:\/\/www.soildirect.com\/images\/noproductimage-large.jpg",
		"thumb_path":"https:\/\/www.soildirect.com\/images\/noproductimage.jpg"
	}],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_subcats",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_calculate

Call this function right before displaying an "Enter Quantity" interface. It returns data elements for that interface.

Parameter	Values	Required?	Description
a	get_calculate	Yes	Method requested
subcategory	variable	Yes	Subcategory key of requested product
address	variable	Yes	Requested delivery address
city	variable	Yes	Requested delivery city
state	variable	Yes	Requested delivery state
zipcode	variable	Yes	Requested delivery zip code
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_calculate&subcategory=[SUBCATEGORY_KEY]&address=[ADDRESS]&city=[CITY]&state=[STATE]&zipcode=[ZIP_CODE]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your requested subcategory was found",
	"results":{
		"category_desc":"Compost",
		"category_seo":"compost",
		"subcategory_desc":"Compost",
		"subcategory_seo":"compost",
		"image_path":"https:\/\/www.soildirect.com\/images\/c2\/c20120712200357.jpg"
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_calculate",
		"subcategory_seo":"topsoil-30-70",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_pricing

Use this method to get pricing on a product based on address, quantity, and subcategory type

Parameter	Values	Required?	Description
a	get_pricing	Yes	Method requested
quantity	variable	Yes	Quantity of material requested
subcategory	variable	Yes	Subcategory key of requested product
address	variable	Yes	Requested delivery address
city	variable	Yes	Requested delivery city
state	variable	Yes	Requested delivery state
zipcode	variable	Yes	Requested delivery zip code
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_pricing&quantity=[QUANTITY]&subcategory=[SUBCATEGORY_KEY]&address=[ADDRESS]&city=[CITY]&state=[STATE]&zipcode=[ZIP_CODE]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your request returned 1 location price",
	"results":{
		"location":{
			"alias":"Location SSD",
			"name":"Soil & Sod Depot",
			"extension":"701",
			"delivery_days_str":"M-F,Sa,Su*"
		},
		"product":{
			"category_desc":"Decomposed Granite",
			"category_seo":"decomposed-granite",
			"subcategory_desc":"Stabilized Decomposed Granite",
			"subcategory_seo":"stabalized-decomposed-granite",
			"minimum_order":"2",
			"sample_price":"10.00",
			"offer_sample":"1",
			"long_desc":"Stabilized Decomposed Granite",
			"quantity":20,
			"image_path":"https:\/\/www.soildirect.com\/images\/size00\/p119-s43-03-20081222-131126.jpg",
			"thumb_path":"https:\/\/www.soildirect.com\/images\/size00\/p119-s43-02-20081222-131126.jpg",
			"overall_desc":"20 cubic yards of Stabilized Decomposed Granite",
			"sample_desc":"Sample of Stabilized Decomposed Granite",
			"grand_total":"1,601.43",
			"product_hash":"sample"
		},
		"truck":{
			"truck_type_desc":"Super 10 Dump Truck"
		}
	},
	"cart":{
		"grand_total":0,
		"num_items":0,
		"customer":[],
		"address":[],
		"delivery":[],
		"logged_in":0,
		"tax_exempt":0,
		"contractor":0,
		"items":[]
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_pricing",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

add_to_cart

Use this method to add a product to a session's shopping cart

Parameter	Values	Required?	Description
a	get_cart	Yes	Method requested
product_hash	variable	Yes	Product hash from get_pricing call
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=add_to_cart&product_hash=[PRODUCT_HASH]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"The item was added to your shopping cart",
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"add_to_cart",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

remove_from_cart

Use this method to remove an item from the current shopping cart.

Use the get_cart method to determine what item id is mapped to each item in the shopping cart.

Parameter	Values	Required?	Description
a	get_cart	Yes	Method requested
item_id	variable	Yes	Item Id of cart item to be removed
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=remove_from_cart&item_id=[CART_ITEM_ID]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"The item was removed from your shopping cart",
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"remove_from_cart",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_cart

Use this method to retrieve the shopping cart for the current shopping session.

Parameter	Values	Required?	Description
a	get_cart	Yes	Method requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_cart&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Here is your shopping cart",
	"results":{
		"items":[{
			"cart_item_id":1,
			"quantity":"20",
			"is_sample":"0",
			"grand_total":"688.98",
			"caption":"compost",
			"subcategory_desc":"Compost",
			"subcategory_seo":"compost",
			"category_desc":"Compost",
			"category_seo":"compost",
			"product_desc":"20 cubic yards of Compost",
			"thumbnail_path":"https:\/\/www.soildirect.com\/images\/size02\/decomposed-vegetation-compost.jpg",
			"image_path":"https:\/\/www.soildirect.com\/images\/size01\/decomposed-vegetation-compost.jpg",
			"truck_desc":"Super 10 Dump Truck"
		},{
			"cart_item_id":2,
			"quantity":"1",
			"is_sample":"1",
			"grand_total":"10.00",
			"caption":"Flower Vegetable Mix",
			"subcategory_desc":"Flower Vegetable Mix",
			"subcategory_seo":"flower-vegetable-mix",
			"category_desc":"Amended Topsoil",
			"category_seo":"amended-topsoil",
			"product_desc":"Sample of Flower Vegetable Mix",
			"thumbnail_path":"https:\/\/www.soildirect.com\/images\/size02\/organic-soil-for-vegetable-gardens.jpg",
			"image_path":"https:\/\/www.soildirect.com\/images\/size01\/organic-soil-for-vegetable-gardens.jpg",
			"truck_desc":"N\/A"
		}],
		"grand_total":"698.98",
		"num_items":2,
		"delivery_str":"Sun - Sat",
		"first_name":null,
		"last_name":null,
		"phone_pri":null,
		"phone_alt":null,
		"email":null,
		"address":"6701 Eton Ave",
		"city":"Woodland Hills",
		"state":"CA",
		"zipcode":"91303",
		"tracking":"1408080544321",
		"display_date":"Mon Nov 3rd, 2014",
		"instructions":"",
		"logged_in":0,
		"tax_exempt":0,
		"contractor":0
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_cart",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

update_cart

Use this method to update miscellaneous delivery information and store in the session shopping cart. This must be called before calling place_order.

Parameter	Values	Required?	Description
a	update_cart	Yes	Method requested
address	variable	Yes	Delivery address
city	variable	Yes	Delivery city
state	variable	Yes	Delivery state
zipcode	variable	Yes	Delivery zipcode
first_name	variable	Yes	First name of customer
last_name	variable	Yes	Last name of customer
email	variable	Yes	Email address of customer
phone_pri	variable	Yes	Primary phone number of customer
phone_alt	variable	Optional	Alternate phone number of customer
delivery_date	variable	Yes	Requested date of delivery in the yyyy-mm-dd format
delivery_time	7:00am - 9:00am, 9:00am - 11:00am, 11:00am - 1:00pm, 1:00pm - 3:00pm, 3:00pm - 5:00pm	Yes	Requested time of delivery
location_type	home, commercial	Yes	Type of location for delivery address
instructions	variable	Optional	Customer requested delivery instructions
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=update_cart&address=[ADDRESS]&city=[CITY]&state=[STATE]&zipcode=[ZIP_CODE]&first_name=[FIRST_NAME]&last_name=[LAST_NAME]&email=[EMAIL]&phone_pri=[PRIMARY_PHONE]&phone_alt=[ALTERNATE_PHONE]&delivery_date=[DELIVERY_DATE]&delivery_time=[DELIVERY_TIME]&location_type=[LOCATION_TYPE]&instructions=[SPECIAL_INSTRUCTIONS]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your shopping cart was updated",
	"results":{
		"items":[{
			"cart_item_id":0,
			"quantity":"20",
			"is_sample":false,
			"grand_total":"793.38",
			"subcategory_desc":"Decomposed Granite",
			"subcategory_seo":"decomposed-granite",
			"category_desc":"Decomposed Granite",
			"category_seo":"decomposed-granite",
			"product_desc":"20 cubic yards of Decomposed Granite",
			"thumbnail_path":"https:\/\/www.soildirect.com\/images\/size00\/p21-43-02-20081021-120116.jpg",
			"image_path":"https:\/\/www.soildirect.com\/images\/size00\/p21-43-04-20081021-120116.jpg",
			"days_delivery_str":"M-F,Sa,Su*",
			"truck_desc":"Super 10 Dump Truck"
		}],
		"grand_total":"793.38",
		"num_items":1,
		"first_name":"John",
		"last_name":"Smith",
		"phone_pri":"310-744-5859",
		"phone_alt":"310-658-2609",
		"email":"john@smith.com",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210",
		"display_date":"Tue Nov 4th, 2014",
		"delivery_time":"9:00am - 11:00am",
		"location_type":"Home Residence",
		"instructions":"Please call 30 mins beforehand",
		"logged_in":0,
		"tax_exempt":0,
		"contractor":0,
		"coupon":null
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"update_cart",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210",
		"tracking":"sample",
		"cart_id":"sample"
	} 
}

Jump to Top

place_order

Use this method to place an order.

Parameter	Values	Required?	Description
a	update_cart	Yes	Method requested
address	variable	Yes	Delivery address
city	variable	Yes	Delivery city
state	variable	Yes	Delivery state
zipcode	variable	Yes	Delivery zipcode
first_name	variable	Yes	First name of customer
last_name	variable	Yes	Last name of customer
email	variable	Yes	Email address of customer
phone_pri	variable	Yes	Primary phone number of customer
phone_alt	variable	Optional	Alternate phone number of customer
delivery_date	variable	Yes	Requested date of delivery in the yyyy-mm-dd format
delivery_time	variable	Yes	Requested time of delivery
location_type	home, commercial	Yes	Type of location for delivery address
instructions	variable	Optional	Customer requested delivery instructions
billing_address	variable	Yes	Billing address
billing_city	variable	Yes	Billing city
billing_state	variable	Yes	Billing state
billing_zipcode	variable	Yes	Billing zip code
credit_card_number	variable	Yes	Credit card number
credit_card_type	MasterCard Visa Amex Discover	Yes	Credit card type
credit_card_cvv	variable	Yes	Credit card security code
exp_date_month	1-12	Yes	Credit card expiration month
exp_date_year	variable	Yes	Credit card expiration year
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=place_order&api_key=[API_KEY]&token=[TOKEN]&address=[ADDRESS]&city=[CITY]&state=[STATE]&zipcode=[ZIP_CODE]&first_name=[FIRST_NAME]&last_name=[LAST_NAME]&email=[EMAIL]&phone_pri=[PRIMARY_PHONE]&phone_alt=[ALTERNATE_PHONE]&delivery_date=[DELIVERY_DATE]&delivery_time=[DELIVERY_TIME]&location_type=[LOCATION_TYPE]&instructions=[SPECIAL_INSTRUCTIONS]&billing_address=[BILLING_ADDRESS]&billing_city=[BILLING_CITY]&billing_state=[BILLING_STATE]&billing_zipcode=[BILLING_ZIP_CODE]&credit_card_number=[CC_NUM]&credit_card_type=[CC_CARD_TYPE]&credit_card_cvv=[CC_CVV]&exp_date_month=[CC_EXPIRE_MONTH]&exp_date_year=[CC_EXPIRE_YEAR]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your order was successfully placed",
	"grand_total":"793.38",
	"items":[{
		"product_desc":"20 cubic yards of Decomposed Granite",
		"order_id":"123456894",
		"price_formatted":"793.38"
	}],
	"detail":{
		"first_name":"John",
		"last_name":"Smith",
		"email_address":"john@smith.com",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zip_code":"90210",
		"primary_phone":"310-744-5859",
		"alternate_phone":"310-658-2609",
		"delivery_type":"Home Residence",
		"delivery_time":"9:00am - 11:00am",
		"display_date":"Wed Oct 15th, 2014",
		"order_date":"2014-10-14 22:07:42",
		"special_instructions":"Please call 30 mins beforehand"
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"place_order",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_subcat_detail

Function to get subcategory detail on a supplied subcategory key.

Parameter	Values	Required?	Description
a	get_subcat_detail	Yes	Method requested
subcategory	variable	Yes	Subcategory key of detail requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_subcat_detail&subcategory=[SUBCATEGORY_KEY]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your request returned 1 subcategory",
	"results":{
		"soldBy":"Volume",
		"categoryDesc":"Decomposed Granite",
		"categorySeo":"decomposed-granite",
		"subcategoryDesc":"Decomposed Granite",
		"subcategorySeo":"decomposed-granite"
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_subcat_detail",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

order_lookup

Use this method to look up the status of an order.

Parameter	Values	Required?	Description
a	order_lookup	Yes	Method requested
email_address	variable	Yes	Email address attached to a order
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=order_lookup&email_address=[EMAIL]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"num_results":52,
	"message":"We have found 1 order",
	"results":[{
		"id":"5029",
		"first_name":"John",
		"last_name":"Smith",
		"address":"6701 Main Ave",
		"email_address":"contractor@soildirect.com",
		"city":"Los Angeles",
		"state":"CA",
		"zip_code":"91201",
		"primary_phone":"310-555-5555",
		"alternate_phone":"",
		"delivery_type":"Home Residence",
		"delivery_time":"9:00am - 11:00am",
		"is_sample":"1",
		"special_instructions":"",
		"product_desc":"Sample of Flower Vegetable Mix",
		"order_status":"Pending",
		"order_display":"September 30th, 2014",
		"delivery_display":"October 1st, 2014",
		"order_total_display":"10.00"
	}],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"order_lookup",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_faqs

Use this method to retrieve all sitewide faqs, as well as, faqs you have defined in your admin console.

Parameter	Values	Required?	Description
a	get_faqs	Yes	Method requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_faqs&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Faqs successfully loaded",
	"num_results":21,
	"results":[{
		"QUESTION":"What is SoilDirect.com?",
		"ANSWER":"Soil Direct is a search engine for ordering bulk landscaping materials. SoilDirect.com allows homeowners and contractors to quickly and easily search for available materials online. Customers have instant access to pricing for all available products. Ordering online is fast, secure, and easy. Try us out and see how we can work for you.",
		"sitekey":"soildirect"
		},{
		"QUESTION":"What types of materials are available?",
		"ANSWER":"The types of available materials vary by location. Our network deliveres everything from clean dirt, mulch, compost, topsoil, decomposed granite, gravel, sand, and much more. To see available products in your area input the delivery address on our home page.",
		"sitekey":"soildirect"
		},{
		"QUESTION":"How do I determine the correct material to order?",
		"ANSWER":"Our sales representative has detailed what the material can be used for. If you require additional information you can contact the sales representative directly by the phone number located on the product details pages. Call 888-688-Soil along with the three digit extension for the location.",
		"sitekey":"soildirect"
	}],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_faqs",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_recent_searches

Use this method to retrieve recent search requests to the system. Searches are maintained for 1-2 days.

Parameter	Values	Required?	Description
a	get_recent_searches	Yes	Method requested
max_results	variable	Optional	Max number of results requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_recent_searches&max_results=[MAX_RESULTS]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Here are your recent searches",
	"searches":[{
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210"
	},{
		"address":"6703 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210"
	},{
		"address":"6705 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210"
	}],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_recent_searches",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

apply_coupon

Use this method to apply a coupon code to a shopping cart. Only one coupon is allowed per shopping cart.

Parameter	Values	Required?	Description
a	apply_coupon	Yes	Method requested
coupon_code	variable	Yes	Coupon code to add to cart
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=apply_coupon&coupon_code=[COUPON_CODE]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Coupon: sample was successfully applied",
	"results":[],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"apply_coupon",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

remove_coupon

Use this method to remove any coupon that is in the shopping cart.

Parameter	Values	Required?	Description
a	remove_coupon	Yes	Method requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=remove_coupon&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Coupon was successfully removed",
	"results":[],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"remove_coupon",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

register_user

Use this method to sign up for a user account that will be attached to your admin account.

Parameter	Values	Required?	Description
a	register_user	Yes	Method requested
first_name	variable	Yes	First name of customer
last_name	variable	Yes	Last name of customer
email_address	variable	Yes	Email of customer
password	variable	Yes	Password of customer
conf_password	variable	Yes	Confirmed password of customer
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=register_user&first_name=[FIRST_NAME]&last_name=[LAST_NAME]&email_address=[EMAIL]&password=[PASSWORD]&conf_password=[PASSWORD]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your registration application was successfully submitted. An email had been dispatched to the email you submitted",
	"results":[],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"register_user",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

login

Use this method to login into your account

Parameter	Values	Required?	Description
a	login	Yes	Method requested
email_address	variable	Yes	Email address
password	variable	Yes	Account password
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=login&email_address=[EMAIL]&password=[PASSWORD]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"You have successfully logged in",
	"results":{
		"first_name":"John",
		"last_name":"Smith",
		"email":"john@smith.com",
		"opt_in":"1",
		"join_display":"May 15th, 2008",
		"license_number":"",
		"is_contractor":"",
		"seller_permit":"",
		"tax_exempt":"",
		"logged_in":1
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"login",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

browse_orders

Use this method to view all orders placed. You must be logged in to use this method.

Parameter	Values	Required?	Description
a	browse_orders	Yes	Method requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=browse_orders&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your orders were successfully found.",
	"results":[{
		"order":{
			"id":"2333",
			"product_desc":"10 cubic yards of Topsoil 30\/70. To be delivered in a Super 10 Dump Truck.",
			"order_status":"Pending",
			"order_display":"July 27th, 2013",
			"delivery_display":"July 28th, 2013",
			"order_total_display":"335.72"
		}
		},{
		"order":{
			"id":"2332",
			"product_desc":"10 cubic yards of Unscreened Fill Dirt. To be delivered in a Super 10 Dump Truck.",
			"order_status":"Pending",
			"order_display":"July 27th, 2013",
			"delivery_display":"July 28th, 2013",
			"order_total_display":"10.00"
		}
	}],
	"num_results":2,
	"user":{
		"logged_in":1
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"browse_orders",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_order_detail

Use this method to retrieve order details made when you were logged in. You must be logged in to use this method.

Parameter	Values	Required?	Description
a	get_order_detail	Yes	Method requested
order_id	variable	Yes	ID of order requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted response (click inside code to reveal entire response)

https://www.soildirect.com/api/?a=get_order_detail&order_id=[ORDER_ID]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response

{
	"success":1,
	"message":"Your order was successfully found.",
	"results":{
		"id":"2329",
		"first_name":"John",
		"last_name":"Smith",
		"address":"4422 Mammoth Ave",
		"email_address":"cnt@soildirect.com",
		"city":"Sherman Oaks",
		"state":"CA",
		"zip_code":"91425",
		"primary_phone":"3107455859",
		"alternate_phone":"3107645359",
		"delivery_type":"Home Residence",
		"delivery_time":"9:00am - 11:00am",
		"is_sample":"1",
		"special_instructions":"",
		"product_desc":"Sample of Decomposed Granite",
		"order_status":"Pending",
		"order_display":"July 27th, 2013",
		"delivery_display":"July 28th, 2013",
		"order_total_display":"10.00"
	},
	"user":{
		"logged_in":1
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_order_detail",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_profile

Use this method to retrieve account details. You must be logged in to use this method.

Parameter	Values	Required?	Description
a	get_profile	Yes	Method requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_profile&api_version=[API_VERSION]&api_key=[API_KEY]&token=[TOKEN]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your profile was found",
	"results":{
		"first_name":"John",
		"last_name":"Smith",
		"email":"contractor@soildirect.com",
		"opt_in":"1",
		"join_display":"May 15th, 2008",
		"license_number":"",
		"is_contractor":"",
		"seller_permit":"",
		"tax_exempt":"",
		"logged_in":1
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_profile",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

update_account_profile

Use this method to update account details. You must be logged in to use this method.

Parameter	Values	Required?	Description
a	update_account_profile	Yes	Method requested
first_name	variable	Yes	First name of customer
last_name	variable	Yes	Last name of customer
email_address	variable	Yes	Email address of customer
license_number	variable	Optional	Contractor's license number
seller_permit	variable	Optional	Seller's permit number
opt_in	0,1	Optional	1 if customer would like to opt in for mailings. 0 otherwise.
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=update_account_profile&first_name=[FIRST_NAME]&last_name=[LAST_NAME]&email_address=[EMAIL]&license_number=[CONTRACTOR_LICENSE&seller_permit=[SELLERS_PERMIT]&opt_in=[OPT_IN]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
"success":1,
	"message":"Your account was successfully updated.",
	"results":{
		"first_name":"John",
		"last_name":"Smith",
		"email":"john@smith.com",
		"opt_in":"1",
		"join_display":"May 15th, 2008",
		"is_contractor":"",
		"license_number":"",
		"tax_exempt":"",
		"seller_permit":""
	},
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"update_account_profile",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

send_password

Use this method to reset your password and have it sent to your registered email address.

Parameter	Values	Required?	Description
a	send_password	Yes	Method requested
email_address	variable	Yes	Email of account
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=send_password&email_address=[EMAIL]&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
"success":1,
	"message":"Your password was successfully sent.",
	"results":[],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"send_password",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

logout

Use this method to logout a user out of their account.

Parameter	Values	Required?	Description
a	logout	Yes	Method requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=logout&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"You have successfully logged out",
	"results":[],
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"logout",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

get_latest_api_version

Use this method to get the latest api version that is active and supported.

Parameter	Values	Required?	Description
a	get_latest_api_version	Yes	Method requested
api_key	variable	Yes	Supplied API key
token	variable	Yes	Generated token
api_version	variable	Optional	API version requested

Formatted call

https://www.soildirect.com/api/?a=get_latest_api_version&api_key=[API_KEY]&token=[TOKEN]&api_version=[API_VERSION]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"The latest api version is 3.0",
	"results":"3.0",
	"request":{
		"key":"sample",
		"api_version":"3.0",
		"action":"get_latest_api_version",
		"tracking":"sample",
		"cart_id":"sample"
	}
}

Jump to Top

Information

Methods

Other Versions

Apply to use API

Introduction

Authentication

Response Format

Methods

get_token

get_cats

get_subcats

get_calculate

get_pricing

add_to_cart

remove_from_cart

get_cart

update_cart

place_order

get_subcat_detail

order_lookup

get_faqs

get_recent_searches

apply_coupon

remove_coupon

register_user

login

browse_orders

get_order_detail

get_profile

update_account_profile

send_password

logout

get_latest_api_version