My Account   Login / Signup Shopping Cart Image

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.6.

This documentation is compatible with the following API versions: 3.0.2.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
client_ip variable Yes IP address of client

Formatted call

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

Formatted response (click inside code to reveal entire response)

{
	"token":"sample",
	"success":1,
	"request":{
		"key":"sample",
		"api_version":"3.0.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_token"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.4soil.com\/images\/c2\/amended-topsoil.jpg"
	},{
		"category_seo":"base",
		"category_desc":"Base",
		"image_path":"https:\/\/www.4soil.com\/images\/c2\/c20120712200226.jpg"
	},{
		"category_seo":"compost",
		"category_desc":"Compost",
		"image_path":"https:\/\/www.4soil.com\/images\/c2\/c20120712200357.jpg"
	},{
		"category_seo":"decomposed-granite",
		"category_desc":"Decomposed Granite",
		"image_path":"https:\/\/www.4soil.com\/images\/c2\/c20120620151208.jpg"
	},{
		"category_seo":"dirt",
		"category_desc":"Dirt",
		"image_path":"https:\/\/www.4soil.com\/images\/c2\/c20120617144604.jpg"
	},{
		"category_seo":"gravel-decorative-rock",
		"category_desc":"Gravel\/ Decorative Rock ",
		"image_path":"https:\/\/www.4soil.com\/images\/c2\/c20120617145209.jpg"
	}],
	"request":{
		"key":"sample",
		"api_version":"3.0.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_cats",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.4soil.com\/images\/size00\/organic-soil-for-vegetable-gardens.jpg",
		"thumb_path":"https:\/\/www.4soil.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.4soil.com\/images\/size00\/p174-s43-04-20100125-113303.jpg",
		"thumb_path":"https:\/\/www.4soil.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.4soil.com\/images\/size00\/p80-43-02-20081021-120412.jpg",
		"thumb_path":"https:\/\/www.4soil.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.4soil.com\/images\/noproductimage-large.jpg",
		"thumb_path":"https:\/\/www.4soil.com\/images\/noproductimage.jpg"
	}],
	"request":{
		"key":"sample",
		"api_version":"3.0.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_subcats",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.4soil.com\/images\/c2\/c20120712200357.jpg"
	},
	"request":{
		"key":"sample",
		"api_version":"3.0.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_calculate",
		"subcategory_seo":"topsoil-30-70",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.4soil.com\/images\/size00\/p119-s43-03-20081222-131126.jpg",
			"thumb_path":"https:\/\/www.4soil.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.2.2",
		"action":"get_pricing",
		"client_ip":"192.168.0.1",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210"
	}
}

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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"add_to_cart",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"remove_from_cart"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.4soil.com\/images\/size02\/decomposed-vegetation-compost.jpg",
			"image_path":"https:\/\/www.4soil.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.4soil.com\/images\/size02\/organic-soil-for-vegetable-gardens.jpg",
			"image_path":"https:\/\/www.4soil.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",
		
		"display_date":"Mon Nov 3rd, 2014",
		"instructions":"",
		"logged_in":0,
		"tax_exempt":0,
		"contractor":0
	},
	"request":{
		"key":"sample",
		"api_version":"3.0.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_cart"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.4soil.com\/images\/size00\/p21-43-02-20081021-120116.jpg",
			"image_path":"https:\/\/www.4soil.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-444-5555",
		"phone_alt":"310-666-9999",
		"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.2.2",
		"client_ip":"192.168.0.1",
		"action":"update_cart",
		"address":"6701 Main St",
		"city":"Los Angeles",
		"state":"CA",
		"zipcode":"90210"
	} 
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Your order was successfully placed",
	"order_id":"3999",
	"grand_total":"803.38",
	"items":[
	{
		"item_id":"7020",
		"product_desc":"20 cubic yards of Decomposed Granite",
		"price_formatted":"793.38"
	},{
		"item_id":"7021",
		"product_desc":"Sample of Topsoil 30\/70",
		"price_formatted":"10.00"
	}],
	"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-444-5555",
		"alternate_phone":"310-666-9999",
		"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.2.2",
		"client_ip":"192.168.0.1",
		"action":"place_order"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_subcat_detail"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"order_lookup"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_faqs"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_recent_searches"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"apply_coupon"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"Coupon was successfully removed",
	"results":[],
	"request":{
		"key":"sample",
		"api_version":"3.0.2.2",
		"client_ip":"192.168.0.1",
		"action":"remove_coupon"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"register_user"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"login"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"browse_orders"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_order_detail"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_profile"
	}
}
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
client_ip variable Yes IP address of client

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]&client_ip=[CLIENT_IP]

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"update_account_profile"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"send_password"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

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.2.2",
		"client_ip":"192.168.0.1",
		"action":"logout"
	}
}
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
client_ip variable Yes IP address of client

Formatted call

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

Formatted response (click inside code to reveal entire response)

{
	"success":1,
	"message":"The latest api version is 3.0.3",
	"results":"3.0.3",
	"request":{
		"key":"sample",
		"api_version":"3.0.2.2",
		"client_ip":"192.168.0.1",
		"action":"get_latest_api_version"
	}
}
Jump to Top