--- title: "Update Lead" method: PUT path: "/v1.0/leads/{leadId}" tags: ["Leads"] --- # Update Lead `PUT /v1.0/leads/{leadId}` 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). ## Path parameters - `leadId` integer, required ## Headers - `Authorization` string, required - `Content-Type` string, required ## Request body - EditLeadRequest — Lead update payload. - `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 - `firstName` string — 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. - `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. - `emails` string[] — A list of email addresses associated with the lead - `phones` string[] — A list of phone numbers associated with the lead. (No more than 20 characters per phone) - `leadTypes` integer[] — Types of lead, expressed by ID. Type ID : Other (-1), Seller (1), Buyer (2), Renter (5), Investor (6), Agent (7),Homeowner (8), Landlord (9) - `assignedUserId` integer — Id of the agent assigned to this contact - `streetAddress` string — The streetAddress associated with the lead. Deprecated: please use the streetAddress field in property instead. - `city` string — The city associated with the lead. Deprecated: please use the city field in property instead. - `state` string — The state associated with the lead. Deprecated: please use the state field in property instead. - `zipCode` string — ZipCode. Deprecated: please use the zipCode field in property instead. - `referredBy` string — The referee of the lead - `isHidden` boolean — The lead is hidden or not - `stage` string — The stage the lead is in, less than 20 characters - `groups` string[] — 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. - `segments` string[] — 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. - `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 success , but only import 64 characters in front. - `tagsAdd` string[] — 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. - `source` string — The source of the lead - `inquiry` LeadInquiry — LeadInquirys - `priceMin` integer — Price range lower end - `priceMax` integer — Price range higher end - `propertyType` string[] — Property types: `Single Family Home`, `Multi-Family`, `Condo`, `Townhouse`, `Mobile Home`, `Manufactured Home`, `Vacant Land`, `Commercial`. - `bedroomsMin` integer — Bed Rooms - `bathroomsMin` string — Bath Rooms - `locations` Location[] — Areas the lead is interested in. Each entry is a Location object (city, stateCode, zipCode, county, streetAddress or description). Used by routing rules when the lead's leadTypes do not include Seller (1). - `stateCode` string — The state code of city Applies to lead routing if the leadType field is not Seller(1) in the lead creation request. - `city` string — The city Applies to lead routing if the leadType field is not Seller(1) in the lead creation request. - `zipCode` string — The zip code Applies to lead routing if the leadType field is not Seller(1) in the lead creation request. - `county` string — The county Applies to lead routing if the leadType field is not Seller(1) in the lead creation request. - `streetAddress` string — The street address Applies to lead routing if the leadType field is not Seller(1) in the lead creation request. - `description` string — Description of location. - `id` integer - `leadUserId` integer - `bedroomsMax` integer - `bathroomsMax` string - `modifyByAgent` boolean - `createTime` string, date-time - `updateTime` string, date-time - `defaultValue` boolean - `property` LeadProperty — Lead property or mailing address details - `price` integer — The price Applies to lead routing only if the leadType field is Seller(1) - `state` string — The state Applies to lead routing only if the leadType field is Seller(1) - `city` string — The city Applies to lead routing only if the leadType field is Seller(1) - `streetAddress` string — The street address Applies to lead routing only if the leadType field is Seller(1) - `zipCode` string — The zip code Applies to lead routing only if the leadType field is Seller(1) - `county` string — The county Applies to lead routing only if the leadType field is Seller(1) - `propertyType` string — Property type: `Single Family Home`, `Multi-Family`, `Condo`, `Townhouse`, `Mobile Home`, `Manufactured Home`, `Vacant Land`, `Commercial`. - `bedrooms` integer — The bed rooms. - `bathrooms` number, double — The bath rooms. - `squareFeet` integer — The square feet. - `lotSize` number, double — The lot size (acreage). - `parkingSpace` integer — The parking space. - `floors` integer — The floors. - `mailAddress` boolean — If set to true, the address is a mailing address; otherwise, it is a property address. - `id` integer — The property ID. Required when updating an existing mailing address or property address. If not provided, a new address will be created. - `leadUserId` integer - `listingId` string - `autoListingId` integer - `label` string - `note` string - `listingStatus` string - `labelList` string - `pictureUrl` string - `siteListingUrl` string - `labelType` string - `priceMax` integer — The max price Applies to lead routing only if the leadType field is Seller(1) - `priceMin` integer — The min price Applies to lead routing only if the leadType field is Seller(1) - `customAttributeList` CustomAttribute[] — User customized field - `attributeName` string, required — The name of this custom field - `attributeType` string, required — The type of the field - `value` string, required — The content of the field for lead, value for multi-select,such as "[\"item1\",\"item2\s",...]" .It's unnecessary when adding a new custom field for team - `params` string — options for select, such as {"option":["item1","item2",...]} - `birthday` string — The birthday of the lead(pattern:MMM d, yyyy) - `buyingTimeFrame` string — buying time frame, `1-3`, `3-6`, `6-12`, `12+`, `Just Looking`, `Refinancing`. - `preQual` string — Pre-qual, `Yes` or `No`. - `houseToSell` string — House to Sell, `Yes` or `No`. - `fthb` string — first time home buyer, `Yes` or `No`. - `withBuyerAgent` string — With buyer Agent, `Yes` or `No`. - `sellingTimeFrame` string — selling time frame, `1-3`, `3-6`, `6-12`, `12+`, `Just Looking`, `Refinancing`. - `mortgage` string — Mortgage, `Yes` or `No`. - `buyHouse` string — Buy a house, `Yes` or `No`. - `withListingAgent` string — With listing agent, `Yes` or `No`. - `leadFamilyMemberList` LeadFamilyMember[] — A list of family members associated with the lead. You can add up to 4 family members. - `relationship` string — The relationship of this family member to primary lead. Example: Husband - `firstName` string, required — The first name of the family member - `lastName` string — The last name of the family member - `phones` string[] — A list of phone numbers associated with the family member. (No more than 20 characters per phone) - `emails` string[] — A list of email addresses associated with the lead - `birthday` string — The birthday of the family member(pattern:MMM d, yyyy) - `language` string — The lead's abbreviated language, `en`, `fr`, `de`, `es`, `zh-CN`, `zh-TW`, `ja` - `ownershipId` integer — 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` — 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. - `unsubscription` boolean — Unsubscription the email - `leadTransaction` LeadTransaction - `created` integer — Transaction creation timestamp, in milliseconds since Unix epoch (UTC). Do not supply on create. - `updated` integer — Transaction last-modified timestamp, in milliseconds since Unix epoch (UTC). Do not supply on create or update. - `transactionId` integer — Transaction ID. Do not supply on create. - `transactionName` string, required — Property address or deal name. Required on create. Must not be blank and must not contain '<' or '>' characters. - `leadName` string — Name of the lead this transaction belongs to. Ignored if supplied in a request body. - `assignedAgent` integer — User ID of the agent this transaction is assigned to. Ignored if supplied in a request body. - `transactionType` 'Purchase' | 'Listing' | 'Lease' | 'Other' — Transaction type. Case-sensitive; must be one of the supported values. Values not matching the team's configured pipeline types fall back silently to the first pipeline (typically 'Purchase / Pre-contract'); always pass a valid type to avoid this silent behavior. - `homePrice` number — Home price of the transaction. - `transactionStatus` string — Transaction status name. Must match one of the statuses configured in the team's pipeline for the given transactionType; unmatched values silently fall back to the first status of that type. - `expectedCloseDate` integer — Expected close date, in milliseconds since Unix epoch (UTC). - `closeDate` integer — Actual close date, in milliseconds since Unix epoch (UTC). - `commissionRate` number — Commission rate, expressed as a percentage (e.g. 3 for 3%). - `gci` number — Gross Commission Income (GCI) of the transaction. - `teamRevenue` number — Portion of the GCI attributed to the team. - `agentRevenue` number — Portion of the GCI attributed to the agent. - `appointmentDate` integer — Appointment date, in milliseconds since Unix epoch (UTC). - `agreementSignedDate` integer — Agreement-signed date, in milliseconds since Unix epoch (UTC). - `offerDate` integer — Offer date, in milliseconds since Unix epoch (UTC). - `contractDate` integer — Contract date, in milliseconds since Unix epoch (UTC). - `appraisalDate` integer — Appraisal date, in milliseconds since Unix epoch (UTC). - `homeInspectionDate` integer — Home-inspection date, in milliseconds since Unix epoch (UTC). - `escrowDate` integer — Escrow date, in milliseconds since Unix epoch (UTC). - `expiration` integer — Expiration date (listing / contract), in milliseconds since Unix epoch (UTC). - `customFields` CustomFieldRequest[] — Custom field values; full-coverage update or insertion. See GET /v1.0/transaction/customfields for the team's custom field definitions. - `id` integer — Custom field id - `value` string — Custom field value For multi_select, the format is:["Item1","Item2", ...] - `commissions` Commissions — Commission structure (preSplit / split / postSplit). See POST /v1.0/leads/{leadId}/transaction description for validation rules. - `preSplit` Commission[] - `id` integer - `splitPayType` 'TEAM' | 'AGENT' | 'VENDOR_PARTNER' | 'LEAD' | 'OTHER' | 'BROKERAGE' | 'UPLINE' - `splitPayTo` integer - `splitPayToName` string - `payType` 'TEAM' | 'AGENT' | 'VENDOR_PARTNER' | 'LEAD' | 'OTHER' | 'BROKERAGE' | 'UPLINE' - `payTo` integer - `payToName` string - `value` integer - `calculateType` 'PERCENT' | 'AMOUNT' - `desc` string - `split` Commission[] - `id` integer - `splitPayType` 'TEAM' | 'AGENT' | 'VENDOR_PARTNER' | 'LEAD' | 'OTHER' | 'BROKERAGE' | 'UPLINE' - `splitPayTo` integer - `splitPayToName` string - `payType` 'TEAM' | 'AGENT' | 'VENDOR_PARTNER' | 'LEAD' | 'OTHER' | 'BROKERAGE' | 'UPLINE' - `payTo` integer - `payToName` string - `value` integer - `calculateType` 'PERCENT' | 'AMOUNT' - `desc` string - `postSplit` Commission[] - `id` integer - `splitPayType` 'TEAM' | 'AGENT' | 'VENDOR_PARTNER' | 'LEAD' | 'OTHER' | 'BROKERAGE' | 'UPLINE' - `splitPayTo` integer - `splitPayToName` string - `payType` 'TEAM' | 'AGENT' | 'VENDOR_PARTNER' | 'LEAD' | 'OTHER' | 'BROKERAGE' | 'UPLINE' - `payTo` integer - `payToName` string - `value` integer - `calculateType` 'PERCENT' | 'AMOUNT' - `desc` string - `tagsRemove` string[] — 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. - `clearAllTags` boolean — Set to `true` to remove ALL tags from the lead. Takes precedence over `tags` / `tagsAdd` / `tagsRemove`. Defaults to `false` (no change). ## Response `200` Lead updated. - LeadIdResponse — Response containing the lead ID. - `leadId` integer — ID of the lead. ## Other responses - `400` — Invalid parameters (20012 INVALID_PARAMETER); `property` block supplied with every address field blank (200057 PROPERTY_ADDRESS_EMPTY). - `401` — Missing or invalid authentication token. - `404` — Lead does not exist or is not accessible (20006 LEAD_NOT_EXIST); supplied `property.id` does not belong to this lead (200108 LEAD_PROPERTY_NOT_EXIST). - `500` — Internal server error. --- [API](https://skmtc.net/lofty/apis/lofty-service-open-apis.md) · [All operations](https://skmtc.net/lofty/apis/lofty-service-open-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lofty/lofty-service-open-apis/revisions/23e640467118/schema)