TwentyCi Agent Performance API

openapi: 3.2.0
info:
  title: TwentyAPI (TwentyCi) v2 Agent Performance API
  version: v2
  summary: UK residential property, valuation (AVM), transaction-trigger and agent-performance data from TwentyCi.
  description: 'TwentyAPI is TwentyCi''s RESTful data-as-a-service API over the DOMUS UK residential property database. Properties are addressed by UPRN (Unique Property Reference Number), the UK national property identifier, rather than by any MLS or RESO identifier. Access is credentialed: an OAuth 2.0 password-grant token is minted at POST https://api.twentyci.co.uk/oauth/token using a client_id, client_secret, username and password issued by TwentyCi under a commercial data agreement. There is no self-serve developer signup.


    PROVENANCE: This document was harvested by API Evangelist on 2026-07-26 from TwentyCi''s own published documentation corpus at https://api.twentyci.co.uk/api/documentation/markdocs (HTTP 200, application/json, 247,074 bytes), which is served publicly without authentication and backs the TwentyAPI documentation SPA at https://api.twentyci.co.uk/documentation. Every path, method, parameter name, parameter type and required flag below is transcribed from that corpus''s own "{% route %}" and "{% param %}" declarations. Response schemas beyond HTTP status codes are NOT modelled, because TwentyCi does not publish them in machine-readable form. TwentyCi advertises a downloadable specification at https://api.twentyci.co.uk/docs/v2/spec.json, but that URL returned HTTP 404 on 2026-07-26; this document is an API Evangelist derivation, not a provider-published artifact.'
  contact:
    name: TwentyCi
    url: https://www.twentyci.co.uk/contact-us/
servers:
- url: https://api.twentyci.co.uk/api/v2
  description: TwentyAPI v2 root URL, as published in the TwentyAPI Overview.
security:
- twentyapiOAuth: []
tags:
- name: Agent Performance
  description: '- Agent Performance based on Sales Data - Agent Performance based on Rental Data'
