API method: create_user

This method allows you to generate a new ToldYa seller account along with a new store widget. A unique ToldYa seller account is required for each store. When a new user is created, we will send a welcome email to the email address specified and the new User will be automatically added to your ToldYa seller network. The welcome email will contain a auto-generated password that the new user can use to activate their account and log into their new ToldYa seller account here at toldya.com to view and manage their store and/or their orders at any time.

Request Method	API Endpoint URL
POST	http://www.toldya.com/api/

Required Parameters

Parameter	Data Type	Length	Notes
action	string		create_user
api_key	string		Your API key
username	string	4-20	New User logs in with this username. Must be unique on toldya.com
email	email	max 80	User's email address. Must be a valid email address and unique at toldya.com
first_name	string	max 40	User's first name
last_name	string	max 40	User's last name

Optional Parameters (show | hide)

Parameter	Data Type	Length	Notes
is_franchise	boolean		Select this option if you own or manage a franchise and you want the new User to become a franchisee. Your existing store will be used to control the item listing for this new User. The new User will be responsible for managing and fulfilling orders for your items as usual and their earnings will be deposited into their bank account. For more information about this option, please feel free to contact us.
url	string	max 100	User's home page URL.
company	string	max 100	Company User works for
address_1	string	max 50	User's billing address.
address_2	string	max 50	User's apt or box #
phone	phone	max 20	User's billing phone number. Must be a U.S. phone number including area code. Acceptible formats: 555-555-1212, 555.555.1212, 5555551212, (555)555-1212
phone_ext	string	max 10
city	string	max 50	User's billing city. Must be U.S. city.
state	string	2	User's billing state. Must be 2 character code for U.S. state
zip	string	max 15	User's billing zip code. Must be U.S. zip code. +4 is optional.
storefront_alias	string	max 50	Name of the custom URL for the seller. In the example URL: http://www.toldya.com/stores/fred, 'fred' is the storefront_alias. Must be unique on toldya.com. If not specified, username will be used as storefront_alias.
url_image	string	max 100	URL of profile photo. Example: http://www.mysite.com/photo1.jpg The image will be automatically downloaded and stored at toldya.com.
notes	string	max 255	Optional field you can use to store your own data.

Example Request

The following example shows how to generate a new ToldYa user via the API. In this example, we use cURL and PHP to generate a POST request to the API and to parse the XML response. The primary purpose of creating a POST using server side code instead of simply submitting a form directly to the API is to protect your API key from unauthorized access and to allow you to process the result in a meaningful way. For more information on manually POSTing data, please see your preferred language's documentation.

/**
 * Prepare the new ToldYa User.  This data could 
 * come from a form on your site or blog.
 */
$post = array(
	'action'		=> 'create_user',
	'api_key' 		=> 'your api key',
	'username' 		=> 'freddo',
	'email' 		=> 'freddo@aol.com',
	'first_name' 	=> 'Fred',
	'last_name' 	=> 'Smith',
	'address_1' 	=> '123 Test St',
	'address_2' 	=> 'Apt 201',
	'city' 			=> 'Some City',
	'state' 		=> 'FL',
	'zip' 			=> '33308',
	'phone' 		=> '555-555-1212',
	'company' 		=> 'Fred\'s Company',
	'url' 			=> 'http://www.fredscompany.com',
	'notes'			=> '123',
	'url_image'		=> 'http://somesite.com/some_photo.jpg'
);

/*
 * Use cURL to POST the data to the API and
 * retrieve the XML response.
 */
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.toldya.com/api/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);

$response = curl_exec($ch);

/**
 * handle any cURL errors
 */
if (curl_errno($ch)) {
	$message ='cURL Error #' . curl_errno($ch) . ': ' . curl_error($ch);
	die($message);
}

curl_close($ch);

/**
 * convert the XML returned by the API
 * into a simple object via this PHP method
 */
$sxml = simplexml_load_string($response);

/**
 * if successful, grab the HTML code to
 * display the new User's store, keeping
 * in mind that it will be empty until we
 * populate it with new items
 */
if($sxml->status == 'SUCCESS') {
	$code = html_entity_decode($sxml->store_code);
/**
 * if the API returns an error, handle it
 */
} else {
	$error_message = $sxml->message;
}

Example Response

Here's an example of how the API responds to creating a new user with a username of 'freddo'. The store_code node in the XML response contains the HTML code to render the new store. To render the new store on your site or blog, first restore the HTML entities in the code (using PHP for example, you can do this with the html_entity_decode function), then copy the code directly to the source code of your site or blog.

Keep in mind that until you populate the new store with one or more items, it will render properly, but will show a message that there are no items currently for sale. Also remember that until the new User activates their ToldYa account by following the instructions in the welcome email they receive, their store will render with a warning icon indicating that they are an unverified seller.

<toldyaapiresponse>
    <url>https://www.toldya.com/api/</url>
    <status>SUCCESS</status>
    <message>User 'freddo' created successfully.</message>
    <store_code>&lt;object classid=&quot;clsid:D27CDB6E-AE6D-11cf-96B8-444553540000&quot; codebase=&quot;http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0&quot; width=&quot;400&quot; height=&quot;300&quot;&gt;&lt;param name=&quot;movie&quot; value=&quot;http://www.toldya.com/resources/swf/stores/-1.swf&quot; /&gt;&lt;param name=&quot;quality&quot; value=&quot;high&quot; /&gt;&lt;param name=&quot;flashVars&quot; value=&quot;fv_url=http://www.toldya.com/&amp;fv_id=-1&quot; /&gt;&lt;embed src=&quot;http://www.toldya.com/resources/swf/stores/-1.swf&quot; width=&quot;400&quot; height=&quot;300&quot; quality=&quot;high&quot; pluginspage=&quot;http://www.macromedia.com/go/getflashplayer&quot; type=&quot;application/x-shockwave-flash&quot; flashvars=&quot;fv_url=http://www.toldya.com/&amp;fv_id=-1&quot;&gt;&lt;/embed&gt;&lt;/object&gt;</store_code>
</toldyaapiresponse>