08/30/2010 - Changed name to first_name and last_name.
12/24/2010 - Added "is_email_notification".
12/27/2010 - Added FAQ seciton. Added "rental_ids".
01/11/2011 - Added "complex_ids"
Introduction to Lead Insert API
The Lead Insert API provides developers with the ability to insert a lead into a YGL account. This is can used, for example, for external lead capturing.
Lead Insert Request Syntax
To insert a lead using the Lead Insert API, you need to send a SECURE HTTP POST request to the following URL: https://www.yougotlistings.com/api/leads/insert.php
You can use the following list of POST parameters to update corresponding lead info. All parameters are case sensitive.
|Name||Required?||Default Value||Possible Values||Purpose|
|key||Required||N/A||Exactly as provided by YGL||Authentication. Unauthorized requests are rejected.|
|external_id||Optional||Null||The lead ID from external system. (25 characters max.)||The unique ID used in a third party system.|
|first_name||Required||N/A||String (150 characters max.)||The lead's first name.|
|last_name||Optional||Null||String (150 characters max.)||The lead's last name.|
|phone||Optional||Null||Contains at least one valid phone number. String (100 characters max.)||The lead's phone number(s).|
|Optional||N/A||Valid email address. String (100 characters max.)||The lead's email address.|
|move_in||Optional||N/A||Valid date format (mm/dd/YYYY).||The lead's desired move in date in mm/dd/YYY format.|
|beds||Optional||N/A||Integer||The number of beds the lead is looking for.|
|max_rent||Optional||N/A||Integer||The maximum rent / month the lead is looking for.|
|poi||Optional||N/A||List of Point of Interests separated by ",".||The point of interests the lead is interested in.|
|cities_neighborhoods||Optional||N/A||List of cities and neighborhoods separated by ",". Neighborhood must be accompanied by the city separated by ":". Ex. Brookline (city), Allston (neighborhood), Brighton (neighborhood), use "Brookline,Boston:Allston,Boston:Brigton"||The cities and neighborhoods the lead is interested in.|
|source||Optional||Null||String (max. 45 characters)||Indicates the source this lead was generated from.|
|cat||Optional||Null||Integer (0 or 1)||Indicates if the lead has a cat. 0 - no cat, 1 - has cat.|
|dog||Optional||Null||Integer (0 or 1)||Indicates if the lead has a dog. 0 - no dog, 1 - has dog.|
|notes||Optional||Null||String||Lead comments and notes.|
|rental_ids||Optional||Null||String||IDs of the rental listings the lead is interested in. The ids are separated by commas.|
|complex_ids||Optional||Null||String||IDs of the complexes the lead is interested in. The ids are separated by commas.|
|is_email_notification||Optional||Null||Integer (0 or 1)||Indicates when a lead is inserted successfully, is an notification email automatically sent to the agency or agent. 0 - No email sent. 1 - Send notification email.|
Response from the Lead Insert API is in XML format. Each response from the API includes a "responseCode" field. This is a number between 200 - 399, which indicates the response status of your request. A number between 200 - 299 indicates successful requests, and 300 - 399 indicates failure requests. Please see the response codes section below for a list of possible response codes and what each means. If a field is not available, the corresponding XML element will not be included in the response XML.
XML Resposne to a Successful Request
<!--?xml version=\"1.0\" encoding=\"UTF-8\"?--> <yglresponse responsecode="200"> <landlordid></landlordid> -- The YGL ID of the lead affected. <externalid></externalid> -- The external ID of the lead affected if available. </yglresponse>XML Response to a Failed Request
<!--?xml version=\"1.0\" encoding=\"UTF-8\"?--> <yglresponse responsecode="300"> <error>Lead insert failed.</error> </yglresponse>Response Codes
The response codes are current work in progress. Please check back periodically to see if new ones are added.
|300||Failed request. Reason Unknown.|
Who is the email notification sent to?
For Unlimited Users account, the lead email notification would depend on the account's Lead Distribution setting. If a listing has a Listing Agent assigned, then the Listing Agent will be the only person getting notified regardless of what the Lead Distribution setting is.