API docs by Redocly

Showami (1.0)

Download OpenAPI specification:

License: Showami Terms of Service

The Showami API for creating, accepting, and updating showings and rentals.

Authentication

Authenticate with Showami

Authenticate with API

Use email/password to generate an Access Token and Refresh Token.

NOTE: this route is not in the /api/v1 namespace. You must send an application/json request to https://showami.com/users/sign_in

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "access_token": "lmn456",
  • "refresh_token": "xyz890"
}

Refresh Access Token

Generate fresh Access Token from valid Refresh Token. This also cycles the Refresh token and returns a new one.

Request Body schema: application/json
required
refresh_token
string

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "abc123"
}

Response samples

Content type
application/json
{
  • "access_token": "lmn456",
  • "refresh_token": "xyz890"
}

Showings

API endpoints related to Showings

Accepted Showings

Get a list of all Showings where the authenticated user is the Showing Agent.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Showing(s)

Create a new Showing or multiple Showings

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
object (ShowingRequest)

Responses

Request samples

Content type
application/json
{
  • "showing_request": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Accepted Showing by Id

Get the details of a showing where the user is the Showing Agent.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
showing_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 123,
  • "showing_request_id": 456,
  • "showing_at": "2020-10-22T13:00:00.000-06:00",
  • "duration": 2.5,
  • "mls": "12120009",
  • "notes": "Here are the details...",
  • "public_notes": "We're looking for you to do the following...",
  • "showing_group": "40ea31cf-e81b-4c0a-853b-8314b6094aef",
  • "buyer_name": "Sally Ride",
  • "buyer_phone": 7205551234,
  • "buyer_type": "individual",
  • "buyer_external_id": "buyer-abc-123",
  • "price": 100,
  • "payout": 79,
  • "paid_group_amount": 158,
  • "tip": 10,
  • "status": "unassigned",
  • "who_cancelled": "SA",
  • "cancellation_notes": "The showing was cancelled because...",
  • "reposted": true,
  • "message_count": 0,
  • "counter_proposal_count": 0,
  • "reschedulable": true,
  • "rescheduling_requested": true,
  • "repostable": true,
  • "counter_proposable": true,
  • "who_schedules": "showing_agent",
  • "schedule_details": "The showing has already been scheduled, the code is...",
  • "amendable": true,
  • "outstanding_amendment": true,
  • "review_allowed": true,
  • "no_show_eligible": true,
  • "showing_type": "standard",
  • "original_showing_id": 111,
  • "external_id": "abc-123",
  • "nar_buyer_agreement": true,
  • "address": {
    },
  • "user": {
    },
  • "showing_agent": {
    },
  • "showing_agent_cancellation": {
    },
  • "initiating_agent_cancellation": {
    }
}

Showing opportunities

All Showing opportunities that match the Showing Agent preferences.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Showings by Buyer External ID

Get a list of all showings where the authenticated user is the Initiating Agent, filtered by buyer_external_id.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
query Parameters
buyer_external_id
required
string

The external identifier for the buyer to filter showings by

page
integer

Page number for pagination

per_page
integer

Number of results per page (default 15)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Showing Requests

Get a list of all showings where the user is the Initiating Agent.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Showing Request by Id

Get the details of a showing where the user is the Initiating Agent.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
showing_request_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 123,
  • "showing_request_id": 456,
  • "showing_at": "2020-10-22T13:00:00.000-06:00",
  • "duration": 2.5,
  • "mls": "12120009",
  • "notes": "Here are the details...",
  • "public_notes": "We're looking for you to do the following...",
  • "showing_group": "40ea31cf-e81b-4c0a-853b-8314b6094aef",
  • "buyer_name": "Sally Ride",
  • "buyer_phone": 7205551234,
  • "buyer_type": "individual",
  • "buyer_external_id": "buyer-abc-123",
  • "price": 100,
  • "payout": 79,
  • "paid_group_amount": 158,
  • "tip": 10,
  • "status": "unassigned",
  • "who_cancelled": "SA",
  • "cancellation_notes": "The showing was cancelled because...",
  • "reposted": true,
  • "message_count": 0,
  • "counter_proposal_count": 0,
  • "reschedulable": true,
  • "rescheduling_requested": true,
  • "repostable": true,
  • "counter_proposable": true,
  • "who_schedules": "showing_agent",
  • "schedule_details": "The showing has already been scheduled, the code is...",
  • "amendable": true,
  • "outstanding_amendment": true,
  • "review_allowed": true,
  • "no_show_eligible": true,
  • "showing_type": "standard",
  • "original_showing_id": 111,
  • "external_id": "abc-123",
  • "nar_buyer_agreement": true,
  • "address": {
    },
  • "user": {
    },
  • "showing_agent": {
    },
  • "showing_agent_cancellation": {
    },
  • "initiating_agent_cancellation": {
    }
}

