--- title: "List Leads" method: GET path: "/v1.0/leads" tags: ["Leads"] --- # List Leads `GET /v1.0/leads` Returns a page of leads matching the supplied filters with pagination metadata. Notes: - limit must be in [1, 100]; otherwise 400 LIMIT_NOT_VALID. - Use offset for offset-based pagination or scrollId for cursor-based pagination. - Multiple filters are combined with AND logic; multi-value filters within a single parameter (e.g. allTags, anyTags) apply their documented AND / OR semantics. ## Query parameters - `stage` string - `source` string - `phone` string - `email` string - `assignedUserId` integer - `contacted` boolean - `groups` string - `segments` string - `allTags` string - `anyTags` string - `groupIds` integer - `querySubGroup` boolean - `scrollId` string - `offset` integer - `limit` integer - `sort` string - `desc` boolean - `languages` string - `preciseSearchFlag` boolean - `roleAssigneeFilters` string - `key` string - `otherFilters` string - `returnFields` string ## Headers - `Authorization` string, required ## Response `200` Page of matching leads with pagination metadata. - LeadListResponse - `get_metadata` MetaData — Pagination metadata (offset, limit, total, collection). - `collection` string — The element of the array - `limit` integer — Quantitative limitation of responded elements - `offset` integer — Start index of the responded elements - `total` integer — The sum of retrieved elements - `scrollId` string — Scroll ID for the search. You can then use the scroll ID to retrieve the next batch of results for the request. - `leads` 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 - `400` — Invalid parameters, such as limit out of range (LIMIT_NOT_VALID). - `401` — Missing or invalid authentication token. - `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)