Zoopla Products API

openapi: 3.2.0
info:
  title: Zoopla Products API
  version: 1.0.0
  contact:
    name: Zoopla Pro P&A Team
    url: https://www.zoopla.co.uk/
    email: purchaseandactivationteam@zoopla.co.uk
  description: 'Operations tagged Products across 2 of this provider''s published API definitions: zoopla-premium-listing-activations-openapi.json, zoopla-weekly-featured-property-activations-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://services.zoopla.co.uk
security:
- oAuthSample:
  - api/api_access
tags:
- name: Products
paths:
  /products/premium-listings/{uuid}:
    get:
      summary: Returns listing for specific uuid
      description: 'If the UUID exists, it  will return a premium listing, if it does not or if it is an invalid UUID it will return an error

        '
      parameters:
      - in: path
        name: uuid
        schema:
          type: string
        required: true
        description: Returns premium listing for a given uuid
      responses:
        '200':
          description: OK. Request body contains premium listing for a given UUID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PremiumListing'
        '404':
          description: Not found. Premium listing doesn't exist or client doesn't have access to it
        '500':
          description: Internal Server Error
      tags:
      - Products
    patch:
      summary: Updates highlights for a specific uuid
      description: 'If the highlights are valid and the premium listing is `ACTIVE` and not currently awaiting an existing update it will return the premium listing with a `WAITING_FOR_UPDATE` status. If the highlights are invalid, the premium listing is not currently `ACTIVE` or the listing is already `WAITING_FOR_UPDATE` it will return the appropriate error.

        '
      parameters:
      - in: path
        name: uuid
        schema:
          type: string
        required: true
        description: The uuid for the premium listing that the caller is trying to update
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateHighlights'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PremiumListing'
          description: Accepted. We are trying to update highlights on your premium listing. Please check the result soon.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Bad request. Something wrong with the request, for example invalid highlights provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Forbidden client error, for example, no access to branch.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Internal Server Error
      tags:
      - Products
    servers:
    - url: https://services.zoopla.co.uk
  /products/premium-listings:
    get:
      summary: Returns all requested upgrades to premium listings that the caller has access to
      description: 'If no parameters are given, the response will return all premium listings for the caller. If the response is an **empty** array it means that there are no premium listings for the caller, activated or not. If the caller needs to filter premium listings, we provide the below query parameters.

        '
      parameters:
      - in: query
        name: listingId
        schema:
          type: string
        required: false
        description: 'The Zoopla internal listingId to return activation requests for. If listingId and customerListingId are provided together it will return an `error`. If no listingId is given it will return all premium listing activations.

          '
      - in: query
        name: customerListingId
        schema:
          type: string
        required: false
        description: 'An optional parameter which is a customer identifier of a listingId which Zoopla can match to an internal listingId. If the customerListingId cannot be matched to a listingId it will return an `error`. If customerListingId and listingId are provided together it will return an `error`.

          '
      - in: query
        name: date_from
        schema:
          type: string
        required: false
        description: 'And optional parameter to filter response by created date starting from date provided. An RFC3339 time format is required. E.g 2022-02-11T14:14:10.776Z

          '
      - in: query
        name: date_to
        schema:
          type: string
        required: false
        description: "And optional parameter to filter response by created date ending with the date provided. An RFC3339 time format is required. E.g 2022-02-11T14:14:10.776Z      \n"
      responses:
        '200':
          description: OK. Request body contains the list of requested upgrades to premium listing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PremiumListings'
        '400':
          description: Bad request. There was something wrong with the request, for example both listingId and customerListingId provided together
        '500':
          description: Internal Server Error
      tags:
      - Products
    post:
      summary: Create the new upgrade to premium listing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePremiumListing'
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
                description: Location of the created activation
                example: https://{server}/premium-listings/{uuid}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PremiumListing'
          description: Accepted. We are trying to make your listing premium. Please check the result soon.
        '303':
          headers:
            Location:
              schema:
                type: string
                description: Location of the existing activation
                example: https://{server}/premium-listings/{uuid}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PremiumListing'
          description: See other. A premium listing for this listing Id already exists and is either pending or already activated. See location of existing activation.
        '400':
          description: Bad request. Something wrong with the request, for example listing_id not provided.
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Payload too large. There was something wrong with the request for example, customDetails data exceeds max memory limit.
        '500':
          description: Internal Server Error
      tags:
      - Products
    servers:
    - url: https://services.zoopla.co.uk
  /products/weekly-featured-properties/{uuid}:
    get:
      summary: Returns a WFP activated listing for a specific uuid
      description: 'if the uuid exists will return a WFP listing, if it does not or it is an invalid UUID will return an error

        '
      parameters:
      - in: path
        name: uuid
        schema:
          type: string
        required: true
        description: returns the WFP for a given uuid
      responses:
        '200':
          description: OK. Request body contains the WFP for the given UUID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklyFeaturedProperty'
        '404':
          description: Not found. WFP doesn't exist or client doesn't have access to it
        '500':
          description: Internal Server Error
      tags:
      - Products
    servers:
    - url: https://services.zoopla.co.uk
  /products/weekly-featured-properties:
    get:
      summary: Returns all requested upgrades to WFPs that the caller has access to
      description: 'If no parameters are given, the response will return all WFPs for the caller. If the response is an **empty** array it means that there are no WFPs for the caller, activated or not. If the caller needs to filter WFPs, we provide the below query parameters.

        '
      parameters:
      - in: query
        name: listingId
        schema:
          type: string
        required: false
        description: 'The Zoopla internal listingId to return activation requests for. If listingId and customerListingId are provided together it will return an `error`. If no listingId is given it will return all WFP activations.

          '
      - in: query
        name: customerListingId
        schema:
          type: string
        required: false
        description: 'An optional parameter which is a customer identifier of a listingId which Zoopla can match to an internal listingId. If the customerListingId cannot be matched to a listingId it will return an `error`. If customerListingId and listingId are provided together it will return an `error`.

          '
      - in: query
        name: date_from
        schema:
          type: string
        required: false
        description: 'And optional parameter to filter response by created date starting from date provided. An date only format (YYYY-MM-DD) is required. E.g 2022-02-11

          '
      responses:
        '200':
          description: OK. Request body contains the list of requested upgrades to WFP.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklyFeaturedProperties'
        '400':
          description: Bad request. There was something wrong with the request, for example both listingId and customerListingId provided together
        '500':
          description: Internal Server Error
      tags:
      - Products
    post:
      summary: Activate a listing as a WFP
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWeeklyFeaturedProperty'
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
                description: Location of the created activation
                example: https://{server}/weekly-featured-properties/{uuid}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklyFeaturedProperty'
          description: Accepted. We are processing your request to make your listing a WFP. Please check the result soon.
        '303':
          headers:
            Location:
              schema:
                type: string
                description: Location of the existing activation
                example: https://{server}/weekly-featured-properties/{uuid}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors_2'
          description: See other. A WFP listing for this listingId already exists and is either pending or already activated. See location of existing activation.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors_2'
          description: Bad request. The was something wrong with the request, for example listingId not provided.
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors_2'
          description: Payload too large. There was something wrong with the request for example, customDetails data exceeds max memory limit.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors_2'
          description: Internal Server Error
      tags:
      - Products
    servers:
    - url: https://services.zoopla.co.uk
