TwentyCi This is Now | Retail Propensity To Buy Goods API

openapi: 3.2.0
info:
  title: TwentyAPI (TwentyCi) v2 This is Now | Retail Propensity To Buy Goods 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: This is Now | Retail Propensity To Buy Goods
  description: '- Local Search - National Search'
paths:
  /this-is-now/search:
    get:
      operationId: local_search
      summary: Local Search
      tags:
      - This is Now | Retail Propensity To Buy Goods
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#local-search
      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: /api/v2/this-is-now/search
      description: 'The /this-is-now/search endpoint in TwentyAPI is designed to retrieve the likelihood of a household within a specified area purchasing specific goods, based on their position in the timeline of their homemover journey. Purpose Targetted Marketing: To enable retailers to target marketing efforts effectively by understanding the likelihood of households purchasing specific goods. Performance Management: To provide insights for inventory management, customer retention, personalized customer experience, resource allocation, competitive advantage, sales forecasting, product development, and customer segmentation. Use Case Scenario: Targeted Direct Mail Campaigns Retailers can use this endpoint to target marketing campaigns specifically to households with a high likelihood of making purchases, thus maximizing ROI and improving customer engagement. Scenario: Inventory Management Inventory managers can leverage the data from this endpoint to forecast demand accurately, ensuring optimal inventory levels and minimising product unavailablity. Conclusion In summary, the /this-is-now/search endpoint is a crucial tool for developers, providing valuable insights into household purchasing behaviour. Whether you''re a beginner or an experienced developer, leveraging this endpoint enhances the development experience by offering straightforward solutions to common challenges.'
      parameters:
      - name: postcode
        in: query
        required: true
        description: This will be in the standard UK Postcode format. For further information, click here
        schema:
          type: string
      - name: product_type
        in: query
        required: true
        description: 'Valid values include the following: - electricals, - departmentstores, - furniture, - bedretailers, - homefurnishings, - kitchen, - diy, - garden'
        schema:
          type: string
      - name: radius
        in: query
        required: false
        description: 'Valid values include the following: - 10, - 15, - 20, - 25'
        schema:
          type: string
  /this-is-now/search-national:
    get:
      operationId: get_this_is_now_search_national
      summary: /this-is-now/search-national
      tags:
      - This is Now | Retail Propensity To Buy Goods
      externalDocs:
        description: TwentyAPI documentation
        url: https://api.twentyci.co.uk/documentation#this-is-now-retail-propensity-to-buy-goods
      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: /this-is-now/search-national
      description: Listed as an available route on the TwentyAPI "This is Now | Retail Propensity To Buy Goods" section page, but TwentyCi does not publish a dedicated parameter or response block for it. Recorded here verbatim from the section index; no parameters are asserted.
components:
  securitySchemes:
    twentyapiOAuth:
      type: oauth2
      description: 'OAuth 2.0 bearer token. TwentyCi''s documentation labels the scheme "OAuth2" with flow "Implicit" but describes a resource-owner password-credentials exchange: POST /oauth/token with client_id, client_secret, username, password, grant_type=password and scope=* returns {token_type: Bearer, expires_in, access_token, refresh_token}. The token is then sent as "Authorization: Bearer <token-key>". Modelled here as the password flow because that is what the documented request body performs. No OpenID Connect discovery document is served (/.well-known/openid-configuration returned 404).'
      flows:
        password:
          tokenUrl: https://api.twentyci.co.uk/oauth/token
          refreshUrl: https://api.twentyci.co.uk/oauth/token
          scopes:
            '*': Full access; the only scope value documented by TwentyCi.
externalDocs:
  description: TwentyAPI documentation
  url: https://api.twentyci.co.uk/documentation
x-provenance:
  harvestedBy: API Evangelist
  harvestDate: '2026-07-26'
  derived: true
  providerPublished: false
  sources:
  - url: https://api.twentyci.co.uk/api/documentation/markdocs
    status: 200
    contentType: application/json
    bytes: 247074
    note: Public, unauthenticated JSON documentation corpus (66 nodes) backing the TwentyAPI docs SPA.
  - url: https://api.twentyci.co.uk/documentation
    status: 200
    contentType: text/html
    note: React/Markdoc single-page app shell; renders the corpus above.
  - url: https://api.twentyci.co.uk/docs/v2/spec.json
    status: 404
    note: Specification download advertised in the TwentyAPI Overview page. NOT served.
  anomalies:
  - TwentyCi advertises https://api.twentyci.co.uk/docs/v2/spec.json as a downloadable specification; it returned HTTP 404 on 2026-07-26. No provider-published OpenAPI exists.
  - Several documented route strings are irregular (e.g. "api/v2/propertiesavm2/{property}", "api/v2/{uprn}/likely-to-sell"). They are transcribed verbatim and flagged with x-documented-route-note rather than corrected.
  - The documentation page "Obtain a Specific Trigger" declares the route "/categories", which is inconsistent with its own section index route "/trigger/{trigger}".
  - Several routes are listed only on a section index page with no parameter documentation; they are included with no asserted parameters.
  - TwentyCi labels the security scheme OAuth2 with the "Implicit" flow while documenting a resource-owner password-credentials request body. Modelled as the password flow.