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",
  • "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 opportunities

All Showing opportunities that match the Showing Agent preferences.

Authorizations:
(APIKeyHeaderUserEmailHeaderUserTokenHeader) (APIKeyHeaderoAuth2Password)

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",
  • "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": {
    }
}

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."
}

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": [
    ]
}

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",
  • "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": {
    }
}

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",
  • "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": {
    }
}

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"

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.

desired_commision
required
string
Enum: "15%" "20%" "25%" "30%" "35%"

The desired commission percentage for the referral

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.",
  • "desired_commision": "25%",
  • "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": {
    }
}