Skip to main content
POST
/
v1.0
/
leads
Create Lead
curl --request POST \
  --url https://api.lofty.com/v1.0/leads \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "firstName": "Bob",
  "cannotText": true,
  "cannotCall": true,
  "cannotEmail": true,
  "lastName": "Li",
  "emails": [
    "jane.doe@example.com",
    "jdoe-work@company.com"
  ],
  "phones": [
    "+14155551234",
    "+12125559876"
  ],
  "leadTypes": [
    2,
    5
  ],
  "assignedUserId": 10000000514,
  "streetAddress": "The White House,1600 Pennsylvania Avenue NW",
  "city": "Washington DC",
  "state": "Washington DC",
  "zipCode": "20500",
  "referredBy": "Jeremy Kelly",
  "stage": "Pending",
  "groups": [
    "VIP Clients",
    "Open House Feb"
  ],
  "segments": [
    "First-Time Buyers",
    "Downtown Area"
  ],
  "tags": [
    "Hot Lead",
    "Zillow"
  ],
  "tagsAdd": [
    "Referral",
    "Pre-Approved"
  ],
  "source": "Open House",
  "inquiry": {
    "priceMin": 1,
    "priceMax": 10000000,
    "propertyType": [
      "Single Family Home",
      "Condo"
    ],
    "bedroomsMin": 1,
    "bathroomsMin": "1",
    "locations": [
      {
        "city": "Austin",
        "stateCode": "TX"
      }
    ],
    "id": 123,
    "leadUserId": 123,
    "bedroomsMax": 123,
    "bathroomsMax": "<string>",
    "modifyByAgent": true,
    "createTime": "2023-11-07T05:31:56Z",
    "updateTime": "2023-11-07T05:31:56Z",
    "defaultValue": true
  },
  "property": {
    "price": 100000,
    "state": "California",
    "city": "New York",
    "streetAddress": "22348 Regnart RD",
    "zipCode": "25401",
    "county": "<string>",
    "propertyType": "Single Family Home",
    "bedrooms": 3,
    "bathrooms": 2,
    "squareFeet": 100,
    "lotSize": 26.33,
    "parkingSpace": 1,
    "floors": 1,
    "mailAddress": true,
    "id": 123,
    "leadUserId": 123,
    "listingId": "<string>",
    "autoListingId": 123,
    "label": "<string>",
    "note": "<string>",
    "listingStatus": "<string>",
    "labelList": "<string>",
    "pictureUrl": "<string>",
    "siteListingUrl": "<string>",
    "labelType": "<string>",
    "priceMax": 10000000,
    "priceMin": 100000
  },
  "unsubscription": true,
  "welcomeEmail": true,
  "leadAlert": true,
  "customAttributeList": [
    {
      "attributeName": "<string>",
      "attributeType": "number, text, date, single_select, multi_select, percentage, currency",
      "value": "<string>",
      "params": "<string>"
    }
  ],
  "birthday": "Jun 5, 2001",
  "leadRouting": true,
  "assignGroupId": 123,
  "buyingTimeFrame": "6-12",
  "preQual": "Yes",
  "houseToSell": "Yes",
  "fthb": "Yes",
  "withBuyerAgent": "Yes",
  "sellingTimeFrame": "1-3",
  "mortgage": "Yes",
  "buyHouse": "Yes",
  "withListingAgent": "Yes",
  "leadFamilyMemberList": [
    {
      "firstName": "<string>",
      "relationship": "<string>",
      "lastName": "<string>",
      "phones": [
        "+14155551234"
      ],
      "emails": [
        "spouse@example.com"
      ],
      "birthday": "<string>"
    }
  ],
  "language": "en",
  "content": "example_note",
  "isPin": false,
  "ownershipId": 123,
  "ownershipScope": "<string>",
  "defaultInquiryParam": true,
  "specifiedAssignGroupId": true
}
'
{
  "leadId": 651095960136641
}

Documentation Index

Fetch the complete documentation index at: https://developer.lofty.com/llms.txt

Use this file to discover all available pages before exploring further.

Silent truncation — firstName, lastName, groups, segments are truncated to 30 characters; tags / tagsAdd to 64 characters. The API returns success with no error. Validate input length before sending.

Headers

​
Authorization
string
required

Bearer [access_token]

​
Content-Type
string
required

application/json

Body

application/json

Lead info that needs to be added in

​
firstName
string
required

The first/given name of the lead Caution: Max limit 30 characters. If you exceed the limit, the import will succuss, but only import 30 characters in front.

Example:

"Bob"

​
cannotText
boolean

false: can send message to the lead

​
cannotCall
boolean

false: can call to the lead

​
cannotEmail
boolean

false: can email to the lead

​
lastName
string

The last/family name of the lead Caution: Max limit 30 characters. If you exceed the limit, the import will succuss, but only import 30 characters in front.

Example:

"Li"

​
emails
string[]

A list of email addresses associated with the lead

Example:
[
  "jane.doe@example.com",
  "jdoe-work@company.com"
]
​
phones
string[]

A list of phone numbers associated with the lead. (No more than 20 characters per phone)

