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.|
|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_from_date||Optional||N/A||Valid date format (mm/dd/YYYY).||The lead's desired move in date in mm/dd/YYY format.|
|move_to_date||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||List of beds separated by ","||The number of beds the lead is looking for.|
|bath_min||Optional||N/A||Integer||The minimum number of baths the lead is looking for.|
|price_min||Optional||N/A||Integer||The minimum price / month the lead is looking for.|
|price_max||Optional||N/A||Integer||The maximum price / month the lead is looking for.|
|cities||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.|
|pet||Optional||Null||Pet values separated by ","||The pet policies needed by the lead. Possible Values: Dog Ok, Pet Friendly, Cat Ok, Small Dog Ok, No Pet, Negotiable, Breed Restriction|
|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.|
|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.|
|request_type||Optional||Null||"JSON"||If provided results will be returned in JSON.|
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"> <LeadID></LeadID> -- The YGL ID of the lead affected. </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.