Cancel showing

You may cancel an existing showing for which you have initiated.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
showing_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "Showing successfully canceled."
}

Initiating Agent Cancel

Cancel a showing as the initiating agent (buyer's agent). The authenticated user must be the initiating agent on the showing.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
showing_id
required
integer
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "initiating_agent_cancellation": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Showing successfully canceled."
}

Counter Proposals

Get all counter proposals for a specific showing.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
showing_id
required
integer
query Parameters
include_rejected
boolean

Whether to include rejected counter proposals in the response. Default is false.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Showing Feedback

Get a list of all Showing feedbacks for this request

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)

Responses

Response samples

Content type
application/json
{
  • "showing_id": "123",
  • "showing_address": "362 W 12th St. Denver CO, 80123",
  • "showing_external_id": "abc-1234-ext",
  • "feedback_responses": [
    ]
}

Accept Counter-Proposal

Accept a counter-proposal for a showing. The authenticated user must be authorized to accept the counter-proposal.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
showing_id
required
integer

The id of the showing.

Request Body schema: application/json
required
counter_proposal_id
required
integer

The id of the counter-proposal to accept.

Responses

Request samples

Content type
application/json
{
  • "counter_proposal_id": 456
}

Response samples

Content type
application/json
{
  • "message": "Counter-proposal accepted!"
}

Reject Counter-Proposal

Reject a counter-proposal for a showing. The authenticated user must be authorized to reject the counter-proposal.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
showing_id
required
integer

The id of the showing.

Request Body schema: application/json
required
counter_proposal_id
required
integer

The id of the counter-proposal to reject.

rejection_reason
string

Optional reason for rejecting the counter-proposal.

Responses

Request samples

Content type
application/json
{
  • "counter_proposal_id": 456,
  • "rejection_reason": "The proposed time does not work for my client."
}

Response samples

Content type
application/json
{
  • "message": "Counter-proposal rejected"
}

Report Showing Issue

Report an issue with a showing as the initiating agent (buyer's agent). The authenticated user must be the buyer's agent on the showing, the showing must be in completed status, and the report must be submitted within 24 hours of the showing time.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
showing_id
required
integer

The id of the showing.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "showing_issue": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Showing marked as a no-show"
}

Reschedule Showing

Create a reschedule request for a showing for which you are either the initiating agent or showing agent.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "showing_rescheduling": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Requested to reschedule showing"
}

Reschedule Accept/Decline

Accept or Reject a rescheduling request for a showing.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
showing_rescheduling_id
required
integer
Request Body schema: application/json
required
status
required
string
Enum: "accept" "decline"

Whether to accept or decline the rescheduling request.

Responses

Request samples

Content type
application/json
{
  • "status": "accept"
}

Response samples

Content type
application/json
{
  • "message": "Accepted rescheduling"
}

Showing Acceptance Prediction

Get a prediction of whether a showing will be accepted based on the showing request parameters.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
object (ShowingRequest)

Responses

Request samples

Content type
application/json
{
  • "showing_request": {
    }
}

Response samples

Content type
application/json
{
  • "prediction": 0.85,
  • "warnings": [
    ]
}

Tasks

API endpoints related to Tasks

Create a Task List

Create a new Task List

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
object (TaskRequest)

Responses

Request samples