Example:
["+14155551234", "+12125559876"]
​
leadTypes
integer<int32>[]

Types of lead, expressed by ID. Type ID : Other (-1), Seller (1), Buyer (2), Renter (5), Investor (6), Agent (7), Homeowner (8), Landlord (9)

Example:
[2, 5]
​
assignedUserId
integer<int64>

ID of the agent to directly assign this lead to. When provided, automatic lead routing is skipped. When omitted or empty, the lead is routed automatically based on routing rules.

Example:

10000000514

​
streetAddress
string
deprecated

The streetAddress associated with the lead. Deprecated: please use the streetAddress field in property instead.

Example:

"The White House,1600 Pennsylvania Avenue NW"

​
city
string
deprecated

The city associated with the lead. Deprecated: please use the city field in property instead.

Example:

"Washington DC"

​
state
string
deprecated

The state associated with the lead. Deprecated: please use the state field in property instead.

Example:

"Washington DC"

​
zipCode
string
deprecated

ZipCode. Deprecated: please use the zipCode field in property instead.

Example:

"20500"

​
referredBy
string

The referee of the lead

Example:

"Jeremy Kelly"

​
stage
string

The stage the lead is in, less than 20 characters

Example:

"Pending"

​
groups
string[]
deprecated

The groups the lead is in. Caution: Max limit 30 characters. If you exceed the limit, the import will succeed, but only import 30 characters in front. Deprecated, use segments instead.

Example:
["VIP Clients", "Open House Feb"]
​
segments
string[]

The segments the lead is in. Caution: Max limit 30 characters. If you exceed the limit, the import will succeed, but only import 30 characters in front.

Example:
["First-Time Buyers", "Downtown Area"]
​
tags
string[]

The tags associated with the lead. All existing tags will be updated based on this call. Caution: Max limit 64 characters. If you exceed the limit, the import will succeed, but only import 64 characters in front.

Example:
["Hot Lead", "Zillow"]
​
tagsAdd
string[]

The tags associated with the lead. All existing tags will be retained, only add new tags based on this call. Caution: Max limit 64 characters. If you exceed the limit, the import will succeed, but only import 64 characters in front.

Example:
["Referral", "Pre-Approved"]
​
source
string

The source of the lead

Example:

"Open House"

​
inquiry
object

LeadInquirys

​
property
object

Lead property or mailing address details

​
unsubscription
boolean

Unsubscription the email

​
welcomeEmail
boolean

send Welcome Email. (Not supporting update)

​
leadAlert
boolean

send new lead alert email. (Not supporting update)

​
customAttributeList
object[]

User customized field

​
birthday
string

The birthday of the lead(pattern:MMM d, yyyy)

Example:

"Jun 5, 2001"

​
leadRouting
boolean
deprecated

Deprecated. Lead routing is now automatically applied when assignedUserId is not provided. This field has no effect.

​
assignGroupId
integer<int64>

Specifies which routing rule scope to apply when automatic lead routing is triggered (i.e., assignedUserId is not provided). Set to -1 to use company-level routing rules. Set to a specific office ID to use that office's routing rules. If omitted, default routing rules will be applied according to the lead’s ownership scope.

​
buyingTimeFrame
string

buying time frame, 1-3, 3-6, 6-12, 12+, Just Looking, Refinancing.

Example:

"6-12"

​
preQual
string

Pre-qual, Yes or No.

Example:

"Yes"

​
houseToSell
string

House to Sell, Yes or No.

Example:

"Yes"

​
fthb
string

first time home buyer, Yes or No.

Example:

"Yes"

​
withBuyerAgent
string

With buyer Agent, Yes or No.

Example:

"Yes"

​
sellingTimeFrame
string

selling time frame, 1-3, 3-6, 6-12, 12+, Just Looking, Refinancing.

Example:

"1-3"

​
mortgage
string

Mortgage, Yes or No.

Example:

"Yes"

​
buyHouse
string

Buy a house, Yes or No.

Example:

"Yes"

​
withListingAgent
string

With listing agent, Yes or No.

Example:

"Yes"

​
leadTransaction
object
​
leadFamilyMemberList
object[]

A list of family members associated with the lead. You can add up to 4 family members.

​
language
string

The lead's abbreviated language, en, fr, de, es, zh-CN, zh-TW, ja

Example:

"en"

​
content
string

Note content

Example:

"example_note"

​
isPin
boolean

Pin this note or not

Example:

false

​
ownershipId
integer<int64>

The entity ID for the ownership scope. Required when ownershipScope is OFFICE (pass the office ID) or PERSONAL (pass the agent's user ID). Ignored when ownershipScope is TEAM.

​
ownershipScope
string

Controls the visibility scope of the lead. TEAM — visible to the entire team (company-wide). OFFICE — visible only within the specified office (requires ownershipId). PERSONAL — visible only to the specified agent (requires ownershipId). Defaults to PERSONAL scope owned by the API caller if not specified.

​
defaultInquiryParam
boolean
​
specifiedAssignGroupId
boolean

Response

200 - application/json

Lead created.

Response containing the lead ID.

​
leadId
integer<int64>

ID of the lead.

Example:

651095960136641