Book an appointment (with prospect)

Creates a tour appointment in Funnel for the community using the submitted prospect and scheduling payload (start time, tour type, optional units, and related fields). When the renter is not specified in the URL, the service attempts to match an existing prospect in the company by contact information, or creates a new prospect if no match is found. The response returns the prospect and appointment identifiers.

POST

/api/partners/v1/community/:community_id/appointments/

Request

Example requestPOSTapplication/json

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "prospect": {
        "price_floor": "string",
        "layout": [
          "loft"
        ],
        "people": [
          {
            "first_name": "string",
            "last_name": "string",
            "is_primary": false,
            "phone_2": "string",
            "email": "string",
            "phone_1": "string"
          }
        ],
        "sms_opted_in": false,
        "price_ceiling": "string",
        "move_in_date": "2023-01-01"
      },
      "appointment": {
        "start": "string",
        "message": "Looking forward to my appointment",
        "tour_type": "string",
        "pms_unit_ids": [
          "123",
          "5678"
        ]
      }
    }' \
    "https://api.funnelleasing.com/api/partners/v1/community/1234/appointments/"

Response

Example responseJSON200 · application/json

{
  "prospect": {
    "id": 456
  },
  "appointment": {
    "id": 789
  }
}

Errors

Errors specific to this endpoint

Malformed Request Body (400)

Returned when the request body isn't valid JSON.

Error responseJSON400 · application/json

{
"error_type": "ValidationError",
"message": "Error decoding JSON in request body."
}

Invalid origin_source (400)

Returned when origin_source doesn't match any recognized value. The errors object includes the full list of accepted forms.

Error responseJSON400 · application/json

{
"error_type": "ValidationError",
"message": "Invalid origin_source.",
"errors": {
  "origin_source": ["Unrecognized value 'xyz'. Expected integer ID, enum constant name, short name, or one of: [...]"]
}
}

Community Not Set Up for Tour Scheduling (400)

Returned when the community has no employee group configured.

Error responseJSON400 · application/json

{
"error_type": "CommunitySchedulingInactive",
"message": "Community does not have tour scheduling enabled."
}

Validation Error (400)

Returned when the submitted prospect/appointment data fails validation (for example, an invalid or unavailable start time). The errors object is keyed by the specific fields that failed.

Error responseJSON400 · application/json

{
"error_type": "ValidationError",
"message": "Error validating data.",
"errors": { "...": ["..."] }
}