API - Leads Insert

08/21/2010 - Changed the city_neighborhoods so neighborhood must be accompanied with a city.
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).
email 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.
Lead Insert Response Syntax

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.

XML Response to a Failed Request
<!--?xml version=\"1.0\" encoding=\"UTF-8\"?-->
<yglresponse responsecode="300">

   <error>Lead insert failed.</error>

Response Codes

The response codes are current work in progress. Please check back periodically to see if new ones are added.
Code Reason
200 Successful request.
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.

Feedback and Knowledge Base