API - Leads Insert
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 addresses. Up to 5 emails separates by ",". String (750 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.
|
| 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. |
| bcc_agent | Optional | Null | Integer (0 or 1) | When listing updates are sent, BCC the agent in the email. "listing_updates" must be on. |
| 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. |
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 CodesThe 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.