> ## Documentation Index > Fetch the complete documentation index at: https://docs.myperch.io/llms.txt > Use this file to discover all available pages before exploring further. # List Leads for FirmMember > Gets a list of records from the Lead table based on passed parameters and implicit access controls. ## OpenAPI ````yaml https://perch-api-docs.s3.ca-central-1.amazonaws.com/perch-realtor.spec.json get /firmMembers/{id}/leads openapi: 3.1.0 info: title: Perch Realtor Web API version: v1 contact: name: API Support url: https://myperch.io email: support@myperch.io description: This is the API used by the Perch Realtor portal. servers: - description: DIT url: https://api.realtor.dit.myperch.io/v1 - description: Production url: https://api.realtor.myperch.io/v1 security: - x-api-key: [] tags: - name: Lead description: Operations involving Lead - name: Plan description: Operations involving Plan paths: /firmMembers/{id}/leads: get: tags: - Lead summary: List Leads for FirmMember description: >- Gets a list of records from the Lead table based on passed parameters and implicit access controls. operationId: get-leads-for-firm-members parameters: - in: path name: id description: The id of the record to retrieve. required: true schema: type: string example: abc123 responses: '200': description: Successful response content: application/json: schema: type: object properties: meta: type: object properties: totalCount: type: integer description: Number of records found by the query example: 42 data: type: array items: $ref: '#/components/schemas/Lead' example: - id: 38owigkM createdAt: '2026-03-05T19:39:18.389Z' updatedAt: '2026-03-05T19:39:18.389Z' deletedAt: null email: client1+74049788@example.com firstName: Amya lastName: Williamson phone: number: '2925655632' extension: '562' clientData: sin: '004877852' prefix: Ms. citizenship: Permanent Legal Resident (PR) dateOfBirth: '1987-07-13' maritalStatus: Married creditScoreEstimation: '142' resourceType: Firm resourceId: qSBKZzUi referredByReferralCodeId: null convertedAt: null - id: t2ad2aop createdAt: '2026-03-05T19:39:18.389Z' updatedAt: '2026-03-05T19:39:18.389Z' deletedAt: null email: client1+82482959@example.com firstName: Titus lastName: Wiza phone: number: '8069012246' extension: '267' clientData: sin: '307055768' prefix: Mr. citizenship: Student VISA dateOfBirth: '1991-07-13' maritalStatus: Single creditScoreEstimation: '210' resourceType: Firm resourceId: nzM7Xffc referredByReferralCodeId: null convertedAt: null components: schemas: Lead: type: object properties: id: type: string description: Unique identifier for the record example: 38owigkM createdAt: type: string format: date-time description: Date and time the record was created example: '2026-03-05T19:39:18.389Z' updatedAt: type: string format: date-time description: Date and time the record was last updated example: '2026-03-05T19:39:18.389Z' deletedAt: type: - string - 'null' format: date-time description: Date and time the record was soft deleted email: type: string format: email description: The client's email address example: client1+74049788@example.com firstName: type: string description: The client's first name example: Amya lastName: type: string description: The client's last name example: Williamson phone: type: - object - 'null' description: The client's phone number properties: number: type: string description: Phone number without country code extension: type: string description: Phone number extension nullable: true required: - number clientData: type: - object - 'null' description: The user data for the lead properties: advisorProfileId: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The Perch ID of the advisor (a FirmMember with a 'Advisory' firmType) that the client is working with. nullable: true citizenship: type: string enum: - Canadian Citizen - Permanent Legal Resident (PR) - Work VISA - Other - Student VISA description: The client's citizenship status. See enum for available types. nullable: true example: Canadian Citizen creditScoreEstimation: type: string pattern: ^[0-9]{3}$ description: >- The client's credit score estimation. This should be a 3 digit number. nullable: true example: '700' dateOfBirth: type: string format: date description: The client's date of birth. nullable: true example: '1980-01-01' isFirstTimeHomeBuyer: type: boolean description: Whether or not the client is a first time home buyer. nullable: true example: true maritalStatus: type: string enum: - Married - Single - Common-Law - Divorced - Widowed - Separated description: The client's marital status. See enum for available types. nullable: true example: Married prefix: type: string enum: - Mr. - Mrs. - Ms. description: The client's prefix / title. See enum for available types. nullable: true example: Mrs. sin: type: string pattern: ^[0-9]{9}$ description: >- The client's social insurance number. This should be a 9 digit number. nullable: true example: '123456789' Assets: type: array items: type: object properties: type: type: string enum: - Savings - Investment - Vehicle - Purchase Deposit - Gifted Funds - Other description: Type of the non-property asset example: Savings description: type: string description: Description of the asset example: Savings account at RBC value: type: string pattern: ^\d+(\.\d{1,2})?$ description: The value of the asset in CAD example: 10000 required: - description - type - value additionalProperties: false description: Assets of the Lead. nullable: true Incomes: type: array items: type: object properties: type: description: The type of the income. type: string enum: - Canada Child Benefit - Child Support - Disability - Employer Pension - Employment - Old Age Security - Other - Pension - Rental - Self-Employment - Spousal Support - Unemployment example: Employment startedOn: description: Date the client started receiving the income. type: string format: date example: '2018-01-01' endedOn: description: Date the client stopped receiving the income. type: string format: date nullable: true example: '2022-12-31' description: description: Description of the income. (Employer name, etc.) type: string nullable: true example: Cyberdyne Systems streams: type: object description: >- Income source details; separated by year. The key is the year and the value is an array of income streams for that year. (e.g. `{ "2026": [ { "type": "Base", "frequency": "Bi-weekly", "amount": "1000" } ] }`) patternProperties: ^[0-9]{4}$: type: array items: type: object properties: type: type: string enum: - Base - Additional - Total description: >- An income year must not include both “Base/Additional” and “Total” entries, and no duplicate entries of the same type are allowed. The “Total” income streams are strictly tied to a “Yearly” frequency, and for past years, only the “Total” type is valid. Special case: "Self-Employment" income for Corporations will use "Base/Additional" for the current year and past years Special case: "Employer Pension" income will use "Base/Additional" for the current year and past years example: Base frequency: type: string enum: - Weekly - Bi-Weekly - Monthly - Semi-Monthly - Quarterly - Yearly description: >- Frequency of the income (e.g. "Monthly", "Yearly", etc.) example: Bi-Weekly amount: type: string description: >- Amount of the income received at each interval. Expressed in CAD. example: '1000' required: - type - frequency - amount additionalProperties: false anyOf: - items: type: object properties: type: const: Total frequency: enum: - Yearly required: - type - frequency - amount minItems: 1 maxItems: 1 - items: type: object properties: type: const: Base required: - type - frequency - amount minItems: 1 maxItems: 1 - allOf: - contains: type: object properties: type: const: Base required: - type - frequency - amount - contains: type: object properties: type: const: Additional required: - type - frequency - amount minItems: 2 maxItems: 2 errorMessage: anyOf: >- An income year must include either one "Total" income stream, one "Base" income stream, or both "Base" and "Additional" income streams. nullable: true required: [] additionalProperties: false employmentDetails: type: object description: Employment information properties: type: type: string enum: - Salaried - Hourly - Contract description: Type of employment. example: Salaried jobTitle: type: string description: Job title of the client at their place of employment. example: Accountant phone: type: object description: Phone number of the client's place of employment. properties: number: type: string description: Phone number without country code extension: type: string description: Phone number extension nullable: true additionalProperties: false required: - number example: '{"number":"6471234567","extension":"123"}' sector: type: string enum: - Agriculture - Arts & Entertainment - Construction - Educational Services - Financial Services - Healthcare - IT & Telecom - Manufacturing - Natural Resources - Public Services - Real Estate & Property Management - Retail & Wholesale - Science & Technology - Transportation - Travel & Tourism - Utilities - Student - Other description: The economic sector of the client's place of work. example: Financial Services businessType: type: string enum: - Sole Proprietorship - Partnership - Corporation description: >- Type of business. Only applicable to self-employed clients. nullable: true example: Sole Proprietorship businessEstablishedOn: type: string format: date description: >- Date the business was established. Only applicable to self-employed clients. nullable: true example: '2019-01-01' businessAnnualGrossRevenue: type: string pattern: ^\d+(\.\d{1,2})?$ description: >- Annual gross revenue of the business. Only applicable to self-employed clients. nullable: true example: '10000' businessName: type: string description: >- Name of the business. Only applicable to self-employed clients. example: Acme Inc. probationEndsOn: type: string format: date description: >- The date the probation period ends at their place of employment. Only required for "Employment" income type. nullable: true example: '2022-01-01' address: type: object properties: unitNumber: type: string description: Address - Unit number nullable: true streetNumber: type: string description: Address - Street number nullable: true streetName: type: string description: Address - Street name including direction nullable: true locality: type: string description: Address - City, town, or village administrativeArea: type: string description: Address - State or province postalCode: type: string description: Address - Postal code or zip code country: type: string description: Address - Country name premise: type: string description: Address - Apartment, building, floor, etc. nullable: true googlePlaceId: type: string description: Google Place ID nullable: true locationGeometry: type: object description: >- Longitude and latitude stored as a point using SRID 4326 in GeoJSON format: [longitude, latitude] example: '{"type":"Point","coordinates":[-79.3832,43.6532]}' properties: type: type: string const: Point coordinates: type: array description: Longitude first, then latitude items: type: number minItems: 2 maxItems: 2 required: - type - coordinates nullable: true additionalProperties: false required: [] additionalProperties: false nullable: true required: - type - jobTitle - phone - sector - businessName - address additionalProperties: false required: - type - startedOn additionalProperties: false if: anyOf: - properties: type: const: Employer Pension - properties: type: const: Self-Employment employmentDetails: properties: businessType: const: Corporation then: properties: streams: $schema: http://json-schema.org/draft-07/schema# type: object description: >- Income source details; separated by year. The key is the year and the value is an array of income streams. example: '2026': - type: Base frequency: Bi-Weekly amount: 1000 - type: Additional frequency: Quarterly amount: 100 patternProperties: ^[0-9]{4}$: type: array items: type: object properties: type: type: string enum: - Base - Additional description: >- Income streams for Corporate Business Self-Employment or Employer Pension must have a "Base" and "Additional" stream. example: Base frequency: type: string enum: - Weekly - Bi-Weekly - Monthly - Semi-Monthly - Quarterly - Yearly description: >- Frequency of the income (e.g. "Monthly", "Yearly", etc.) example: Bi-Weekly amount: type: number description: >- Amount of the income received at each interval. Expressed in CAD. example: 1000 required: - type - frequency - amount additionalProperties: false nullable: true required: [] additionalProperties: false nullable: true ClientResidencies: type: array items: type: object properties: occupancyType: description: >- The status of the client's residency. Residers do not own or rent the property. type: string enum: - Owner - Renter - Resider example: Resider startsOn: description: Date the client moved into the location type: string format: date example: '2018-01-01' endsOn: description: Date the client moved out of the location type: string format: date nullable: true example: '2022-12-31' monthlyRent: description: The monthly rent amount when occupancyType is "Renter" type: string pattern: ^\d+(\.\d{1,2})?$ nullable: true example: 2000 unitNumber: type: string description: Address - Unit number nullable: true streetNumber: type: string description: Address - Street number nullable: true streetName: type: string description: Address - Street name including direction nullable: true locality: type: string description: Address - City, town, or village administrativeArea: type: string description: Address - State or province postalCode: type: string description: Address - Postal code or zip code country: type: string description: Address - Country name premise: type: string description: Address - Apartment, building, floor, etc. nullable: true googlePlaceId: type: string description: Google Place ID nullable: true locationGeometry: type: object description: >- Longitude and latitude stored as a point using SRID 4326 in GeoJSON format: [longitude, latitude] example: '{"type":"Point","coordinates":[-79.3832,43.6532]}' properties: type: type: string const: Point coordinates: type: array description: Longitude first, then latitude items: type: number minItems: 2 maxItems: 2 required: - type - coordinates nullable: true additionalProperties: false required: - occupancyType - startsOn - locality - country - postalCode - administrativeArea additionalProperties: false nullable: true Plans: type: array items: type: object required: - type additionalProperties: false properties: id: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The readonly ID of the plan. This will get set when the plan is created. nullable: true leadId: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The ID of the lead that the plan is associated with. This will get set when the plan is created. nullable: true referralCodeId: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The id of a Perch referral code that should be applied to the plan. This should be either the partner or realtor referral code. nullable: true type: type: string enum: - Switching - Renewing - Refinancing - Buying description: The type of the plan. See enum for available types. example: Buying realtorProfileId: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The Perch ID of the realtor (a FirmMember with a 'Realty' firmType) that the client is working with. This is only allowed for "Buying" plans. nullable: true oneOf: - title: LeadBuyingPlan type: object required: - type additionalProperties: false properties: id: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The readonly ID of the plan. This will get set when the plan is created. nullable: true leadId: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The ID of the lead that the plan is associated with. This will get set when the plan is created. nullable: true referralCodeId: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The id of a Perch referral code that should be applied to the plan. This should be either the partner or realtor referral code. nullable: true type: type: string enum: - Buying description: The type of the plan. See enum for available types. example: Buying realtorProfileId: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The Perch ID of the realtor (a FirmMember with a 'Realty' firmType) that the client is working with. This is only allowed for "Buying" plans. nullable: true - title: LeadManagePlan type: object required: - type additionalProperties: false properties: id: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The readonly ID of the plan. This will get set when the plan is created. nullable: true leadId: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The ID of the lead that the plan is associated with. This will get set when the plan is created. nullable: true referralCodeId: type: string pattern: ^[a-zA-Z0-9]{8}$ description: >- The id of a Perch referral code that should be applied to the plan. This should be either the partner or realtor referral code. nullable: true type: type: string enum: - Switching - Renewing - Refinancing description: The type of the plan. See enum for available types. example: Renewing description: Plans associated with the Lead. nullable: true Properties: type: array items: type: object properties: type: type: string enum: - Detached - Condo/Apartment - Townhouse - Semi-Detached - Other description: The type of the property. example: Detached status: type: string enum: - Purchasing - Owned - Selling - Sold - Shortlisted description: Current state of the property example: Owned occupancyType: type: string enum: - Owner Occupied - Rental - Owner Occupied & Rental - Second Home description: The status of the occupant's residency example: Owner Occupied purchasePrice: type: string pattern: ^\d+(\.\d{1,2})?$ description: The purchase price of the property in CAD nullable: true example: 500000 purchasedOn: type: string format: date description: >- The date the agreement to purchase the property was accepted nullable: true example: '2018-01-01' monthlyTotalRent: type: string pattern: ^\d+(\.\d{1,2})?$ description: Rental income from Property nullable: true example: 2000 costs: type: object properties: annualPropertyTaxes: type: number description: The annual property taxes for the property in CAD nullable: true monthlyMaintenanceFee: type: number description: >- The monthly maintenance fee for condos/townhouses in CAD nullable: true unitNumber: type: string description: Address - Unit number nullable: true streetNumber: type: string description: Address - Street number nullable: true streetName: type: string description: Address - Street name including direction nullable: true locality: type: string description: Address - City, town, or village administrativeArea: type: string description: Address - State or province postalCode: type: string description: Address - Postal code or zip code country: type: string description: Address - Country name premise: type: string description: Address - Apartment, building, floor, etc. nullable: true googlePlaceId: type: string description: Google Place ID nullable: true locationGeometry: type: object description: >- Longitude and latitude stored as a point using SRID 4326 in GeoJSON format: [longitude, latitude] example: '{"type":"Point","coordinates":[-79.3832,43.6532]}' properties: type: type: string const: Point coordinates: type: array description: Longitude first, then latitude items: type: number minItems: 2 maxItems: 2 required: - type - coordinates nullable: true additionalProperties: false Liabilities: type: array items: type: object properties: type: type: string enum: - Alimony - Car Lease - Car Finance - Child Support - Condo Fees - Heating Costs - HELOC - Mortgage - Personal Loan - Property Tax - Student Loan - Unsecured Line of Credit - Other description: The type of the liability. balance: type: string pattern: ^\d+(\.\d{1,2})?$ description: The current balance of the liability. creditLimit: type: string pattern: ^\d+(\.\d{1,2})?$ description: >- The original balance of mortgages or the credit limit for other loan types. description: type: string description: A helpful description of the liability. nullable: true lenderName: type: string description: The name of the lender. maturesOn: type: string format: date description: Date the liability matures. paymentAmount: type: string pattern: ^\d+(\.\d{1,2})?$ description: Payment amount at each payment interval. paymentDetails: type: object properties: isInterestOnly: type: boolean description: Whether or not the payment is interest only. isPropertyTaxIncluded: type: boolean description: >- Whether or not the payment includes property tax. This indicates the lender is responsible for paying the property tax. This affects the calculation of the payment amount and amortization years. required: - isInterestOnly - isPropertyTaxIncluded additionalProperties: false paymentFrequency: type: string enum: - Weekly - Bi-Weekly - Monthly - Semi-Monthly - Quarterly - Yearly description: Payment frequency of the liability. rate: type: number description: >- Loan: Either the fixed interest rate or the prime offset (e.g. Prime +/- rate) for variable rateType: type: string enum: - Fixed - Variable - Adjustable description: Type of interest rate for a loan termMonths: type: number description: The term of the loan in months nullable: true position: type: integer description: >- The position of the liability. This is used to determine the order in which liabilities are paid off. This is almost exclusively used for mortgages. Position must be unique for each liability. nullable: true ChildLiabilities: type: array description: >- A ChildLiability is the HELOC in a Mortgage+HELOC combination. items: type: object properties: type: type: string enum: - HELOC description: A HELOC type in a Mortgage+HELOC combination. balance: type: string pattern: ^\d+(\.\d{1,2})?$ description: The current balance of the liability. creditLimit: type: string pattern: ^\d+(\.\d{1,2})?$ description: >- The original balance of mortgages or the credit limit for other loan types. description: type: string description: A helpful description of the liability. nullable: true lenderName: type: string description: The name of the lender. maturesOn: type: string format: date description: Date the liability matures. paymentAmount: type: string pattern: ^\d+(\.\d{1,2})?$ description: Payment amount at each payment interval. paymentDetails: type: object properties: isInterestOnly: type: boolean description: >- Whether or not the payment is interest only. isPropertyTaxIncluded: type: boolean description: >- Whether or not the payment includes property tax. This indicates the lender is responsible for paying the property tax. This affects the calculation of the payment amount and amortization years. required: - isInterestOnly - isPropertyTaxIncluded additionalProperties: false paymentFrequency: type: string enum: - Weekly - Bi-Weekly - Monthly - Semi-Monthly - Quarterly - Yearly description: Payment frequency of the liability. rate: type: number description: >- Loan: Either the fixed interest rate or the prime offset (e.g. Prime +/- rate) for variable rateType: type: string enum: - Fixed - Variable - Adjustable description: Type of interest rate for a loan termMonths: type: number description: The term of the loan in months nullable: true required: - type - balance - creditLimit - lenderName - maturesOn - paymentAmount - paymentDetails - paymentFrequency - rate - rateType additionalProperties: false nullable: true required: - type - balance - creditLimit - lenderName - maturesOn - paymentAmount - paymentDetails - paymentFrequency - rate - rateType additionalProperties: false allOf: - if: properties: type: const: Mortgage then: required: - termMonths - position nullable: true required: - type - status - occupancyType additionalProperties: false description: Properties owned by the Lead. nullable: true notes: description: Notes about the Lead type: string nullable: true required: [] resourceType: type: string description: The resource type of the lead owner enum: - ClientProfile - Firm - FirmMember example: Firm resourceId: type: string description: The resource ID of the lead owner example: qSBKZzUi referredByReferralCodeId: type: - string - 'null' description: >- Support only: The referral source of the lead. This referral source takes priority over the lead owner during lead conversion. convertedAt: type: - string - 'null' format: date-time description: >- The date the Lead was converted into a client. This is set when a client signs up or is created by an advisor / CX representative. required: - id - createdAt - updatedAt - email - firstName - lastName - resourceType - resourceId securitySchemes: x-api-key: name: x-api-key type: apiKey in: header ````