> ## 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 a reservation

> A unit's reservation and its buyer. Changing it never messages the buyer.



## OpenAPI

````yaml /openapi.json post /reservations
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:
  /reservations:
    post:
      tags:
        - Listings and new homes
      summary: Send a reservation
      description: >-
        A unit's reservation and its buyer. Changing it never messages the
        buyer.
      operationId: send_reservation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReservationIn'
        required: true
      responses:
        '200':
          description: >-
            Updated, or ignored because we already held a newer version (see
            `applied`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationSynced'
        '201':
          description: >-
            Recorded. `applied` says whether this version was used, and what
            became of the buyer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationSynced'
        '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:
    ReservationIn:
      properties:
        development_ref:
          type: string
          maxLength: 128
          minLength: 1
          title: Development Ref
          description: Send the development first. An unknown one is a 422.
        unit_ref:
          type: string
          maxLength: 128
          minLength: 1
          title: Unit Ref
          description: Send the unit first. An unknown one is a 422.
        ref:
          type: string
          maxLength: 128
          minLength: 1
          title: Ref
          description: >-
            Your id for this reservation or sale. A new buyer for the same unit
            is a new reservation with a new ref.
        status:
          type: string
          enum:
            - reserved
            - exchanged
            - completed
            - fell_through
          title: Status
          description: >-
            reserved: a booking deposit is paid. exchanged: contracts exchanged
            (signed in Ireland). completed: the sale has closed. fell_through:
            the reservation ended without a sale. A reservation call also sets
            the unit's status: reserved, exchanged and completed set the same
            status, fell_through sets it back to available. You needn't send the
            unit as well, and a unit call older than the reservation won't undo
            it.
        buyer:
          allOf:
            - $ref: '#/components/schemas/Contact'
          description: >-
            The lead buyer. We find them by contact_id, then your buyer
            external_id, then phone. With none of those usable, only the unit's
            status is updated.
        contact_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Contact Id
          description: Signal's id for the buyer, if you have it.
        reserved_at:
          type: string
          format: date-time
          title: Reserved At
          description: When the reservation was made.
        exchanged_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Exchanged At
          description: When it happened, once it has.
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: When it happened, once it has.
        fell_through_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Fell Through At
          description: When it happened, once it has.
        fell_through_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Fell Through Reason
          description: Why it ended, if you know. Cut at 500 characters.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: >-
            When it last changed in your system (if you don't track that, send
            the time of the call). An update older than the one we hold is
            ignored; the same time again is applied, so retries are safe.
      type: object
      required:
        - development_ref
        - unit_ref
        - ref
        - status
        - buyer
        - reserved_at
        - updated_at
      title: ReservationIn
      description: A unit's reservation and its lead buyer.
    ReservationSynced:
      properties:
        development_ref:
          type: string
          title: Development Ref
          description: Your development reference.
        unit_ref:
          type: string
          title: Unit Ref
          description: Your unit reference.
        ref:
          type: string
          title: Ref
          description: Your reservation reference.
        status:
          type: string
          enum:
            - reserved
            - exchanged
            - completed
            - fell_through
          title: Status
          description: The reservation's status as recorded.
        buyer:
          type: string
          enum:
            - matched
            - created
            - not_matched
          title: Buyer
          description: >-
            matched: someone Signal knows. created: new to Signal, recorded,
            never messaged automatically. not_matched: no contact_id we know and
            no usable phone number, so only the unit's status was updated.
        contact_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Contact Id
          description: Signal's id for the buyer, when matched or created.
        applied:
          type: boolean
          title: Applied
          description: >-
            False when we already held a newer version (by updated_at), so this
            one was ignored.
      type: object
      required:
        - development_ref
        - unit_ref
        - ref
        - status
        - buyer
        - applied
      title: ReservationSynced
      description: What Signal did with a reservation 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.
    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.
  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.