Connells Group Branches API

openapi: 3.2.0
info:
  title: Connells Website JSON API (undocumented) Branches API
  version: '2026-07-26'
  summary: Read-only JSON endpoints served by the Connells estate agency website.
  description: 'This is NOT a published Connells Group product. Connells Group publishes no developer portal, no documentation and no specification of any kind. This document was DERIVED by API Evangelist purely from live, anonymous, unauthenticated HTTP probes of https://www.connells.co.uk/api on 2026-07-26, and every schema below is a faithful transcription of an observed response body — nothing was invented, and no field appears here that was not returned by the live service.


    The endpoints are Next.js App Router route handlers backing the www.connells.co.uk consumer site (branch finder, people directory, testimonials wall and location autocomplete). Content is sourced from the Homeflow estate-agency platform that powers the Connells consumer estate (asset URLs resolve to *.homeflow-assets.co.uk). They are unversioned, undocumented, carry no service-level commitment, are rate limited by Cloudflare (HTTP 429 with Retry-After) and may change or disappear without notice. Treat them as an observation of the estate, not as a contract.


    The sibling Connells Group brand sites (Hamptons, Sequence, Bairstow Eves, Fox & Sons, John D Wood, Blundells, Barnard Marcus, William H Brown) run the Homeflow Rails application directly and 302-redirect /api/* to their homepage; Countrywide 301-redirects; Gascoigne Halman 404s. Only www.connells.co.uk exposes these handlers.'
  x-provenance: api-evangelist-derived-from-live-probes
  x-published-by-provider: false
  x-probe-date: '2026-07-26'
servers:
- url: https://www.connells.co.uk/api
  description: Production (undocumented, unversioned, no SLA)
tags:
- name: Branches
  description: Connells branch (office) directory.
paths:
  /branches:
    get:
      operationId: listBranches
      summary: List Connells branches
      description: 'Returns the first page of the Connells branch directory. Observed 2026-07-26 as 162 branches across 14 pages of 12. No query parameter was honoured — page, pageSize, per_page, limit, lat, lng, search, q, query, slug, service, distance and isLettingsEnabled were each probed and all returned page 1 unchanged. OPTIONS reports "Allow: GET, HEAD, OPTIONS".'
      tags:
      - Branches
      security: []
      responses:
        '200':
          description: A page of branches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchListEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
  /branches/{branchId}:
    get:
      operationId: getBranch
      summary: Get one branch by numeric id
      description: 'Returns a single branch by its numeric id (observed: 8020 = Abingdon). The path segment must be the numeric id; passing the branch slug ("abingdon") returns HTTP 200 with a null result rather than a 404.'
      tags:
      - Branches
      security: []
      parameters:
      - name: branchId
        in: path
        required: true
        description: Numeric branch identifier, as returned by listBranches.
        schema:
          type: integer
        example: 8020
      responses:
        '200':
          description: The branch, or a null result when no branch matches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
  /properties:
    get:
      operationId: listProperties
      summary: Property listings (route present, non-functional)
      description: This route handler exists but returned HTTP 500 with an empty body on every probe on 2026-07-26 — bare, and with location, search, type and page query parameters. It is documented here only to record that the route is present and failing; no successful response has ever been observed, so no 200 schema is asserted. Property listings on www.connells.co.uk are server-rendered from the Homeflow platform, not fetched from this endpoint by the browser.
      tags:
      - Branches
      security: []
      responses:
        '500':
          description: Observed on every probe. Empty body.
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    BranchListEnvelope:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Branch'
        pagination:
          $ref: '#/components/schemas/Pagination'
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ApiError'
    BranchService:
      type: object
      description: A service line offered at a branch.
      properties:
        service:
          type: string
          example: Lettings
        phone_number:
          type:
          - string
          - 'null'
        fax_number:
          type:
          - string
          - 'null'
        email_address:
          type:
          - string
          - 'null'
        enabled:
          type:
          - boolean
          - 'null'
    ApiError:
      type: object
      properties:
        message:
          type: string
          example: Name required for places search
    Pagination:
      type: object
      description: Pagination envelope returned by the list endpoints.
      properties:
        totalCount:
          type: integer
          example: 162
        currentPage:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 12
        pageCount:
          type: integer
          example: 14
        hasPrevPage:
          type: boolean
        hasNextPage:
          type: boolean
    BranchEnvelope:
      type: object
      properties:
        result:
          oneOf:
          - $ref: '#/components/schemas/Branch'
          - type: 'null'
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ApiError'
    Branch:
      type: object
      description: A Connells branch (high-street office).
      properties:
        id:
          type: integer
          example: 8020
        slug:
          type: string
          example: abingdon
        name:
          type: string
          example: Abingdon
        mainPhoto:
          type:
          - string
          - 'null'
          format: uri
          description: Branch photograph, served from the Homeflow asset CDN.
        email:
          type:
          - string
          - 'null'
          format: email
        description:
          type:
          - string
          - 'null'
          description: Long-form marketing copy for the branch.
        lat:
          type:
          - number
          - 'null'
          example: 51.6701702207
        lng:
          type:
          - number
          - 'null'
          example: -1.2827574378
        displayAddress:
          type:
          - string
          - 'null'
          description: Newline-delimited postal address.
        contactTelephone:
          type:
          - string
          - 'null'
        urlLabel:
          type:
          - string
          - 'null'
        salesTelephone:
          type:
          - string
          - 'null'
        lettingsTelephone:
          type:
          - string
          - 'null'
        branchManager:
          oneOf:
          - $ref: '#/components/schemas/StaffMember'
          - type: 'null'
        services:
          type: array
          items:
            $ref: '#/components/schemas/BranchService'
        agencyId:
          type:
          - integer
          - 'null'
          example: 909
        isSalesEnabled:
          type:
          - boolean
          - 'null'
        isLettingsEnabled:
          type:
          - boolean
          - 'null'
        departments:
          type: array
          description: Observed empty on every record sampled.
          items:
            type: object
        distance:
          type:
          - number
          - 'null'
          description: Observed null; presumably populated by a proximity search.
        branchUrl:
          type:
          - string
          - 'null'
          example: /estate-agents/abingdon
    StaffMember:
      type: object
      description: A Connells colleague. The same shape is embedded as a branch's `branchManager`.
      properties:
        id:
          type: integer
          example: 23232373
        slug:
          type: string
          example: paul-barron
        name:
          type: string
          example: Paul Barron
        jobTitle:
          type:
          - string
          - 'null'
          example: Instructions Manager
        avatar:
          type:
          - string
          - 'null'
          format: uri
        mobileNumber:
          type:
          - string
          - 'null'
          description: Observed null on every record sampled.
        email:
          type:
          - string
          - 'null'
          description: Observed null on every record sampled.
        urlLabel:
          type:
          - string
          - 'null'
        team:
          type:
          - string
          - 'null'
        shortBio:
          type:
          - string
          - 'null'
        longBio:
          type:
          - string
          - 'null'
        branchId:
          type:
          - integer
          - 'null'
          description: Foreign key to Branch.id.
          example: 8020
  responses:
    RateLimited:
      description: Rate limited at the Cloudflare edge. Body is the plain-text string "Too many requests" and a Retry-After header is supplied (34 seconds observed).
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
          example: 34
      content:
        text/plain:
          schema:
            type: string
          example: Too many requests