components:
  schemas:
    PremiumListings:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            format: uuid
            readOnly: true
          listingId:
            type: number
            example: 1234
            description: an internal zoopla identifier for a given listing which determines which listing should be made premium.
          createdAt:
            type: string
            format: date-time
            readOnly: true
          updatedAt:
            type: string
            format: date-time
            readOnly: true
          createdBy:
            type: string
            readOnly: true
            description: unique client identifier
          status:
            $ref: '#/components/schemas/PremiumListing/properties/status'
            x-miro: /builds/13667159605/api-premium-listings/docs/api/schemas/Status.yaml
          expiryAt:
            type: string
            format: date-time
            description: ISO-8601 date when the premium listing stops being premium
            readOnly: true
          highlights:
            $ref: '#/components/schemas/PremiumListing/properties/highlights'
            x-miro: /builds/13667159605/api-premium-listings/docs/api/schemas/Highlights.yaml
          customDetails:
            type: object
            description: So customers can store additional information about a product activation - for example - CRM identifier or order number.
        required:
        - listingId
    Status:
      type: object
      description: 'Status of request with error response

        '
      properties:
        result:
          type: string
          enum:
          - PENDING
          - ACTIVATED
          - DEACTIVATED
          - SCHEDULED
          - ERROR
          example: ERROR
        currently:
          type: string
          enum:
          - WAITING_FOR_UPDATE
          - LAST_UPDATE_FAILED
          example: WAITING_FOR_UPDATE
        errors:
          type: object
          properties:
            errors:
              type: array
              items:
                $ref: '#/components/schemas/Errors/properties/errors/items'
                x-miro: /builds/13667159605/api-premium-listings/docs/api/schemas/ServiceError.yaml
    PremiumListing:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        listingId:
          type: number
          example: 1234
          description: an internal zoopla identifier for a given listing which determines which listing should be made premium.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          type: string
          readOnly: true
          description: unique client identifier
        status:
          type: object
          description: 'Status of request with error response

            '
          properties:
            result:
              type: string
              enum:
              - PENDING
              - ACTIVATED
              - DEACTIVATED
              - SCHEDULED
              - ERROR
              example: ERROR
            currently:
              type: string
              enum:
              - WAITING_FOR_UPDATE
              - LAST_UPDATE_FAILED
              example: WAITING_FOR_UPDATE
            errors:
              $ref: '#/components/schemas/Status/properties/errors'
              x-miro: /builds/13667159605/api-premium-listings/docs/api/schemas/Errors.yaml
        expiryAt:
          type: string
          format: date-time
          description: ISO-8601 date when the premium listing stops being premium
          readOnly: true
        highlights:
          type: array
          items:
            $ref: '#/components/schemas/Highlights/items'
            x-miro: /builds/13667159605/api-premium-listings/docs/api/schemas/Highlight.yaml
        customDetails:
          type: object
          description: So customers can store additional information about a product activation - for example - CRM identifier or order number.
      required:
      - listingId
    UpdateHighlights:
      type: object
      properties:
        highlights:
          $ref: '#/components/schemas/CreatePremiumListing/properties/highlights'
          x-miro: /builds/13667159605/api-premium-listings/docs/api/schemas/HighlightsRequest.yaml
      required:
      - highlights
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            description: 'The possible errors:

              * **1011003** - 101 premium listing api, severity level 1, code 003 create premium listing invalid request

              '
            properties:
              reason:
                type: string
                description: The human readable reason of failure
                example: JSON schema requirements not met
              code:
                type: integer
                description: Comprising of the service identifier, severity and custom error code
                example: 1011003
    HighlightsRequest:
      type: array
      items:
        type: object
        description: 'highlighted feature of a premium listing

          '
        properties:
          id:
            type: integer
          description:
            type: string
        required:
        - id
    Highlights:
      type: array
      items:
        type: object
        description: 'highlighted feature of a premium listing

          '
        properties:
          id:
            type: integer
          description:
            type: string
          key:
            type: string
        required:
        - id
    CreatePremiumListing:
      type: object
      properties:
        listingId:
          type: number
          description: an internal zoopla identifier for a given listing which determines which listing should be made premium.
        customerListingId:
          type: string
          example: 100219_CHS108334
          description: an customer identifier of listing id (it has to be provided during listing creation) Zoopla is aware of.
        highlights:
          type: array
          items:
            $ref: '#/components/schemas/HighlightsRequest/items'
            x-miro: /builds/13667159605/api-premium-listings/docs/api/schemas/HighlightRequest.yaml
        customDetails:
          type: object
          description: So customers can store additional information about a product activation - for example - CRM identifier or order number.
    Status_2:
      type: object
      description: 'Status of request with error response

        '
      properties:
        result:
          type: string
          enum:
          - PENDING
          - ACTIVATED
          - DEACTIVATED
          - SCHEDULED
          - ERROR
          example: ERROR
        errors:
          type: object
          properties:
            errors:
              type: array
              items:
                $ref: '#/components/schemas/Errors/properties/errors/items'
                x-miro: /builds/13634493756/api-weekly-featured-properties/docs/api/schemas/ServiceError.yaml
    Errors_2:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            description: 'The possible errors:

              * **2011003** - 201 WFP API, severity level 1, code 003 activate WFP invalid request

              '
            properties:
              reason:
                type: string
                description: The human readable reason of failure
                example: JSON schema requirements not met
              code:
                type: integer
                description: Comprising of the service identifier, severity and custom error code
                example: 2011003
    WeeklyFeaturedProperties:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            format: uuid
            readOnly: true
          listingId:
            type: number
            example: 1234
            description: an internal zoopla identifier for a given listing which determines which listing should be made a WFP.
          createdAt:
            type: string
            format: date-time
            readOnly: true
          updatedAt:
            type: string
            format: date-time
            readOnly: true
          createdBy:
            type: string
            readOnly: true
            description: unique client identifier
          startAt:
            type: string
            format: date-time
            description: ISO-8601 date when the listing begins being a WFP
          expiryAt:
            type: string
            format: date-time
            description: ISO-8601 date when the listing stops being a WFP
          isRenewable:
            type: boolean
            description: Can listing be renewed
            readOnly: true
          status:
            $ref: '#/components/schemas/WeeklyFeaturedProperty/properties/status'
            x-miro: /builds/13634493756/api-weekly-featured-properties/docs/api/schemas/Status.yaml
          customDetails:
            type: object
            description: So customers can store additional information about a product activation - for example - CRM identifier or order number.
        required:
        - expiryAt
        - startAt
        - listingId
    CreateWeeklyFeaturedProperty:
      type: object
      properties:
        listingId:
          type: number
          example: 1234
          description: An internal zoopla identifier for a given listing which determines which listing should be activated as a WFP.
        customerListingId:
          type: string
          example: 100219_CHS108334
          description: A customer identifier of listing id which Zoopla is aware of (it has to be provided during the listing creation).
        customDetails:
          type: object
          description: So customers can store additional information about a product activation - for example - CRM identifier or order number.
    WeeklyFeaturedProperty:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        listingId:
          type: number
          example: 1234
          description: an internal zoopla identifier for a given listing which determines which listing should be made a WFP.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          type: string
          readOnly: true
          description: unique client identifier
        startAt:
          type: string
          format: date-time
          description: ISO-8601 date when the listing begins being a WFP
        expiryAt:
          type: string
          format: date-time
          description: ISO-8601 date when the listing stops being a WFP
        isRenewable:
          type: boolean
          description: Can listing be renewed
          readOnly: true
        status:
          type: object
          description: 'Status of request with error response

            '
          properties:
            result:
              type: string
              enum:
              - PENDING
              - ACTIVATED
              - DEACTIVATED
              - SCHEDULED
              - ERROR
              example: ERROR
            errors:
              $ref: '#/components/schemas/Status/properties/errors'
              x-miro: /builds/13634493756/api-weekly-featured-properties/docs/api/schemas/Errors.yaml
        customDetails:
          type: object
          description: So customers can store additional information about a product activation - for example - CRM identifier or order number.
      required:
      - expiryAt
      - startAt
      - listingId
  securitySchemes:
    oAuthSample:
      type: oauth2
      description: This API uses OAuth 2 with the client credentials grant flow.
      flows:
        clientCredentials:
          tokenUrl: https://services-auth.services.zoopla.co.uk/oauth2/token
          scopes:
            api/api_access: access to the API
x-refined-from:
- zoopla-premium-listing-activations-openapi.json
- zoopla-weekly-featured-property-activations-openapi.json