API - Planyo Web Services

You are here: Planyo » Help » API
The Planyo API lets you perform advanced functions and automate the Planyo reservation system (e.g. import resource data and photos into your site, make automated reservations). To use the API you must be familiar with a programming language such as PHP, Java, Ruby or ASP.NET.

Authentication

Click here to get your API key. You will need it to authenticate all calls made to the API

Request format

At this time the API uses only the REST request format: a simple GET or POST HTTP action. The REST end point URL is: http://api.planyo.com/rest/

Here's a sample test request: http://api.planyo.com/rest/?method=api_test

Required parameters

All API requests require the following parameters:
method - this is the method being called
api_key - your API key (note: the API key is required for all methods except api_test). Click here to get your key

Optional parameters

version - you can optionally specify the version of the API that you're using. Use the value of latest or simply skip this parameter to use the latest API version. The latest version is: 1
language - by specifying a 2-letter (ISO 639-1) language code (all capital letters e.g. EN, DE, FR, ES, IT) you can change the language of the text values returned in the data key

Response format

The Planyo API uses JSON (JavaScript Object Notation) as the response format. This is one of the most popular data formats (more info about this format at json.org) fully supported by all popular scripting languages. The response uses a named array for the output data with text-based keys.

Successful responses

Here's a sample response (returned by the api_test method):
{"data":"API Test Response","response_code":0,"response_message":"Method api_test executed successfully."}

Successful responses will contain the response data in the data key. This is usually another named array but in the response above, it's a simple string 'API Test response'.

The response_code key will always contain the value of 0 (success) and response_message will say Method xyz executed successfully.

Failure responses

Failure responses will contain one of the following failure codes in the response_code key:
1 - authentication error (invalid API key) or invalid method
3 - invalid input data
4 - other error
5 - call rejected because of API overuse; please see below for the allowed limits

API Methods

The following API methods are currently available:
add_custom_property_definition
add_notification_callback
add_reservation_payment
add_resource
add_resource_image
add_site
add_user
add_vacation
apply_coupon
can_make_reservation
do_reservation_action
get_custom_property
get_custom_property_definition
get_event_times
get_form_items
get_invoice_items
get_rental_price
get_reservation_actions
get_reservation_data
get_reservation_payment_amount
get_reservation_products
get_resource_info
get_resource_pricing
get_resource_seasons
get_resource_usage_for_month
get_site_info
get_user_data
is_resource_available
list_additional_products
list_coupons
list_reservation_payments
list_reservations
list_resources
list_sites
list_users
list_vacations
list_vouchers
make_reservation
modify_reservation
modify_resource
modify_user
process_template
remove_custom_property_definition
remove_notification_callback
remove_resource
remove_vacation
reservation_search
resource_search
search_reservations_by_form_item
set_custom_properties
set_custom_property
set_event_times
set_payment_gateway
set_reservation_color
set_resource_availability
set_translation

Sample code

You'll find a PHP sample in the get_all_resources, get_event_times and process_template functions

API playground

You'll find the API playground where you can easily test any API function here

HTTP notifications / webhooks

Planyo can also inform your server whenever an event occurs, such as new reservation being entered or a reservation being cancelled etc. You don't need the API key for this functionality, please see Q222 for the details.

API usage limits

The below limits are set by default. Please contact us if you need higher limits with a detailed explanation of your planned API usage.

The API should not receive simultaneous calls for a single API key. If this happens, the remaining calls will always wait for the original call to complete before being executed. You should therefore never do simultaneous calls, do only one at a time. If you do API calls triggered by user action (e.g. API call on your webpage), this can of course happen but will not cause any issues. The second (and third etc..) simultaneous call will simply get a 1-sec delay before being executed. Your calls will not fail due to this restriction.

We also use a rate limit throttling. In case of a heavy usage in a 10-second period, we'll add delays (1-4 seconds based on total running time in the previous 10 seconds). Also here your calls will not fail but will simply be delayed.

One reason your calls can fail with the error code 5 is if you exceed the usage limits:
  • max 30 calls in 3 seconds
  • max 300 calls in 1 minute
  • max 5000 calls in 1 hour
  • max 20000 calls in 1 day