---
title: "Gets a paginated list of Leads"
method: GET
path: "/leads"
tags: ["Leads"]
---

# Gets a paginated list of Leads

`GET /leads`

## Request

- Base URL: `https://api.alto.zoopladev.co.uk`
- URL: `https://api.alto.zoopladev.co.uk/leads`
- Auth: `appAuth` (a scheme the document does not define)

Retrieves a paginated list of leads in the requested state of processing for a given AgencyRef and all permissible branches.
Required scope: alto/read:leads

## Query parameters

- `modified-from` string, date-time
- `modified-to` string, date-time
- `lead-status` 'Unspecified' | 'Unprocessed' | 'Processed' | 'Rejected' | 'Accepted'
- `enquiry-from` string, date-time
- `enquiry-to` string, date-time
- `next-token` string
- `max-results` integer

## Headers

- `AgencyRef` string, required

## Response `200`

OK

- LeadPagedResponse: Represents a paged response containing metadata and a collection of items.
  - `meta` Meta
    - `nextToken` string, nullable
    - `previousToken` string, nullable
  - `items` Lead[], nullable: The collection of items in the response.
    - `id` string, nullable: The unique identifier of the lead
    - `branchId` string, nullable: The identifier of the branch the lead belongs to
    - `leadStatus` 'Unspecified' | 'Unprocessed' | 'Processed' | 'Rejected' | 'Accepted'
    - `leadSource` 'Unspecified' | 'Agent' | 'RightMove' | 'Vebra' | 'Zoopla' | 'Api' | 'ZooplaAdReachExpress' | 'ZooplaAudienceConnect'
    - `enquiryDate` string, date-time: The date and time in ISO 8601 format that the lead enquired
    - `createdDate` string, date-time: The date and time in ISO 8601 format that the lead was imported into Alto eg. the status of the lead has changed to "Processed"
    - `modifiedDate` string, date-time: The date and time in ISO 8601 format that the lead was last modified eg. the status of the lead has changed from "Processed" to "Accepted"
    - `enquiryType` 'Unspecified' | 'LookingToBuy' | 'LookingToLet' | 'LookingToRent' | 'LookingToSell' | 'Other'
    - `enquirerDetails` EnquirerDetails: The lead's enquirer contact details that have been submitted as part of the enquiry;
      - `title` string, nullable: The formal title of the enquirer
      - `forename` string, nullable: The first or given name of the enquirer
      - `surname` string, nullable: The surname of the enquirer
      - `phoneNumberDay` string, nullable: The day time phone number of the enquirer
      - `phoneNumberEve` string, nullable: The evening phone number of the enquirer
      - `email` string, nullable: The email address of the enquirer
      - `address` EnquirerAddress: Represents a physical address of the enqurier
        - `houseName` string, nullable: The house or flat name of the enquirer's address
        - `houseNumber` string, nullable: The house or flat number of the enquirer's address
        - `street` string, nullable: The street of the enquirer's address
        - `locality` string, nullable: The locality of the enquirer's address
        - `area` string, nullable: The area of the enquirer's address
        - `town` string, nullable: The town or city of the enquirer's address
        - `county` string, nullable: The county of the enquirer's address
        - `country` string, nullable: The country of the enquirer's address
        - `postcode` string, nullable: The postal code of the enquirer's addres
    - `contact` Contact: A contact that has been associated to the lead; if no contact has been associated to a lead, then will return null
      - `id` string, nullable: The unique identifier of the contact
      - `links` Link[], nullable: Links to related contact.
        - `href` string, nullable
        - `rel` string, nullable
    - `properties` Property[], nullable: A collection of properties that the lead has enquired against; if no properties have been enquired against, then returns an empty collection
      - `id` string, nullable: The unique identifier of the property
      - `links` Link[], nullable: Links to related property.
        - `href` string, nullable
        - `rel` string, nullable
    - `comment` string, nullable: Comment or note for the lead

## Other responses

- `400`: Validation error i.e. invalid date range or missing branch level activation.
- `401`: Unauthorized
- `403`: Invalid scope or AgencyRef for request.
- `500`: Internal Server Error

---

[API](https://skmtc.dev/alto/apis/alto-api.md) - [All operations](https://skmtc.dev/alto/apis/alto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/alto/apis/alto-api/revisions/1b729d9b15a8?raw)