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.
  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'
    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
    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'
    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
    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
  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