Skip to content

API - Leads Insert

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:

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).
email 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
listing_sources Optional Null Listing source values separated by "," Restrict the lead searches to only the selected sources. Possible Values: Y, S, F, M, D.
  • Y - YGL Data Entry
  • S - YGL Network
  • F - Internal
  • M - MLSPIN (if applicable)
  • D - MRED (if applicable)
notes Optional Null String Lead comments and notes.
inquired_rental_id Optional Null Number ID of the listing the lead inquired about.
recommended_rental_ids Optional Null String IDs of listings to be added to the lead's Recommended Rentals.
listing_updates Optional Null Integer (0 or 1) Auto-send new listings matching search criteria of the lead. Requires lead email, city and bed search criteria at the minimum.
agent_id Optional Null Integer Assign the lead to the specified agent. If no agent is specified, the lead will be assigned based on the account's lead distribution setting.
request_type Optional Null "JSON" If provided results will be returned in JSON.
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">

   <LeadID></LeadID> -- The YGL ID of the lead affected.
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