Content type
application/json
{
  • "showing_request": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Accept a Task List

Mark a Task List as Accepted

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
task_id
required
integer
Request Body schema: application/json
required
status
required
string
Enum: "approve" "reject"

Whether to approve or reject the task.

Responses

Request samples

Content type
application/json
{
  • "status": "approve"
}

Response samples

Content type
application/json
{
  • "message": "Task Accepted"
}

Rentals

API endpoints related to Rentals

Rental Requests

Get a paginated list of all rental showings initiated by the authenticated user.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
query Parameters
page
integer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Rental

You may create one or more rental showing(s) using this action. It takes a JSON object containing the parameters of the showing.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
object (RentalShowingRequest)

Responses

Request samples

Content type
application/json
{
  • "showing_request": {
    }
}

Response samples

Content type
application/json
{
  • "id": 123,
  • "showing_request_id": 456,
  • "showing_at": "2020-10-22T13:00:00.000-06:00",
  • "duration": 2.5,
  • "mls": "12120009",
  • "notes": "Here are the details...",
  • "public_notes": "We're looking for you to do the following...",
  • "showing_group": "40ea31cf-e81b-4c0a-853b-8314b6094aef",
  • "buyer_name": "Sally Ride",
  • "buyer_phone": 7205551234,
  • "buyer_type": "individual",
  • "buyer_external_id": "buyer-abc-123",
  • "price": 100,
  • "payout": 79,
  • "paid_group_amount": 158,
  • "tip": 10,
  • "status": "unassigned",
  • "who_cancelled": "SA",
  • "cancellation_notes": "The showing was cancelled because...",
  • "reposted": true,
  • "message_count": 0,
  • "counter_proposal_count": 0,
  • "reschedulable": true,
  • "rescheduling_requested": true,
  • "repostable": true,
  • "counter_proposable": true,
  • "who_schedules": "showing_agent",
  • "schedule_details": "The showing has already been scheduled, the code is...",
  • "amendable": true,
  • "outstanding_amendment": true,
  • "review_allowed": true,
  • "no_show_eligible": true,
  • "showing_type": "standard",
  • "original_showing_id": 111,
  • "external_id": "abc-123",
  • "nar_buyer_agreement": true,
  • "address": {
    },
  • "user": {
    },
  • "showing_agent": {
    },
  • "showing_agent_cancellation": {
    },
  • "initiating_agent_cancellation": {
    }
}

Cancel Rental

You may cancel an existing rental showing.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
rental_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "Rental successfully canceled."
}

Rental Request by Id

Get a serialized rental showing object by its id, initiated by the authenticated user.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
path Parameters
rental_id
required
integer
query Parameters
page
integer

Responses

Response samples

Content type
application/json
{
  • "id": 123,
  • "showing_request_id": 456,
  • "showing_at": "2020-10-22T13:00:00.000-06:00",
  • "duration": 2.5,
  • "mls": "12120009",
  • "notes": "Here are the details...",
  • "public_notes": "We're looking for you to do the following...",
  • "showing_group": "40ea31cf-e81b-4c0a-853b-8314b6094aef",
  • "buyer_name": "Sally Ride",
  • "buyer_phone": 7205551234,
  • "buyer_type": "individual",
  • "buyer_external_id": "buyer-abc-123",
  • "price": 100,
  • "payout": 79,
  • "paid_group_amount": 158,
  • "tip": 10,
  • "status": "unassigned",
  • "who_cancelled": "SA",
  • "cancellation_notes": "The showing was cancelled because...",
  • "reposted": true,
  • "message_count": 0,
  • "counter_proposal_count": 0,
  • "reschedulable": true,
  • "rescheduling_requested": true,
  • "repostable": true,
  • "counter_proposable": true,
  • "who_schedules": "showing_agent",
  • "schedule_details": "The showing has already been scheduled, the code is...",
  • "amendable": true,
  • "outstanding_amendment": true,
  • "review_allowed": true,
  • "no_show_eligible": true,
  • "showing_type": "standard",
  • "original_showing_id": 111,
  • "external_id": "abc-123",
  • "nar_buyer_agreement": true,
  • "address": {
    },
  • "user": {
    },
  • "showing_agent": {
    },
  • "showing_agent_cancellation": {
    },
  • "initiating_agent_cancellation": {
    }
}

Property Data Collection

API endpoints related to Property Data Collection appointments. These use the same underlying /showings endpoint as a standard showing, but with showing_type set to property_data_collection. They are documented separately for clarity.

Create Property Data Collection

Create a new PDC (Property Data Collection) appointment.

This is the same underlying endpoint as POST /showings, but with showing_type set to property_data_collection.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
object (PropertyDataCollectionRequest)

Responses

Request samples

Content type
application/json
{
  • "showing_request": {
    }
}

Response samples

Content type
application/json
{
  • "message": "New property data collection successfully created.",
  • "body": [
    ]
}

Users

API endpoints related to Users

Mark a user as a favorite

Mark a user as a favorite

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
type
string
Enum: "add" "remove"

If add is given, the user will be added as a favorite. If 'remove' is given, the user will be removed as a favorite.

Responses

Request samples

Content type
application/json
{
  • "type": "add"
}

Response samples

Content type
application/json
{}

