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": "5551231234",
  • "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": "5551231234",
  • "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": "5551231234",
  • "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": "5551231234",
  • "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 phone number of the referred Person

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": "Person",
  • "last_name": "McPerson",
  • "email": "[email protected]",
  • "phone": 7776665555,
  • "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": {
    }
}