---
title: "Get negotiator's appointments within a selected time range."
method: GET
path: "/appointments/negotiators"
tags: ["Appointments"]
---

# Get negotiator's appointments within a selected time range.

`GET /appointments/negotiators`

## Request

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

Retrieves a paginated list of the requested negotiator's appointments within the selected time range, grouped by negotiator.
Required scope: alto/read:appointments

## Query parameters

- `start-date` string, date-time, required
- `end-date` string, date-time, required
- `type-id` 'Unspecified' | 'General' | 'Valuation' | 'Viewing' | 'Communication' | 'InternalMessage' | 'Offer' | 'AgreedOffer' | 'Note' | 'AuditedChange' | 'StickyNote' | 'FinancialTransaction' | 'Marketing' | 'Creation' | 'SyncedEmail' | 'AccountingTransaction' | 'WorkOrderEvent' | 'TenancyEvent' | 'FollowUp' | 'PersonalInformationRequest' | 'TdsEvent' | 'SigningRequest' | 'MaintenanceRequest' | 'DocumentSharing' | 'ConveyancerReferral'
- `next-token` string
- `max-results` integer
- `negotiator-id` integer[], required

## Headers

- `AgencyRef` string, required

## Response `200`

Appointments retrieved for negotiator.

- ExternalPartnerUserAppointmentsPagedResponse: Represents a paged response containing metadata and a collection of items.
  - `meta` Meta
    - `nextToken` string, nullable
    - `previousToken` string, nullable
  - `items` ExternalPartnerUserAppointments[], nullable: The collection of items in the response.
    - `negotiatorId` integer: The unique identifier of the negotiator
    - `appointments` ExternalPartnerAppointment[], nullable: A collection of appointments belonging to the negotiator; if there are no appointments, then returns an empty collection
      - `id` integer: The unique identifier of the appointment
      - `instanceId` integer: The numeric instance of an appointment; this value is only greater than zero for general appointment types that are marked as recurring and represents the xth instance of a given appointment in a recurring series.
      - `type` 'Unspecified' | 'General' | 'Valuation' | 'Viewing' | 'Communication' | 'InternalMessage' | 'Offer' | 'AgreedOffer' | 'Note' | 'AuditedChange' | 'StickyNote' | 'FinancialTransaction' | 'Marketing' | 'Creation' | 'SyncedEmail' | 'AccountingTransaction' | 'WorkOrderEvent' | 'TenancyEvent' | 'FollowUp' | 'PersonalInformationRequest' | 'TdsEvent' | 'SigningRequest' | 'MaintenanceRequest' | 'DocumentSharing' | 'ConveyancerReferral': The type of the appointment
      - `startDate` string, date-time: The appointment start date and time, returned as a local (UK) diary time with no timezone offset.
      - `endDate` string, date-time: The appointment end date and time, returned as a local (UK) diary time with no timezone offset.
      - `createdDate` string, date-time: The appointment's creation date and time in ISO 8601 format
      - `modifiedDate` string, date-time: The appointment's last modified date and time in ISO 8601 format
      - `title` string, nullable: The title of the appointment. For general appointments this refers to the appointment entry type
      - `status` 'Unspecified' | 'NotYetBooked' | 'Active' | 'CancelledByOffice' | 'CancelledByOwner' | 'CancelledByApplicant' | 'CancelledByContact': The status of the appointment
      - `isCancelled` boolean: Indicates whether the appointment has a cancelled status; An appointment is only cancelled if the appointment status is not set to either Active or NotYetBooked
      - `negotiators` ExternalPartnerNegotiator[], nullable: A collection of negotiators associated with the appointment; if there are no negotiators, then returns an empty collection
        - `id` string, nullable: The unique identifier of the negotiator
        - `links` Link[], nullable: Links to related negotiator; NOTE: This is currently set to an empty collection as no api is currently available for retrieving negotiator details
          - `href` string, nullable
          - `rel` string, nullable
      - `properties` ExternalPartnerProperty[], nullable: A collection of properties that are associated with the appointment; if there are no properties, 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
      - `contacts` ExternalPartnerContact[], nullable: A collection of contacts that are associated with the appointment; if there are no contacts, then returns an empty collection
        - `id` string, nullable: The unique identifier of the contact
        - `links` Link[], nullable: Links to related contact.
          - `href` string, nullable
          - `rel` string, nullable
      - `viewingDetails` ExternalPartnerViewingDetails
        - `internalNotes` string, nullable: The internal notes of the appointment.
        - `applicantFeedback` string, nullable: The feedback of the appointment.

## Other responses

- `400`: Validation error e.g. invalid date range selection.
- `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)