v1

latestOpenAPI 3.0.12026-07-22120163333.7 KB

Leads

Update Lead

Updates an existing lead. Caller must have manage permission on the lead.

Property block

If the request body carries a property block, it is persisted alongside the lead update with the same semantics as POST /v1.0/leads/{leadId}/property:

property.id omitted or <= 0 — merge with an existing property by address; if no match, create a new property record. (Prior versions of this endpoint rejected this case with UPDATE_LEAD_PROPERTY_FAILED; that restriction has been lifted.)
property.id > 0 — update the named property in place. The property must belong to this lead (its leadUserId must match); otherwise the request is rejected with 200108 LEAD_PROPERTY_NOT_EXIST.

Validation:

When a property block is supplied, at least one of city, state, zipCode, streetAddress must be non-blank; otherwise 200057 PROPERTY_ADDRESS_EMPTY is returned (the lead update is also aborted).

put/v1.0/leads/{leadId}

Path parameters

leadIdinteger required

ID of the lead to update.

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

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 assigned to this contact

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

isHiddenboolean

The lead is hidden or not

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 success , 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 success , 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 success , but only import 64 characters in front.

tagsAddstring[]

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

sourcestring

The source of the lead

birthdaystring

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

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

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). Note: TEAM refers to the entire client account (the organization), not the Lofty "Team add-on" product.

unsubscriptionboolean

Unsubscription the email

tagsRemovestring[]

Tags to remove from the lead, by literal name. Only tags that are already on the lead are affected — a name not currently on the lead is ignored (so a brand-new tag introduced by tags/tagsAdd in the same request is not affected). Names are matched literally, so a tag named "*" is removed like any other. To remove ALL tags use the clearAllTags flag instead. Applied after tags/tagsAdd; it does not change their behavior. Omit it to leave tags unchanged.

clearAllTagsboolean

Set to true to remove ALL tags from the lead. Takes precedence over tags / tagsAdd / tagsRemove. Defaults to false (no change).

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",
  "leadFamilyMemberList": [
    {
      "phones": [
        "+14155551234"
      ],
      "emails": [
        "spouse@example.com"
      ]
    }
  ],
  "language": "en",
  "ownershipScope": "TEAM",
  "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
  },
  "tagsRemove": [
    "Hot Lead"
  ]
}

Response

Lead updated.

leadIdinteger

ID of the lead.

Example response

{
  "leadId": 651095960136641
}