Sign in

v1

latestOpenAPI 3.0.12026-07-22120163333.7 KB
Leads

Create Lead

Lead Assignment & Routing

Assignment priority:

  1. If assignedUserId is provided, the lead is directly assigned to that agent. No routing rules are applied.
  2. If assignedUserId is empty or omitted, the lead goes through automatic lead routing based on the configured routing rules.

Routing rule scope (when routing is triggered):

  • assignGroupId = -1 → Apply company-level routing rules.
  • assignGroupId = <officeId> → Apply routing rules for the specified office.
  • assignGroupId not set → Default routing rules will be applied according to the lead’s ownership scope.

Routing location matching:

  • For Seller (1) type leads, routing is determined by the property field (property address/location).
  • For all other lead types (Buyer, Renter, etc.), routing is determined by inquiry.locations[] (interested areas).

Lead Ownership

Controls the visibility scope of the lead:

  • ownershipScope = TEAM → Account-wide: visible to all users in this Lofty client account.
  • ownershipScope = OFFICE → Visible to a specific office. Must provide ownershipId with the office ID.
  • ownershipScope = PERSONAL → Visible only to the assigned agent. Must provide ownershipId with the agent's user ID.
  • If not specified, defaults to PERSONAL scope owned by the API caller.

Note: ownershipScope = TEAM refers to the entire client account (the organization), not the Lofty "Team add-on" product.

Eventual consistency

Persistence is asynchronous. The lead ID is returned immediately, but subsequent GET /v1.0/leads/{leadId} and similar read endpoints may briefly return 404 right after create. Follow-up writes (PUT, POST inquiry, POST property, POST transaction) are unaffected.

Property block

The optional property block is persisted together with the lead:

  • Omit it entirely if you don't need to attach an address — the lead is still created.
  • If provided, at least one of city, state, zipCode, streetAddress must be non-blank; otherwise the request is rejected with 200057 PROPERTY_ADDRESS_EMPTY and no lead is created.
post/v1.0/leads

Headers

Authorizationstring required

Bearer [access_token]

Content-Typestring required

application/json

Request body

cannotTextboolean

false: can send message to the lead

cannotCallboolean

false: can call to the lead

cannotEmailboolean

false: can email to the lead

firstNamestring 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.

lastNamestring

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.

emailsstring[]

A list of email addresses associated with the lead

phonesstring[]

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

leadTypesinteger[]

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

assignedUserIdinteger

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.

streetAddressstring

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

citystring

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

statestring

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

zipCodestring

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

referredBystring

The referee of the lead

stagestring

The stage the lead is in, less than 20 characters

groupsstring[]

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.

segmentsstring[]

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.

tagsstring[]

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.

tagsAddstring[]

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.

sourcestring

The source of the lead

unsubscriptionboolean

Unsubscription the email

welcomeEmailboolean

send Welcome Email. (Not supporting update)

leadAlertboolean

send new lead alert email. (Not supporting update)

birthdaystring

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

leadRoutingboolean

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

assignGroupIdinteger

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.

buyingTimeFramestring

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

preQualstring

Pre-qual, Yes or No.

houseToSellstring

House to Sell, Yes or No.

fthbstring

first time home buyer, Yes or No.

withBuyerAgentstring

With buyer Agent, Yes or No.

sellingTimeFramestring

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

mortgagestring

Mortgage, Yes or No.

buyHousestring

Buy a house, Yes or No.

withListingAgentstring

With listing agent, Yes or No.

languagestring

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

contentstring

Note content

isPinboolean

Pin this note or not

ownershipIdinteger

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.

ownershipScopestring

Controls the visibility scope of the lead. TEAM — Account-wide: visible to all users in this Lofty client account. 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. Note: ownershipScope = TEAM refers to the entire client account (the organization), not the Lofty "Team add-on" product.

defaultInquiryParamboolean
specifiedAssignGroupIdboolean

Example request

{
  "firstName": "Bob",
  "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"
      }
    ]
  },
  "property": {
    "price": 100000,
    "state": "California",
    "city": "New York",
    "streetAddress": "22348 Regnart RD",
    "zipCode": "25401",
    "propertyType": "Single Family Home",
    "bedrooms": 3,
    "bathrooms": 2,
    "squareFeet": 100,
    "lotSize": 26.33,
    "parkingSpace": 1,
    "floors": 1,
    "priceMax": 10000000,
    "priceMin": 100000
  },
  "customAttributeList": [
    {
      "attributeType": "number, text, date, anniversary_date, single_select, multi_select, percentage, currency"
    }
  ],
  "birthday": "Jun 5, 2001",
  "buyingTimeFrame": "6-12",
  "preQual": "Yes",
  "houseToSell": "Yes",
  "fthb": "Yes",
  "withBuyerAgent": "Yes",
  "sellingTimeFrame": "1-3",
  "mortgage": "Yes",
  "buyHouse": "Yes",
  "withListingAgent": "Yes",
  "leadTransaction": {
    "created": 1518078026000,
    "updated": 1518078026000,
    "transactionId": 10001,
    "transactionName": "123 Main St",
    "leadName": "Bob",
    "assignedAgent": 100001,
    "transactionType": "Purchase",
    "homePrice": 1000000,
    "transactionStatus": "Pre-contract",
    "expectedCloseDate": 1508580010000,
    "closeDate": 1508580010000,
    "commissionRate": 3,
    "gci": 5000,
    "teamRevenue": 1000,
    "agentRevenue": 4000,
    "appointmentDate": 1508580010000,
    "agreementSignedDate": 1508580010000,
    "offerDate": 1508580010000,
    "contractDate": 1508580010000,
    "appraisalDate": 1508580010000,
    "homeInspectionDate": 1508580010000,
    "escrowDate": 1508580010000,
    "expiration": 1508580010000
  },
  "leadFamilyMemberList": [
    {
      "phones": [
        "+14155551234"
      ],
      "emails": [
        "spouse@example.com"
      ]
    }
  ],
  "language": "en",
  "content": "example_note"
}

Response

Lead created.

leadIdinteger

ID of the lead.

Example response

{
  "leadId": 651095960136641
}