API Documentation - Prospects

Table of Contents

Prospects

Prospect data must be nested under the client key in the json body.

PUT /api/v2/clients/<client_id>

Edit a limited number of fields on a specified company prospect.

Accepted PUT Parameters

• status
  • String value representing new prospect status
  • Choices are lead, toured, applicant, resident, and not-a-prospect
• application
  • Optional. Details about the prospect’s application if they are being set to applicant or resident status. If not setting to one of those statuses, leave this key out of the payload.
  • Application object keys: * unit_id
    • The Funnel unit id for the unit that the prospect has applied for.
  • lease_start_date
    • YYYY-MM-DD formatted date that the prospect’s lease starts.
  • lease_end_date
    • YYYY-MM-DD formatted date that the prospect’s lease expires.
  • application_submitted_date
    • YYYY-MM-DD formatted date that the prospect’s application was submitted
  • application_price
    • The rent price the prospect is applying with.
  • closed_date
    • YYYY-MM-DD formatted date that the prospect was closed.

Example request body for status change:

{
    "status": "toured"
}

Example request body for status change to applicant:

{
    "status": "applicant"
    "application": {
    	"unit_id": 123,
	"lease_start_date": "2020-06-01",
	"lease_end_date": "2020-05-31",
	"application_submitted_date": "2020-05-20",
	"application_price": "1200.00"
    }
}

POST /api/v2/clients

Create a prospect record in Funnel. Note that in order for Funnel to properly ingest prospects and associate them with teams and properties, the following fields are required: first_name, last_name, email, group.

Accepted POST Parameters

• people
  • List of objects representing people associated with this prospect record.
  • Person object keys:
    • first_name
      • String field for first name
    • last_name
      • String field for last name
    • email
      • String field for email
    • phone_1
      • String field for phone number
    • phone_2
      • Additional phone number field
    • is_primary
      • Boolean field indicating whether or not person is primary prospect contact
• move_in_date
  • Prospect’s desired move in date in format YYYY-MM-DD
• layout
  • Array of layout choices
  • Choices are loft, studio, 1br, 2br, 3br, 4+br
• price_floor
  • Number value representing lowest dollar value the prospect would like to pay
• price_ceiling
  • Number value representing highest dollar value the prospect would like to pay
• notes
  • Free text field for prospect-sourced information
• group
  • Number value provided by Funnel representing the group id the prospect should be assigned to. Please contact us at support@funnelleasing.com to get your group id and more details.
• broker_company
  • String field for broker company if representing prospect
• broker_email
  • String field for broker email if representing prospect
• broker_first_name
  • String field for broker first name if representing prospect
• broker_last_name
  • String field for broker last name if representing prospect
• broker_phone
  • String field for broker name if representing prospect
• client_referral
  • String field for prospect referral source (up to 255 characters)
• campaign_id
  • Campaign Identifier (up to 255 characters)
• campaign_info
  • Optional string. Use this parameter to pass a value to Funnel for marketing attribution. To assign a lead source to a prospect, set the value to a string that matches the name of your campaign as entered in Funnel under marketing settings. The value must match exactly (case sensitive). If also using Funnel’s DNI script, the value of this parameter can be pulled from local storage of the browser and sent via the form.
• community
  • Number value representing the Funnel Community id a prospect is inquiring about
• building
  • Number value representing the Funnel Building id a prospect is inquiring about
• unit
  • Number value representing the Funnel unit id a prospect is inquiring about

NOTE: You should only pass one of three community/building/unit, otherwise you will get a validation error.

• discovery_source
  • String value representing the way the prospect says they discovered your property. This can be entered manually by a prospect on a contact form, guest card, or tour scheduler and is typically presented as the question: “How did you hear about us?” (defaults to null if choice does not match)
  • To retrieve the list of available sources, see Discovery Sources
• lead_source
  • Integer or String value representing the way the prospect became a lead for your property (defaults to null if choice does not match)
  • To retrieve the list of available sources, see Discovery Sources.
  • To send an integer value, it will need to match an ID on your list of available discovery sources.
  • To send a string value, it will need to match a name on your list of available discovery sources.
• device
  • String value indicating the type of device the lead was on when captured.
  • Choices are phone, tablet, desktop, other, or blank if unknown
• source_type
  • String value indicating whether the recorded lead originated from a paid marketing campaign or from an organic, non-paid initiative.
  • Choices are paid, organic, or blank if unknown
• sms_opted_in
  • String value indicating whether the recorded lead has opted in to receiving SMS communication. The available choices are:
  • 'marketing-enabled' : This prospect has opted into receiving all communication including automated marketing messages
  • 'marketing-disabled' : This prospect has opted into receiving communications, but not opted into receiving automated marketing messages. This is the default setting.
  • 'all-sms-disabled': This will disable the prospect from receiving any SMS communications. This setting can be updated via the Funnel app. Use this if you want to temporarily disable SMS communication with the prospect
  • ‘client-opted-out': The prospect has explicitly opted out of communication. This setting cannot be updated unless the prospect submits their information again. Use this if you want to permamently disable all SMS communication with the prospect.
• request_sms
  • Boolean value which will create an event declaring the prospect requested a sms, set the client’s preference for sms, and enable virtual agent for that client if all other factors are satisfied (for instance sms_opted_in)

Example request body:

{
	"client": {
                "people": [{
                		"first_name": "John",
                		"last_name": "Doe",
                		"email": "johndoe@example.com",
                		"phone_1": "5101234567",
                		"phone_2": "",
                		"is_primary": true
                	},
                	{
                		"first_name": "Jane",
                		"last_name": "Doe",
                		"email": "janedoe@example.com",
                		"phone_1": "",
                		"phone_2": "",
                		"is_primary": false
                	}
                ],
                "move_in_date": "1970-01-01",
                "layout": ["studio", "1br"],
                "price_floor": 1500,
                "price_ceiling": 2500,
                "notes": "looking for affordable neighborhood with bars and restaurants",
                "group": 12,
                "broker_company": "Jerry Company",
                "broker_email": "jerry@seinfeld.com",
                "broker_first_name": "Jerry",
                "broker_last_name": "Seinfeld",
                "broker_phone": "4101230987",
                "client_referral": "Company Website",
                "campaign_id": "Test-Campaign",
                "campaign_info": "GooglePPC",
                "unit": 5309,
                "device": "phone",
                "source_type": "organic"
    }
}