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://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>

 


back to top