--- title: "Get Lead" method: GET path: "/v1.0/leads/{leadId}" tags: ["Leads"] --- # Get Lead `GET /v1.0/leads/{leadId}` ## Request - Base URL: `https://api.lofty.com` - URL: `https://api.lofty.com/v1.0/leads/{leadId}` - Auth: none required - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns a single lead by ID. The response is wrapped under the 'lead' key. Notes: - By default, trashed leads are not returned. Pass withTrash=true to include them. - Caller must have access to the lead; otherwise 404 LEAD_NOT_EXIST. ## Path parameters - `leadId` integer, required ## Query parameters - `withTrash` boolean ## Headers - `Authorization` string, required ## Response `200` Lead retrieved successfully. - LeadResponse - `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 - `leadId` integer: The Id of the lead - `leadUserId` integer: The user Id of the lead - `firstName` string: The first/given name of the lead - `lastName` string: The last/family name of the lead - `birthday` string: The birthday of the lead - `emails` string[]: The email list of the lead - `phones` string[]: The phone list of the lead - `leadSource` integer: The leadSource(Id) about the lead - `source` string: The source of the lead - `stageId` integer: The stageId of the lead - `stage` string: The stage of the lead - `assignedUserId` integer: The user Id of the lead assigned to - `assignedUser` string: The Username of the lead assigned to - `lenderUserId` integer: The user Id of the lead's lender - `score` integer: The score of the lead - `tags` UserLeadTagVo[]: The tags of the lead - `leadId` integer - `tagId` integer - `createTime` string - `updateTime` string - `tagName` string - `creatorUserId` integer - `visibleType` integer - `teamId` integer: The teamId of the lead's team - `streetAddress` string: The streetAddress associated with the lead. Deprecated: please use the streetAddress field in leadPropertyList instead. - `city` string: The city associated with the lead. Deprecated: please use the city field in leadPropertyList instead. - `state` string: The state associated with the lead. Deprecated: please use the state field in leadPropertyList instead. - `zipCode` string: The zip code associated with the lead. Deprecated: please use the zipCode field in leadPropertyList instead. - `createTime` string: The create time of the lead - `assignTime` string: The assigned time of the lead - `facebook` string: The Facebook account of the lead - `twitter` string: The Twitter account of the lead - `hiddenFlag` boolean: The lead is hidden or not - `referredBy` string: The referee of the lead - `leadInquiry` 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 - `leadPropertyList` LeadProperty[]: LeadPropertyList - `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) - `customAttributes` 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",...]} - `lastUpdateTime` string: The update time of the lead - `groups` string[]: The groups that the lead in. Deprecated, use segments instead. - `segments` string[]: The segments that the lead in - `unsubscription` boolean: Unsubscription the email - `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) - `lastTouch` string: The last touch time of the lead - `lastVisit` string: The last visit time of the lead - `phoneStatuses` integer[]: The status of the phone number Type id: invaild number(1), vaild number(2), talked(3), DNC Number(4), DNC Contact(5) - `assignCompletionStatus` boolean: Whether complete all lead assign process - `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`. - `opportunity` 'High Interest' | 'Sell' | 'Back to Site' | 'Back on Market': The lead's current opportunity type, derived from on-platform lead scoring. One of: "High Interest", "Sell", "Back to Site", "Back on Market". Null when the lead has no active opportunity. - `leadFamilyMemberList` LeadFamilyMember[]: A list of family members associated with the lead - `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) - `pondId` integer: The Id of the lead's pond - `pondName` string: The Name of the lead's pond - `customRoleList` CustomRole[] - `roleId` integer, required: The ID of this custom role - `role` string, required: The name of this custom role - `assigneeId` integer: The user id of this custom role - `assignee` string: The user account of this custom role - `language` string: The language of the lead - `ownershipId` integer: The entity ID associated with `ownershipScope`: the office ID when scope is `OFFICE`, or the agent's user ID when scope is `PERSONAL`. Not applicable when scope is `TEAM`. - `ownershipScope` string: The visibility scope of the lead. `TEAM` — Account-wide: visible to all users in this Lofty client account. `OFFICE` — visible only within a specific office. `PERSONAL` — visible only to a single agent. Note: `TEAM` refers to the entire client account (the organization), not the Lofty "Team add-on" product. ## Other responses - `401`: Missing or invalid authentication token. - `404`: Lead does not exist or is not accessible (20006 LEAD_NOT_EXIST). - `500`: Internal server error. --- [API](https://skmtc.dev/lofty/apis/lofty-service-open-apis.md) - [All operations](https://skmtc.dev/lofty/apis/lofty-service-open-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/lofty/apis/lofty-service-open-apis/revisions/23e640467118?raw)