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

# Send an enquiry

> For enquiries that start in your system: phone calls, walk-ins, your own web forms. Sending the same `external_id` again changes nothing and messages nobody.



## OpenAPI

````yaml /openapi.json post /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:
    post:
      tags:
        - Enquiries
      summary: Send an enquiry
      description: >-
        For enquiries that start in your system: phone calls, walk-ins, your own
        web forms. Sending the same `external_id` again changes nothing and
        messages nobody.
      operationId: send_enquiry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnquiryIn'
      responses:
        '200':
          description: >-
            We already had this external_id. Nothing changed, and the body is
            the same as the first answer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnquiryAccepted'
        '202':
          description: Accepted. `conversation` says what happens next.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnquiryAccepted'
        '401':
          description: The key is missing, unknown or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '413':
          description: The body is over 64 KB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '415':
          description: The body is not JSON.
          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:
    EnquiryIn:
      properties:
        external_id:
          type: string
          maxLength: 128
          minLength: 1
          title: External Id
          description: >-
            The ENQUIRY's id, not the contact's. One person, three properties:
            three ids.
        received_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Received At
          description: >-
            When it reached you. Defaults to now. Over 24 hours old: recorded,
            never messaged.
        source:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Source
          description: >-
            Where the enquiry came from: daft, myhome, website, phone, walk_in
            or other. Anything else is recorded as other.
        transaction_type:
          type: string
          enum:
            - sale
            - letting
          title: Transaction Type
          description: sale or letting. Picks the questions Signal asks.
        branch_code:
          anyOf:
            - type: string
              maxLength: 32
              minLength: 1
            - type: 'null'
          title: Branch Code
          description: >-
            Which of the agency's branches it belongs to. The codes are agreed
            with the agency when they join. An unknown code is a 422.
        contact:
          $ref: '#/components/schemas/Contact'
        property:
          $ref: '#/components/schemas/PropertyRef'
        consent:
          anyOf:
            - $ref: '#/components/schemas/Consent'
            - type: 'null'
          description: >-
            Leave it out unless your capture point records a WhatsApp
            preference. Absent: the agency's policy applies, which by default
            starts the conversation. contact_by_whatsapp false: recorded, never
            messaged.
        message:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Message
          description: Their own words. Anything past 2,000 characters is cut off.
        suppress_conversation:
          type: boolean
          title: Suppress Conversation
          description: Record the enquiry and send nothing. For testing.
          default: false
      type: object
      required:
        - external_id
        - transaction_type
        - contact
        - property
      title: EnquiryIn
      description: >-
        An enquiry that started in your system: a phone call, a walk-in, your
        own web form.
    EnquiryAccepted:
      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. Store it.
        conversation:
          type: string
          enum:
            - starting
            - existing_contact
            - not_started
          title: Conversation
          description: >-
            starting: the greeting is on its way. existing_contact: we already
            have a conversation with this mobile number. not_started: recorded,
            nothing sent (see reason).
        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.
      type: object
      required:
        - enquiry_id
        - external_id
        - conversation
      title: EnquiryAccepted
      description: What happened to an enquiry you sent.
    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.
    Contact:
      properties:
        external_id:
          anyOf:
            - type: string
              maxLength: 128
              minLength: 1
              description: >-
                Your own id. Stored and echoed back as sent, without surrounding
                spaces.
            - type: 'null'
          title: External Id
          description: Your contact id.
        first_name:
          anyOf:
            - type: string
              maxLength: 200
              minLength: 1
            - type: 'null'
          title: First Name
          description: If you hold one name string, send it here.
        last_name:
          anyOf:
            - type: string
              maxLength: 200
              minLength: 1
            - type: 'null'
          title: Last Name
          description: Their surname, if you hold one.
        phone:
          anyOf:
            - type: string
              maxLength: 32
            - type: 'null'
          title: Phone
          description: >-
            Irish (+353) or UK (+44) numbers. National numbers (086 123 4567,
            07700 900123) are read for the agency's side of the border. Without
            a mobile number nothing can be sent, but the record is kept.
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: >-
            Treated as absent, not refused, if we can't read it as an email
            address.
      type: object
      title: Contact
      description: A person, as your system holds them.
    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.
    Consent:
      properties:
        contact_by_whatsapp:
          type: boolean
          title: Contact By Whatsapp
          description: Whether they agreed to be contacted on WhatsApp.
        captured_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Captured At
          description: >-
            When they said so. Later than an earlier opt-out, it lets us message
            them again.
      type: object
      required:
        - contact_by_whatsapp
      title: Consent
      description: >-
        What the person agreed to about WhatsApp, if your capture point records
        it.
    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.
    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.
    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).
  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.