Introduction
Welcome to FantasticStay API.
Default base url
The default base URL for FantasticStay API is https://api.fsapp.io/
All data should be sent in JSON format and with a Content-Type: application/json header.
Note: for security reasons, all FantasticStay APIs are served over HTTPS only.
Global params
| Parameter | Type | Values | Default |
|---|---|---|---|
| include_related_objects | int | 0-1 | 0 |
| page | int | positive | 1 |
| per_page | int | positive | 20 |
Filter object
| Parameter | Description | Values |
|---|---|---|
| field | Subject of the filter | |
| operator | Comparison operator | = <> < > <= >= in not_in between not_between |
| value | Value to filter by |
Operators in, not_in, between and not_between expects at least 2 comma-separated values.
Authentication
FantasticStay uses API keys to allow access to the API. You can register a new API key at our developer portal.
FantasticStay expects for the API key to be included in all API requests to the server in a header that looks like the following:
FantasticStay expects for the API key to be included in all API requests to the server in a header that looks like the following:
x-api-key: '<KEY>'
Calendar
Calendar object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| reservation_id | int | Ref to Reservation |
| date | date | Format: YYYY-MM-DD |
| status | string | available unavailable booked |
| currency | string | 3 letter ISO currency code |
| price | float | The price that that day cost |
| note | string |
Get calendar
Get listing calendar
HTTP Request
GET https://api.fsapp.io/calendar
Query Parameters
| Parameter | Type | Values | Default | Example |
|---|---|---|---|---|
| listing_id | int | 1000 | ||
| filters (optional) | array | status price currency | [ { "field": "status", "operator": "<>", "value": "booked" }, { "field": "price", "operator": ">=", "value": 100 } ] | |
| start_date (optional) | date | 2024-01-01 | 2022-01-01 | |
| end_date (optional) | date | 2024-12-31 | 2022-01-31 |
Get single calendar
HTTP Request
GET https://api.fsapp.io/calendar/<ID>
Update calendar
HTTP Request
PUT https://api.fsapp.io/calendar
Query Parameters
| Parameter | Type | Range | Example |
|---|---|---|---|
| listing_id | int | 1000 | |
| start_date | date | 2018-01-01 | |
| end_date | date | 2018-01-31 | |
| is_available | int | 0-1 | 0 |
| price (optional) | float | 123.45 | |
| note (optional) | string | Note |
Custom stay
Custom stay object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| name | string | |
| date_start | date | Format: YYYY-MM-DD |
| date_end | date | Format: YYYY-MM-DD |
| min_stay | int | Minimum number of nights a guest can book |
| checkin_weekday | int | Numeric representation of the day of the week: 0 (for Sunday) through 6 (for Saturday) |
Get custom stay
Get listing custom stay rules
HTTP Request
GET https://api.fsapp.io/custom_stay
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| listing_id | int | 1000 |
Set custom stay
Create or change custom stay rule
HTTP Request
POST https://api.fsapp.io/custom_stay
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| listing_id | int | 1000 |
| default_min_stay | int | 1 |
| default_max_stay | int | 31 |
| custom_stay | array | [ { "min_stay": 3, "date_start": "YYYY-MM-DD", "date_end": "YYYY-MM-DD", "checkin_weekday": null }, { "min_stay": 2, "date_start": null, "date_end": null, "checkin_weekday": 6 } ] |
Guests
Guest object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| channel_guest_id | int | Channel unique id |
| name | string | |
| string | ||
| phone | string | |
| location | string | |
| is_verified | int | 0-1 |
| has_facebook | int | 0-1 |
| has_governmentid | int | 0-1 |
| has_email | int | 0-1 |
| has_phone | int | 0-1 |
| reviews | int | # of reviews |
| about | string | |
| work | string | |
| languages | [string] | |
| original_file | string | Guest picture URL |
| notes | string | |
| integration_id | int | Ref to Integration |
Get guest
HTTP Request
GET https://api.fsapp.io/guests/<ID>
List guests
HTTP Request
GET https://api.fsapp.io/guests
Query Parameters
| Parameter | Type | Values | Example |
|---|---|---|---|
| listing_id | int | 1000 | |
| filters (optional) | array | channel_guest_id phone email | [ { "field": "channel_guest_id", "operator": "=", "value": "12345" } ] |
Inbox
Thread object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| channel_thread_id | int | Channel unique id |
| integration_id | int | Ref to Integration |
| listing_id | int | Ref to Listings |
| reservation_id | int | Ref to Reservation |
| guest_id | int | Ref to Guest |
| answered | int | 0-1 |
| channel_unread | int | 0-1 |
| preview | string | Last message text |
| last_message | datetime | The time of last message YYYY-MM-DD HH:mm:ss |
| nights | int | |
| guests | int | |
| start_date | date | Inquiry start date YYYY-MM-DD |
| is_archived | int | 0-1 |
Message object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| message | string | |
| notes | string | |
| guest_id | int | Ref to Guest |
| guest_name | string | |
| guest_thumb | string | Guest picture URL |
| created | datetime | The time of last message YYYY-MM-DD HH:mm:ss |
| is_automatic | int | 0-1 |
Get thread
HTTP Request
GET https://api.fsapp.io/inbox/<ID>
List threads
HTTP Request
GET https://api.fsapp.io/inbox
Post a reply
HTTP Request
POST https://api.fsapp.io/inbox/reply
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| thread_id | int | 12345 |
| message | string | Thank you for your interest! |
Integrations
Integration object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| nickname | string | |
| picture | string | URL |
| user | string | |
| first_name | string | |
| last_name | string | |
| full_name | string |
Get integration
HTTP Request
GET https://api.fsapp.io/integrations/<ID>
List integration
HTTP Request
GET https://api.fsapp.io/integrations
Listings
Listing object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| currency | string | 3 letter ISO currency code |
| channel_listing_id | int | Channel unique id |
| listing_type | int | |
| room_type | int | |
| instant_booking | int | 0-1 |
| name | string | |
| nickname | string | |
| security_deposit | float | |
| cleaning_fee | float | |
| extra_person | float | Extra person price per night |
| guests_included | int | |
| default_daily_price | float | |
| weekend_price | float | |
| weekly_price_factor | float | |
| monthly_price_factor | float | |
| min_nights | int | |
| max_nights | int | |
| checkin_start | time | Format: HH:mm |
| checkin_end | time | Format: HH:mm |
| checkout | time | Format: HH:mm |
| cancel_policy* | int | 1 - Strict 2 - Moderate 3 - Flexible 4 - Strict |
| price_tip | float | |
| weekly_tip | float | |
| monthly_tip | float | |
| max_notice_days | int | |
| min_notice_hours | int | |
| tags | [string] | |
| thumbnail_file | string | URL |
| country | string | |
| countrycode | string | 3 letter iso country code |
| state | string | |
| city | string | |
| city_id | int | |
| zipcode | string | |
| street | string | |
| lat | float | |
| lng | float | |
| timezone_offset | string | Format: HH:mm |
| timezone | string | |
| price_markup | float | |
| master_calendar | int | 0-1 |
| service_pms | int | 0-1 |
| service_communication | int | 0-1 |
| revenue_target | float | |
| high_season_rate | float | |
| low_season_rate | float | |
| lowest_rate | float | |
| back_to_back | int | |
| guests_wo_reviews | int | |
| guests_unverified | int | |
| guest_explaination | int | |
| guest_house_rules | int | |
| guests_young | int | |
| booking_last_minute | int | |
| booking_future_period | int | |
| hesitate | int | |
| booking_additional | int | |
| communication_sla | int | |
| communication_whitelabel | int | |
| communication_phone | int | |
| checkin_type | int | 0-1 |
| lockbox_code | int | |
| post_cleaning | int | |
| post_maintenance | int | |
| main_contact | string | |
| emergency_contact | string | |
| checkin_contact | string | |
| cleaning_contact | string | |
| maintenance_contact | string | |
| integration_id | int | Ref to Integration |
| parent_id | int | Ref to Parent listing |
| revenue_target_1 | int | |
| revenue_target_2 | int | |
| revenue_target_3 | int | |
| revenue_target_4 | int | |
| revenue_target_5 | int | |
| revenue_target_6 | int | |
| revenue_target_7 | int | |
| revenue_target_8 | int | |
| revenue_target_9 | int | |
| revenue_target_10 | int | |
| revenue_target_11 | int | |
| revenue_target_12 | int | |
| listed_channel_listing_id | int | |
| custom_fields | [string] |
Get listing
Get listing information
HTTP Request
GET https://api.fsapp.io/listings/<ID>
Query Parameters
| Parameter | Type | Range | Default | Example |
|---|---|---|---|---|
| guests (optional) | int | 2 | ||
| min_rating (optional) | int | 1-5 | 4 | |
| start_date (optional) | date | 2024-01-01 | 2022-01-01 | |
| end_date (optional) | date | 2024-12-31 | 2022-01-31 |
List listings
Get all active listings
HTTP Request
GET https://api.fsapp.io/listings
List children
HTTP Request
GET https://api.fsapp.io/listings/children/<ID>
Get available listings
Search for available listings
HTTP Request
GET https://api.fsapp.io/listings/available
Query Parameters
| Parameter | Type | Range | Default | Example |
|---|---|---|---|---|
| start_date | date | 2018-01-01 | ||
| end_date | date | 2018-01-31 | ||
| guests | int | 2 | ||
| min_rating (optional) | int | 1-5 | 4 |
Listing price
Get listing price
HTTP Request
GET https://api.fsapp.io/listings/price
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| listing_id | int | 1000 |
| start_date | date | 2018-12-01 |
| end_date | date | 2018-12-03 |
| guests | int | 3 |
Reservations
Reservation object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| channel_reservation_id | int | Channel unique id |
| listing_id | int | Ref to Listing |
| parent_listing_id | int | Ref to Parent listing |
| guest_id | int | Ref to Guest |
| integration_id | int | Ref to Integration |
| inbox_id | int | Ref to Inbox thread |
| status_code | int | |
| status | string | accepted denied cancelled |
| status_description | string | |
| currency | string | 3 letter ISO currency code |
| price_per_night | float | |
| base_price | float | |
| security_price | float | |
| extras_price | float | |
| cleaning_fee | float | |
| channel_commission | float | |
| service_charge | float | |
| subtotal | float | |
| payout_price | float | |
| tax_amount | float | |
| transaction_fee | float | |
| sum_refunds | float | |
| source | string | |
| confirmation_code | string | |
| checkIn | date | Format: YYYY-MM-DD |
| checkOut | date | Format: YYYY-MM-DD |
| planned_arrival | time | Format: HH:mm |
| planned_departure | time | Format: HH:mm |
| confirmed_at | datetime | Format: YYYY-MM-DD HH:mm |
| nights | int | |
| guests | int | |
| adults | int | |
| children | int | |
| infants | int | |
| advance_days | int | |
| beds_to_be_prepared | int | |
| notes | string | |
| extra_info | string | |
| cancel_penalty | string | |
| cleaning_notes | string |
Get reservation
HTTP Request
GET https://api.fsapp.io/reservations/<ID>
List reservations
Get listing reservations
HTTP Request
GET https://api.fsapp.io/reservations
Query Parameters
| Parameter | Type | Values | Example |
|---|---|---|---|
| listing_id (optional) | int | 1000 | |
| filters (optional) | array | checkIn checkOut source status payout_price confirmation_code nights advance_days guests | [ { "field": "source", "operator": "=", "value": "Airbnb" }, { "field": "payout_price", "operator": ">=", "value": 1000 }, { "field": "status", "operator": "in", "value": "accepted,pending" } ] |
| sort (optional) | string | checkIn checkOut confirmed_at |
Create reservation
Create new reservation
HTTP Request
POST https://api.fsapp.io/reservations
Query Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| listing_id | int | 1000 | |
| start_date | date | 2018-12-01 | |
| end_date | date | 2018-12-03 | |
| guests | int | 3 | |
| name | string | Guest name | John Smith |
| string | Guest email | [email protected] | |
| phone | string | Guest phone | +1-541-754-3010 |
| total_price | float | 560.00 | |
| note | string | Approximate time of arrival: between 13:00 and 14:00 | |
| source | string | Booking.com |
Push Notifications
Get notification
HTTP Request
GET https://api.fsapp.io/webhooks/<ID>
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| id | int | 1 |
List notifications
HTTP Request
GET https://api.fsapp.io/webhooks
Create notification
HTTP Request
POST https://api.fsapp.io/webhooks
Query Parameters
| Parameter | Type | Values | Example |
|---|---|---|---|
| url | string | https://api.example.com | |
| notification_type | string | new_reservation update_reservation | { "notification_type": "update_reservation" } |
| auth | string | header params | { "header": { "x-api-key": "ApiKey" } } |
Delete Notification
HTTP Request
DELETE https://api.fsapp.io/webhooks
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| subscription_id | int | 1 |
Custom Fields
Get Custom Field
HTTP Request
GET https://api.fsapp.io/custom_fields/<ID>
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| id | int | 1 |
List Custom Fields
HTTP Request
GET https://api.fsapp.io/custom_fields
Create Custom Field
HTTP Request
POST https://api.fsapp.io/custom_fields
Query Parameters
| Parameter | Type | Values | Example |
|---|---|---|---|
| ref | string | listing reservation | listing |
| name | string | ||
| type | string | text long_text number date time bool option | option |
| option_values | array | { "option1": "1", "option2": "2" } |
Update Custom Field
HTTP Request
POST https://api.fsapp.io/custom_fields/update
Query Parameters
| Parameter | Type | Values | Example |
|---|---|---|---|
| custom_field_id | int | ||
| name | string | ||
| type | string | text long_text number date time Yes/No option | text |
Delete Custom Field
HTTP Request
DELETE https://api.fsapp.io/custom_fields
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| custom_field_id | int | 1 |
Set Custom Field Values
HTTP Request
POST https://api.fsapp.io/custom_fields/set_values
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| custom_field_id | int | 1 |
| value | string | Custom field value |
| listing_ids | array | { "listing_ids": [ 1, 2 ] } |
| reservation_ids | array | { "reservation_ids": [ 1 ] } |
Reviews
Review object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| reservation_id | int | Ref to Reservation |
| listing_id | int | Ref to Listing |
| parent_listing_id | int | Ref to Parent listing |
| guest_id | int | Ref to Guest |
| integration_id | int | Ref to Integration |
| created | datetime | Format: YYYY-MM-DD HH:mm:ss |
| rating | int | 1-5 |
| accuracy_rating | int | 1-5 |
| checkin_rating | int | 1-5 |
| clean_rating | int | 1-5 |
| communication_rating | int | 1-5 |
| location_rating | int | 1-5 |
| value_rating | int | 1-5 |
| comments | string | |
| accuracy_comments | string | |
| checkin_comments | string | |
| clean_comments | string | |
| communication_comments | string | |
| improve_comments | string | |
| location_comments | string | |
| value_comments | string |
Get review
HTTP Request
GET https://api.fsapp.io/reviews/<ID>
List reviews
HTTP Request
GET https://api.fsapp.io/reviews
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| reservation_id (optional) | int | 9876 |
| listing_id (optional) | int | 1000 |
Search
Search for everything
HTTP Request
GET https://api.fsapp.io/search
Query Parameters
| Parameter | Type | Values |
|---|---|---|
| q | string | |
| type (optional) | string | guests reservations listings integrations |
Transactions
Transaction object
| Attribute | Type | Description |
|---|---|---|
| id | int | Unique id |
| channel_transaction_id | int | Channel unique id |
| currency | string | 3 letter ISO currency code |
| amount | float | |
| arrival_date | date | Format: YYYY-MM-DD |
| charge_date | date | Format: YYYY-MM-DD |
| is_competed | int | 0-1 |
| reservation_id | int | Ref to Reservation |
| code | string | |
| details | string | |
| notes | string | |
| payout_type | int | 0-1 |
| source | string |
Get transaction
HTTP Request
GET https://api.fsapp.io/transactions/<ID>
List transactions
HTTP Request
GET https://api.fsapp.io/transactions
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| reservation_id (optional) | int | 1000 |
| listing_id (optional) | int | 9876 |
Create transaction
HTTP Request
POST https://api.fsapp.io/transactions
Query Parameters
| Parameter | Type | Range | Example |
|---|---|---|---|
| reservation_id | int | 9876 | |
| amount | float | 260 | |
| currency | string | USD | |
| charge_date | date | 2018-12-01 | |
| arrival_date | date | 2018-12-03 | |
| is_completed | int | 0-1 | 0 |
| details (optional) | string |
Update transaction
HTTP Request
PUT https://api.fsapp.io/transactions/<ID>
Query Parameters
| Parameter | Type | Range | Example |
|---|---|---|---|
| amount (optional) | float | 560 | |
| currency (optional) | string | USD | |
| charge_date (optional) | date | 2018-12-01 | |
| arrival_date (optional) | date | 2012-12-03 | |
| is_completed (optional) | int | 0-1 | 1 |
| details (optional) | string | Charged |
Users
User object
Get user
HTTP Request
GET https://api.fsapp.io/users/<ID>
List users
HTTP Request
GET https://api.fsapp.io/users
Update user
HTTP Request
PUT https://api.fsapp.io/users/<ID>
Query Parameters
| Parameter | Type | Range | Example |
|---|---|---|---|
| is_active | int | 0-1 | 1 |
Assign role
HTTP Request
POST https://api.fsapp.io/users/assign_role
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| user_id | int | 230 |
| role | string | Listing Owner |
Unassign role
HTTP Request
DELETE https://api.fsapp.io/users/unassign_role
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| user_id | int | 230 |
| role | string | Listing Owner |
Add listing
HTTP Request
POST https://api.fsapp.io/users/add_listing
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| user_id | int | 230 |
| listing_id | int | 1000 |
Remove listing
HTTP Request
DELETE https://api.fsapp.io/users/remove_listing
Query Parameters
| Parameter | Type | Example |
|---|---|---|
| user_id | int | 230 |
| listing_id | int | 1000 |
Errors
Platform API uses the following error codes:
| Error code | Meaning |
|---|---|
| 400 | Bad request |
| 401 | Unauthorized – Your API key is wrong |
| 403 | Forbidden |
| 404 | Not Found |
| 405 | Method Not Allowed – You tried to access with an invalid method |
| 500 | Internal Server Error – We had a problem with our server. Try again later. |
| 503 | Service Unavailable – We’re temporarially offline for maintanance. Please try again later. |