> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signalproptech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read an enquiry

> Read one enquiry you sent, by your external_id. Counts towards the rate limit: cache it rather than calling it on every page view.



## OpenAPI

````yaml /openapi.json get /enquiries
openapi: 3.1.0
info:
  title: Signal Partner API
  description: >-
    Send Signal enquiries, viewings and listings from your system, and receive
    what Signal learns back as signed webhooks. Every call is in beta:
    documented ahead of going live, it answers `501 not_available_yet` until
    then.
  contact:
    name: Signal
    url: https://signalproptech.com/
  version: 1.0.0-beta
servers:
  - url: https://api.signalproptech.com/api/v1/partner
    description: Production
security: []
tags:
  - name: Enquiries
    description: >-
      Hand Signal an enquiry that started in your system, and read where it
      stands.
  - name: Viewings
    description: >-
      Tell Signal about viewings booked in your system, so it can remind and ask
      for feedback.
  - name: Listings and new homes
    description: >-
      Keep Signal's copy of your listings, developments, units and reservations
      up to date.
  - name: Webhooks
    description: >-
      Register where Signal sends events, test it, and catch up on what you
      missed.
  - name: Events
    description: >-
      What Signal sends to your webhook, one page per event type. Check the
      webhook- headers before trusting the body.
paths:
  /enquiries:
    get:
      tags:
        - Enquiries
      summary: Read an enquiry
      description: >-
        Read one enquiry you sent, by your external_id. Counts towards the rate
        limit: cache it rather than calling it on every page view.
      operationId: read_enquiry
      parameters:
        - name: external_id
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
            description: Your enquiry id.
            title: External Id
          description: Your enquiry id.
      responses:
        '200':
          description: The enquiry's current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnquiryState'
        '401':
          description: The key is missing, unknown or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: No enquiry with that external_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: Validation failed. `fields` lists each problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '429':
          description: Rate limited. Retry after the number of seconds in `Retry-After`.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '501':
          description: Not live yet (beta).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
        - AgencyKey: []