Mark a user as blocked

Mark a user as blocked

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
type
string
Enum: "add" "remove"

If add is given, the user will be added as a blocked user for your account. If 'remove' is given, the user will be removed as a blocked user.

Responses

Request samples

Content type
application/json
{
  • "type": "add"
}

Response samples

Content type
application/json
{}

Add a user to an organization

Add a new user to an organization with the specified user details.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Successfully added user to organization."
}

Remove a user from an organization

Remove a user from an organization, by email address.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
email
required
string

The email address of the user to remove from the organization.

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "message": "Successfully removed user from organization."
}

Consumers

API endpoints related to Consumers

Create Consumer

Create a consumer account under the authenticated brokerage.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Consumer successfully created."
}

Create Consumer Showing

You may create one or more consumer showing(s) using this action. It takes a JSON object containing the parameters of the showing.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
consumer
string

The consumer's email

object

Responses

Request samples

Content type
application/json
{
  • "consumer": "[email protected]",
  • "showing_request": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Showing successfully created."
}

Referrals

API endpoints related to Referrals

Referral Requests

Create a new referral request

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json
required
client_type
required
string
Enum: "buyer" "seller" "both"

The type of client

first_name
required
string

The first name of the referral client

last_name
required
string

The last name of the referral client

email
required
string

The email of the referral client

phone
required
string

The referred person's phone number (exactly 10 digits, no spaces or special characters)

target_price_range
required
string
Enum: "$100,000 - $200,000" "$200,001 - $300,000" "$300,001 - $400,000" "$400,001 - $500,000" "$500,001 - $600,000" "$600,001 - $700,000" "$700,001 - $800,000" "$800,001 - $900,000" "$900,001 - $1,000,000" "$1,000,001+"

The price range of the referral property, either buying or selling

mortgage_status
required
string
Enum: "Unknown / Has Not Applied" "Prequalified" "Preapproved" "Cash Buyer"

The buyer's mortgage status

min_beds
required
integer
Enum: 0 1 2 3 4 5 6 7

The minimum number of bedrooms in the desired referral property

min_baths
required
integer
Enum: 1 2 3 4 5 6 7

The minimum number of bathrooms in the desired referral property

details
string

An detailed explanation of the referral, from one agent to the other.

required
object (Address)

Responses

Request samples

Content type
application/json
{
  • "client_type": "buyer",
  • "first_name": "Christopher",
  • "last_name": "Robbins",
  • "email": "[email protected]",
  • "phone": 7205551234,
  • "target_price_range": "$800,001 - $900,000",
  • "mortgage_status": "Unknown / Has Not Applied",
  • "min_beds": 3,
  • "min_baths": 2,
  • "details": "My client looking for a 3 bedroom, 2 bath home in the Denver area.",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Referral successfully created."
}

Price Suggestions

API Endpoints related to Showing Price Suggestions

Retrieve price suggestions

Get a suggested Showing price based on Showing Type, Zip and Duration

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
query Parameters
showing_type
required
string

The type of showing for which to get price suggestions. Ex/ standard, open_house, etc.

zip
required
string

The zip code for which to get price suggestions.

duration
required
number

The duration of the showing in hours.

Responses

Response samples

Content type
application/json
{
  • "suggested_price": 80,
  • "price_suggestion_algorithm": "zip_average"
}

Webhooks

Showami webhooks

Showing Webhook

A webhook to receive showing data on any change of status for any showing that your user has initiated.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json

A serialized showing object

object

Responses

Request samples

Content type
application/json
{
  • "body": {
    }
}

Showing Rescheduling Webhook

A webhook to receive create/update of a reschedule showing request for a showing that you are associated with.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json

A serialized showing_rescheduling object

object

Responses

Request samples

Content type
application/json
{
  • "body": {
    }
}

Message Webhook

A webhook to receive notification of a new message on any showing that your user has initiated.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json

A serialized message object

object

Responses

Request samples

Content type
application/json
{
  • "body": {
    }
}

Showing Feedback Webhook

A webhook to receive notification of a new showing feedback on any showing that your user has initiated.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json

A serialized Showing Feedback object

object

Responses

Request samples

Content type
application/json
{
  • "body": {
    }
}

Counter Proposal Webhook

A webhook to receive notification of a new showing counter-proposal for any showing that your user has initiated.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)
Request Body schema: application/json

A serialized Counter Proposal object

object

Responses

Request samples

Content type
application/json
{
  • "body": {
    }
}