paths:
  /agent/best:
    get:
      operationId: list_of_best_agents
      summary: List of Best Agents
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#list-of-best-agents
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent/best
      description: The /agent/best endpoint in TwentyAPI is designed to retrieve valuable data for identifying the best estate agents within a specified area. Leveraging proprietary algorithms, this endpoint calculates a score for each agent, offering a comprehensive ranking based on multiple data points. Users gain actionable insights for performance evaluation, client satisfaction monitoring, market trend analysis, strategic planning, and benchmarking against industry standards and competitors. This real-time snapshot ensures informed decision-making with accurate and unbiased data.
      parameters:
      - name: postcode
        in: query
        required: true
        description: This is the postcode unit for where the user would like to find the list of Best Agents. This will be in the standard UK Postcode format. For further information, click here
        schema:
          type: string
      - name: bedroom
        in: query
        required: false
        description: This is the number of bedrooms withn specific properties
        schema:
          type: integer
      - name: propsubtype
        in: query
        required: false
        description: 'Refers to what type of Property can be filtered by. Only the following parameters can be used: - Flat / Apartment - Bungalow - Houses'
        schema:
          type: string
      - name: achieve_asking_price
        in: query
        required: false
        description: 'The paramter refers to whether or not an agent has acheived the listed asking price. This is a boolean value (e.g. 1 or 0) to ultilise this parameter or not. If the following parameters are not used, this parameter is required: - fastestsale - experiencedagent'
        schema:
          type: boolean
      - name: fastest_sale
        in: query
        required: false
        description: 'The paramter refers to whether or not an agent can record a quick sale. This is a boolean value (e.g. 1 or 0) to ultilise this parameter or not. If the following parameters are not used, this parameter is required: - achieveaskingprice - experiencedagent'
        schema:
          type: boolean
      - name: experienced_agent
        in: query
        required: false
        description: 'The paramter refers to whether or not an agent is a known agent with extensive experince. This is a boolean value (e.g. 1 or 0) to ultilise this parameter or not. If the following parameters are not used, this parameter is required: - fastestsale - achieveaskingprice'
        schema:
          type: boolean
  /agent-performance/rankings/sstc:
    get:
      operationId: brands_ranked_by_sstc_s
      summary: Brands Ranked by SSTC's
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#brands-ranked-by-sstc-s
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent-performance/rankings/sstc
      description: The /agent-performance/rankings/sstc endpoint in TwentyAPI is designed to retrieve data on the top five estate agencies ranked by agreed property sales. This API (Application Programming Interface) endpoint assists estate agents in gaining valuable market intelligence, understanding their competitiveness, and identifying opportunities for growth.
      parameters:
      - name: min_price
        in: query
        required: false
        description: Minimum price of the properties to evaluate (rounded down to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: max_price
        in: query
        required: false
        description: Maximum price of the properties to evaluate (rounded up to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: price_bands
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of price bands.
        schema:
          type: string
      - name: postcode_sectors
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode sectors.
        schema:
          type: string
      - name: postcode_areas
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode areas.
        schema:
          type: string
      - name: postcode_districts
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode districts.
        schema:
          type: string
      - name: regions
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of regions.
        schema:
          type: string
      - name: property_types
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of property types.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Dictates which ranked brands to return. By default it returns the top 5. Note this does not limit the result set to 5, if 2 Brands are ranked at 5 for example, then the result set would be 6 long, not 5
        schema:
          type: integer
  /agent-performance/rankings/new-instructions:
    get:
      operationId: brands_ranked_by_new_instructions
      summary: Brands Ranked by New Instructions
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#brands-ranked-by-new-instructions
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent-performance/rankings/new-instructions
      description: The /agent-performance/rankings/new-instructions endpoint in TwentyAPI is designed to retrieve data on the top five estate agencies ranked by new instructions. This API call is crucial for estate agents, providing insights into market trends, facilitating competitive analysis, and supporting strategic planning.
      parameters:
      - name: min_price
        in: query
        required: false
        description: Minimum price of the properties to evaluate (rounded down to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: max_price
        in: query
        required: false
        description: Maximum price of the properties to evaluate (rounded up to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: price_bands
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of price bands.
        schema:
          type: string
      - name: postcode_sectors
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode sectors.
        schema:
          type: string
      - name: postcode_areas
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode areas.
        schema:
          type: string
      - name: postcode_districts
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode districts.
        schema:
          type: string
      - name: regions
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of regions.
        schema:
          type: string
      - name: property_types
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of property types.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Dictates which ranked brands to return. By default it returns the top 5. Note, this does not limit the result set to 5, if 2 Brands are ranked at 5 for example, then the result set would be 6 long, not 5
        schema:
          type: integer
  /agent-performance/rankings/percentage-of-initial-price-achieved:
    get:
      operationId: brands_ranked_by_pipa
      summary: Brands Ranked by PIPA
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#brands-ranked-by-pipa
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent-performance/rankings/percentage-of-initial-price-achieved
      description: The /agent-performance/rankings/percentage-of-initial-price-achieved endpoint in TwentyAPI is designed to retrieve data on the top five estate agencies ranked by the percentage change of the initial listing price (PIPA). This API call is crucial for estate agents, providing insights into market pricing trends, facilitating competitive analysis, and supporting strategic positioning.
      parameters:
      - name: min_price
        in: query
        required: false
        description: Minimum price of the properties to evaluate (rounded down to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: max_price
        in: query
        required: false
        description: Maximum price of the properties to evaluate (rounded up to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: price_bands
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of price bands.
        schema:
          type: string
      - name: postcode_sectors
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode sectors.
        schema:
          type: string
      - name: postcode_areas
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode areas.
        schema:
          type: string
      - name: postcode_districts
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode districts.
        schema:
          type: string
      - name: regions
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of regions.
        schema:
          type: string
      - name: property_types
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of property types.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Dictates which ranked brands to return. By default it returns the top 5. Note this does not limit the result set to 5, if 2 Brands are ranked at 5 for example, then the result set would be 6 long, not 5
        schema:
          type: integer
  /agent-performance/rankings/days-to-sstc:
    get:
      operationId: brands_ranked_by_days_from_new_instruction_to_sstc
      summary: Brands Ranked by Days from New Instruction to SSTC
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#brands-ranked-by-days-from-new-instruction-to-sstc
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent-performance/rankings/days-to-sstc
      description: The /agent-performance/rankings/days-to-sstc endpoint in TwentyAPI is designed to retrieve data on the top five estate agencies ranked by how quickly properties transition from for sale to sold subject to contract (SSTC). This API call is essential for estate agents, providing insights into market efficiency and sales processes.
      parameters:
      - name: min_price
        in: query
        required: false
        description: Minimum price of the properties to evaluate (rounded down to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: max_price
        in: query
        required: false
        description: Maximum price of the properties to evaluate (rounded up to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: price_bands
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of price bands.
        schema:
          type: string
      - name: postcode_sectors
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode sectors.
        schema:
          type: string
      - name: postcode_areas
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode areas.
        schema:
          type: string
      - name: postcode_districts
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode districts.
        schema:
          type: string
      - name: regions
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of regions.
        schema:
          type: string
      - name: property_types
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of property types.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Dictates which ranked brands to return. By default it returns the top 5. Note this does not limit the result set to 5, if 2 Brands are ranked at 5 for example, then the result set would be 6 long, not 5
        schema:
          type: integer
  /agent-performance/brand/new-instructions:
    get:
      operationId: new_instructions_statistics_for_a_brand
      summary: New Instructions Statistics for a Brand
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#new-instructions-statistics-for-a-brand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent-performance/brand/new-instructions
      description: The /agent-performance/brand/new-instructions endpoint in TwentyAPI is designed to retrieve the volume of new instructions for a specific estate agency within the last 12 months. Additionally, it provides the agency's overall rank based on optional parameters. If no parameters are set, the ranking is done on a national level.
      parameters:
      - name: brand_id
        in: query
        required: true
        description: The ID of the brand/agent you want the stats for
        schema:
          type: integer
      - name: min_price
        in: query
        required: false
        description: Minimum price of the properties to evaluate (rounded down to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: max_price
        in: query
        required: false
        description: Maximum price of the properties to evaluate (rounded up to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: price_bands
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of price bands.
        schema:
          type: string
      - name: postcode_sectors
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode sectors.
        schema:
          type: string
      - name: postcode_areas
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode areas.
        schema:
          type: string
      - name: postcode_districts
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode districts.
        schema:
          type: string
      - name: regions
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of regions.
        schema:
          type: string
      - name: property_types
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of property types.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Dictates which ranked brands to return. By default it returns the top 5. Note this does not limit the result set to 5, if 2 Brands are ranked at 5 for example, then the result set would be 6 long, not 5
        schema:
          type: integer
  /agent-performance/brand/sstc:
    get:
      operationId: sstc_statistics_for_a_brand
      summary: SSTC statistics for a Brand
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#sstc-statistics-for-a-brand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent-performance/brand/sstc
      description: The /agent-performance/brand/sstc endpoint in TwentyAPI is designed to retrieve information on properties sold subject to contract (SSTC) by a specific estate agency within the last 12 months. Additionally, it provides the agency's overall rank based on optional parameters. If no parameters are set, the ranking is done on a national level.
  /agent-performance/brand/time-to-sell:
    get:
      operationId: days_to_sstc_for_a_specific_brand
      summary: Days to SSTC for a Specific Brand
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#days-to-sstc-for-a-specific-brand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent-performance/brand/time-to-sell
      description: The /agent-performance/brand/time-to-sell endpoint in TwentyAPI is designed to retrieve the average time it takes for a property to be sold after being instructed for a specific brand. This data is based on optional parameters, allowing for a customised analysis. If no parameters are set, the calculation is done on a national level.
      parameters:
      - name: brand_id
        in: query
        required: true
        description: The ID of the brand/agent you want the stats for
        schema:
          type: integer
      - name: min_price
        in: query
        required: false
        description: Minimum price of the properties to evaluate (rounded down to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: max_price
        in: query
        required: false
        description: Maximum price of the properties to evaluate (rounded up to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: price_bands
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of price bands.
        schema:
          type: string
      - name: postcode_sectors
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode sectors.
        schema:
          type: string
      - name: postcode_areas
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode areas.
        schema:
          type: string
      - name: postcode_districts
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode districts.
        schema:
          type: string
      - name: regions
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of regions.
        schema:
          type: string
      - name: property_types
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of property types.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Dictates which ranked brands to return. By default it returns the top 5. Note, this does not limit the result set to 5, if 2 Brands are ranked at 5 for example, then the result set would be 6 long, not 5
        schema:
          type: integer
  /agent-performance/brand/time-to-sell-all-brands:
    get:
      operationId: days_to_sstc_for_all_brands
      summary: Days to SSTC for all Brands
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#days-to-sstc-for-all-brands
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent-performance/brand/time-to-sell-all-brands
      description: The /agent-performance/brand/time-to-sell-all-brands endpoint in TwentyAPI is designed to retrieve the average time it takes for a property to be sold after being instructed by all brands within a specific area defined by additional parameters. If no parameters are set, the calculation is done on a national level.
      parameters:
      - name: brand_id
        in: query
        required: true
        description: The ID of the brand/agent you want the stats for
        schema:
          type: integer
      - name: min_price
        in: query
        required: false
        description: Minimum price of the properties to evaluate (rounded down to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: max_price
        in: query
        required: false
        description: Maximum price of the properties to evaluate (rounded up to the nearest £50k). Cannot not be used with pricebrands.
        schema:
          type: integer
      - name: price_bands
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of price bands.
        schema:
          type: string
      - name: postcode_sectors
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode sectors.
        schema:
          type: string
      - name: postcode_areas
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode areas.
        schema:
          type: string
      - name: postcode_districts
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of postcode districts.
        schema:
          type: string
      - name: regions
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of regions.
        schema:
          type: string
      - name: property_types
        in: query
        required: false
        description: Only evaluate properties within the given list (comma separated) of property types.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Dictates which ranked brands to return. By default it returns the top 5. Note, this does not limit the result set to 5, if 2 Brands are ranked at 5 for example, then the result set would be 6 long, not 5
        schema:
          type: integer
  /agent-performance/brand/property-sale-difference:
    get:
      operationId: difference_in_sold_price_for_a_property_for_a_specific_brand_and_all_other_brands
      summary: Difference in Sold price for a Property for a Specific Brand and all other Brands
      tags:
      - Agent Performance
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#difference-in-sold-price-for-a-property-for-a-specific-brand-and-all-other-brands
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - authentication credentials were missing or incorrect.
        '404':
          description: Not Found - the URI requested is invalid or the resource does not exist.
        '422':
          description: Unprocessable Entity - request is invalid or unable to be validated.
      x-documented-route: /agent-performance/brand/property-sale-difference
      description: The /agent-performance/brand/property-sale-differenceendpoint in TwentyAPI is designed to calculate the difference between the average sale price from a Property for a given brand and the average sale price of all brands with the specified filter. The volume attribute is in GBP. A positive value indicates the brand sells properties above the average, while a negative value signifies sales below the average. This calculation is performed within a specific area defined by additional parameters. If no parameters are set, the analysis is done on a national level.
      parameters:
      - name: brand_id
        in: query
        required: true
        description: The ID of the brand/agent you want the stats for
        schema:
          type: integer
      - name: min_price
        in: query
        required: false
        desc

# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twentyci/refs/heads/main/openapi/twentyci-agent-performance-api-openapi.yml