components:
  schemas:
    EnquiryState:
      properties:
        enquiry_id:
          type: string
          format: uuid
          title: Enquiry Id
          description: Signal's id for the enquiry.
        external_id:
          type: string
          title: External Id
          description: Your enquiry id.
        contact_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Contact Id
          description: Signal's id for the person.
        contact_external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Contact External Id
          description: Your contact id, once we know it.
        transaction_type:
          type: string
          enum:
            - sale
            - letting
          title: Transaction Type
          description: sale or letting.
        branch_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Branch Code
          description: Which of the agency's branches it belongs to.
        property:
          anyOf:
            - $ref: '#/components/schemas/PropertyRef'
            - type: 'null'
          description: The property it's about.
        status:
          type: string
          enum:
            - not_started
            - greeted
            - in_conversation
            - qualified
            - quiet
            - opted_out
          title: Status
          description: >-
            not_started: recorded, nothing sent. greeted: greeting sent, no
            reply yet. in_conversation: they've replied and the questions are
            under way. qualified: questions answered. quiet: they stopped
            replying. opted_out: asked us to stop.
        reason:
          anyOf:
            - type: string
              enum:
                - no_phone
                - not_mobile
                - no_consent
                - opted_out
                - stale
                - suppressed
                - transaction_type_off
                - whatsapp_not_connected
            - type: 'null'
          title: Reason
          description: >-
            Why nothing was sent. no_phone: no usable phone number. not_mobile:
            the number is a landline. no_consent: contact_by_whatsapp was false.
            opted_out: they've asked us to stop. stale: received more than 24
            hours ago. suppressed: suppress_conversation was set, or the number
            isn't on a dev key's allow-list. transaction_type_off: the agency
            hasn't switched Signal on for sales, or for lettings.
            whatsapp_not_connected: the agency's WhatsApp number isn't connected
            yet.
        qualification:
          anyOf:
            - oneOf:
                - $ref: '#/components/schemas/SaleQualification'
                - $ref: '#/components/schemas/LettingQualification'
              discriminator:
                propertyName: kind
                mapping:
                  letting: '#/components/schemas/LettingQualification'
                  sale: '#/components/schemas/SaleQualification'
            - type: 'null'
          title: Qualification
          description: Their answers, once they've given any.
        last_message_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Message At
          description: When the last message was sent, by either side.
        last_message_from:
          anyOf:
            - type: string
              enum:
                - contact
                - agency
            - type: 'null'
          title: Last Message From
          description: >-
            contact: the person. agency: the agency's side, including Signal's
            own messages.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: When anything about it last changed.
      type: object
      required:
        - enquiry_id
        - external_id
        - transaction_type
        - status
        - updated_at
      title: EnquiryState
      description: Where an enquiry stands now.
    ErrorBody:
      properties:
        error:
          type: string
          title: Error
          description: >-
            Stable machine code: validation_failed, unauthorized, bad_request,
            forbidden, not_found, method_not_allowed, conflict, too_large,
            unsupported_media_type, rate_limited, cursor_expired,
            not_available_yet or internal_error. Any other status gives error.
        message:
          type: string
          title: Message
          description: What went wrong, in plain English.
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Quote this to us and we can find the call.
        fields:
          items:
            $ref: '#/components/schemas/FieldError'
          type: array
          title: Fields
          description: Each problem with the request. Empty for other errors.
      type: object
      required:
        - error
        - message
      title: ErrorBody
      description: Every error has this shape.
    PropertyRef:
      properties:
        ref:
          anyOf:
            - type: string
              maxLength: 128
              minLength: 1
              description: >-
                Your own id. Stored and echoed back as sent, without surrounding
                spaces.
            - type: 'null'
          title: Ref
          description: >-
            Your property or unit reference. For new homes, leave it out when
            the enquiry is about a development rather than one unit, and send
            `development` instead.
        address:
          anyOf:
            - type: string
              maxLength: 500
              minLength: 1
            - type: 'null'
          title: Address
          description: Names the property in messages. Recommended.
        development:
          anyOf:
            - $ref: '#/components/schemas/DevelopmentRef'
            - type: 'null'
          description: 'New homes: the development the unit is in.'
        details:
          anyOf:
            - $ref: '#/components/schemas/ListingDetails'
            - type: 'null'
          description: What you know about the property, if you want Signal to have it.
      type: object
      title: PropertyRef
      description: >-
        The property an enquiry or viewing is about: your reference, the
        development, or both.
    SaleQualification:
      properties:
        kind:
          const: sale
          title: Kind
          description: >-
            `sale` or `letting`, the same as `transaction_type`. Says which
            fields follow.
        position:
          anyOf:
            - type: string
              enum:
                - cash
                - first_time_buyer
                - selling_mortgage
                - selling_cash_proceeds
                - selling_cash_available
                - renting_cash
                - renting_mortgage
                - living_with_family_cash
                - living_with_family_mortgage
                - other_mortgage
            - type: 'null'
          title: Position
          description: >-
            Their buying position. cash: cash buyer. first_time_buyer:
            first-time buyer. selling_mortgage: selling, using a mortgage.
            selling_cash_proceeds: selling, paying cash from the proceeds.
            selling_cash_available: selling, with cash available. renting_cash /
            renting_mortgage: renting, as a cash buyer / using a mortgage.
            living_with_family_cash / living_with_family_mortgage: living with
            family or friends, as a cash buyer / using a mortgage.
            other_mortgage: another living situation, using a mortgage.
        has_property_to_sell:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Property To Sell
          description: They have a home of their own to sell.
        on_market:
          anyOf:
            - type: boolean
            - type: 'null'
          title: On Market
          description: Their own home is already on the market.
        has_agent:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Agent
          description: An agent is already selling their own home.
        mortgage_status:
          anyOf:
            - type: string
              enum:
                - cash
                - aip_secured
                - no_aip
                - not_applicable
            - type: 'null'
          title: Mortgage Status
          description: >-
            cash: no mortgage needed. aip_secured: mortgage approval (or
            decision) in principle in place. no_aip: none yet. not_applicable:
            doesn't apply.
        wants_valuation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Wants Valuation
          description: Asked for a valuation of the home they're selling.
        wants_mortgage_advice:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Wants Mortgage Advice
          description: Would like mortgage advice.
        viewing_availability:
          items:
            type: string
          type: array
          title: Viewing Availability
          description: When they can view, in their words.
        questions:
          items:
            type: string
          type: array
          title: Questions
          description: Questions the agency still needs to answer.
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
          description: A short plain-English summary of their answers.
      type: object
      required:
        - kind
      title: SaleQualification
      description: >-
        A buyer's answers to Signal's qualifying questions. New-homes buyers use
        the same shape.
    LettingQualification:
      properties:
        kind:
          const: letting
          title: Kind
          description: >-
            `sale` or `letting`, the same as `transaction_type`. Says which
            fields follow.
        occupants:
          items:
            type: string
          type: array
          title: Occupants
          description: Names of everyone who'd live there.
        occupant_count:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Occupant Count
          description: How many people would live there.
        employment_status:
          anyOf:
            - type: string
              enum:
                - employed
                - self_employed
                - student
                - retired
                - other
            - type: 'null'
          title: Employment Status
          description: employed, self_employed, student, retired or other.
        household_income_annual:
          anyOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
          description: Total household income a year.
        move_in_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Move In Date
          description: When they want to move in.
        tenancy_length_months:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Tenancy Length Months
          description: How long they want to rent for.
        has_pets:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Pets
          description: Whether they have pets.
        pets_details:
          anyOf:
            - type: string
            - type: 'null'
          title: Pets Details
          description: What pets they have.
        has_smokers:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Smokers
          description: Whether anyone who'd live there smokes.
        viewing_availability:
          items:
            type: string
          type: array
          title: Viewing Availability
          description: When they can view, in their words.
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
          description: A short plain-English summary of their answers.
      type: object
      required:
        - kind
      title: LettingQualification
      description: A prospective tenant's answers to Signal's qualifying questions.
    FieldError:
      properties:
        path:
          type: string
          title: Path
          description: >-
            Where the problem is, e.g. `contact.phone` or `house_types[0].name`.
            Empty for the request as a whole.
        code:
          type: string
          title: Code
          description: >-
            Stable code: required, empty, too_long, missing_offset, not_allowed,
            invalid_json or invalid.
        message:
          type: string
          title: Message
          description: What is wrong with this field, in plain English.
      type: object
      required:
        - path
        - code
        - message
      title: FieldError
      description: One problem with one field.
    DevelopmentRef:
      properties:
        ref:
          type: string
          maxLength: 128
          minLength: 1
          title: Ref
          description: >-
            Your development reference. Send the development first: an unknown
            one is a 422.
        name:
          anyOf:
            - type: string
              maxLength: 200
              minLength: 1
            - type: 'null'
          title: Name
          description: The development's name.
      type: object
      required:
        - ref
      title: DevelopmentRef
      description: A new-homes development, by your reference.
    ListingDetails:
      properties:
        price:
          anyOf:
            - $ref: '#/components/schemas/Price'
            - type: 'null'
          description: The asking price, or a letting's rent.
        bedrooms:
          anyOf:
            - type: integer
              maximum: 50
              minimum: 0
            - type: 'null'
          title: Bedrooms
          description: Number of bedrooms.
        bathrooms:
          anyOf:
            - type: integer
              maximum: 50
              minimum: 0
            - type: 'null'
          title: Bathrooms
          description: Number of bathrooms.
        property_type:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          title: Property Type
          description: Free text.
        floor_area_sqm:
          anyOf:
            - type: number
              maximum: 100000
              exclusiveMinimum: 0
            - type: 'null'
          title: Floor Area Sqm
          description: Floor area in square metres.
        available_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Available From
          description: When it's free to move in.
        furnished:
          anyOf:
            - type: string
              enum:
                - furnished
                - part_furnished
                - unfurnished
            - type: 'null'
          title: Furnished
          description: furnished, part_furnished or unfurnished.
        pets_allowed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Pets Allowed
          description: Whether pets are allowed.
        minimum_term_months:
          anyOf:
            - type: integer
              maximum: 120
              minimum: 1
            - type: 'null'
          title: Minimum Term Months
          description: The shortest tenancy offered, in months.
        deposit:
          anyOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
          description: A letting's deposit.
      type: object
      title: ListingDetails
      description: >-
        What you know about the property. Every field is optional: send what you
        have.
    Money:
      properties:
        amount:
          type: integer
          minimum: 0
          title: Amount
          description: >-
            Minor units: €395,000 is 39500000. A decimal point is refused,
            because it usually means whole euros or pounds were sent.
        currency:
          type: string
          enum:
            - EUR
            - GBP
          title: Currency
          description: EUR or GBP.
      type: object
      required:
        - amount
        - currency
      title: Money
      description: An amount in whole minor units (cents or pence).
    Price:
      properties:
        amount:
          type: integer
          minimum: 0
          title: Amount
          description: >-
            Minor units: €395,000 is 39500000. A decimal point is refused,
            because it usually means whole euros or pounds were sent.
        currency:
          type: string
          enum:
            - EUR
            - GBP
          title: Currency
          description: EUR or GBP.
        period:
          anyOf:
            - type: string
              enum:
                - week
                - month
            - type: 'null'
          title: Period
          description: Required on a letting listing's price.
      type: object
      required:
        - amount
        - currency
      title: Price
      description: A price. A letting's rent also says how often it's paid.
  securitySchemes:
    AgencyKey:
      type: http
      description: >-
        The agency's secret key, sent as `Authorization: Bearer <key>`. One key
        per agency.
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.