Vreasy API
Documentation

API Reference

The Vreasy API allows you to push and pull property, reservation, listing and pricing information to and from the Vreasy system. It is organized around REST, following a "REST-Like" architecture. It is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. Please read below to find out more about what you could do with our API and all our reference material.

We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (you must request this if needed). JSON will be returned in all responses from the API, including errors.

Documentation for this API is a work in progress. We are working hard to enable documentation for you, but for now has been done on a request basis.

If you have a question please contact us:


API Features

  • Partial responses & updates
  • Nested resources expansion
  • Autodiscovery of related resources via Links (pagination, subscriptions, etc)
  • Cursor based pagination
  • Basic filter using any of the resource's fields (apart from documented query filters)
  • Data validation
  • Errors

Partial Responses & Partial Updates

When retrieving data, you can always specify which fields you would like to get back in the response. Use the fields query parameter with a comma separated list of fields that you want to see in the response. To get all fields use the * as a wild-card.

Here's an example to get the guest's first name, last name and email address from all your enquiries:

curl -u "<your-api-key>:" -X GET "https://www.vreasy.com/api/reservations?status=ENQUIRY&expand=guest&fields=guest/fname,guest/lname,guest/email"

The response of this call will look like the one below:

  [
    {
      "guest": {
        "fname": "John",
        "lname": "Doe",
        "email": "johndoe@example.com"
      }
    },
    {
      "guest": {
        "fname": "Jane",
        "lname": "Doe",
        "email": "janedoe@example.com"
      }
    },
    {
      "guest": {
        "fname": "Johnnie,
        "lname": "Doe",
        "email": "johnniedoe@example.com"
      }
    }
  ]

When retrieving data, you can always specify which fields you would like to get back in the response. Use the fields query parameter with a comma separated list of fields that you want to see in the response. To get all fields use the * as a wild-card.

Here's an example to get the guest's first name, last name and email address from all your enquiries:

curl -u "<your-api-key>:" -X GET "https://www.vreasy.com/api/reservations?status=ENQUIRY&expand=guest&fields=guest/fname,guest/lname,guest/email"

When modifying data, you are not required to send the whole object contents in your request. In fact you are encouraged to only send those pieces of data that have been updated.

curl -X PUT -u "<your-api-key>:" "https://www.vreasy.com/api/account"\
 -H "Content-Type: application/json"\
 -d '{"company_name":"Vreasy - Put Your Rentals On Autopilot"}'

Nested Resources Expansion

Many objects contain the id of another related object or other embedded data. These objects can be expanded inline in a single request using the expand request parameter, eg:

curl -u "<your-api-key>:" -X GET https://www.vreasy.com/api/properties?expand=images,featured_image

To discover what data you are able to expand or not, look for the empty associated objects - images:{ }, that you might get in your responses. You are also welcome to checkout a resource's schema in our documentation. To have a better understanding of this 'expand' feature, take a look at the example below:

Suppose you want to see the payment whose ID is 1. You will have to do this:

curl -u "<your-api-key>:" -X GET https://www.vreasy.com/api/payments/1

And you will get something like:

  {
    "id": "1",
    "payment_type_id": "1",
    "payer_user_id": "7",
    "payee_user_id": "1",
    "reservation_id": "12",
    "due_date": "2016-03-23",
    "status": ""unpaid"",
    "amount": "0",
    "total": "0",
    "amount_paid": "0",
    "payment_type": { },
    "payee": { },
    "reservation": { }
  }

As you can see, the 'expandable' fields are payment_type:{ }, payee:{ } and reservation:{ }. We can now expand any of these by doing:

curl -u "<your-api-key>:" -X GET https://www.vreasy.com/api/payments/1?expand=payment_type

And you will get the same response as above but, in this example, with the field payment_type:{ } expanded.

  {
    "id": "1",
    "payment_type_id": "1",
    "payer_user_id": "7",
    "payee_user_id": "1",
    "reservation_id": "12",
    "due_date": "2016-03-23",
    "status": ""unpaid"",
    "amount": "0",
    "total": "0",
    "amount_paid": "0",
    "payment_type": {
      "id": "1",
      "name": "Initial Deposit",
      "user_id": "null",
      "position": "null",
    },
    "payee": { },
    "reservation": { }
  }

Autodiscovery of related resources via Links

We use the Link header (RFC 5988) to augment your discoverability of the API via standarized Link relations. Whenever you are browsing a collection of resources, the API will hint you with "next" & "prev" links that point where you should make a new request to continue browsing.

curl -IX GET -u "<your-api-key>:" "https://www.vreasy.com/api/reservations"

You might see something like this, as part of the HTTP Headers of your response:

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://www.vreasy.com/api/reservations?after=1092887>; rel="next"

Another possibility would be "monitor" which gives you the api endpoint to use to subscribe to notifications for that resource.

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://www.vreasy.com/api/listings/1234/subscriptions>; rel="monitor"

Cursor based pagination

Let Vreasy build this for you and use Link found in the response headers with a rel next & prev instead of directly setting this query's parameters!

To transverse a collection of resources, you might have to paginate over the collection. Vreasy supports cursor pagination, where you indicate the id of the resource that you would like to be used as the "pivot" in order to move forward or backward in the collection.

For this, all the endpoints that return a collection (a json array) are susceptible to being paginated. You can get the next part of of the collection using the after query parameter and the previous part of the collection using the before query parameter.

Autodiscovery of monitorable resources via Links

We use the Link header (RFC 5988) to augment your discoverability of the API via standarized Link relations. Whenever you are browsing a resource, the API will hint you with "monitor" link to where to subscribe for updates.

curl -IX GET -u "<your-api-key>:" "https://www.vreasy.com/api/listings/1092887"

You might see something like this, as part of the HTTP Headers of your response:

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://www.vreasy.com/api/listings/subscribe>; rel="monitor"

Simple filter using any resource's column

Again, let Vreasy assist you when filtering your data. When traversing a collection of resources, you can use most of its fields to filter the collection's response. Vreasy understands several logical operators:

  • = equal to: to filter reservations with an Enquiry status use status=ENQUIRY
  • >, < bigger or smaller than: to filter reservations updated after/before a certain date use updated_at=>2015-01-01
  • >=, <= bigger or equal / smaller or equal than**
  • ! not equal to
  • =*value* equal to with wildcard: to filter properties with a prefix in the title use title=*prefix*
  • NULL & !NULL value is equal to null or it is not equal to null**

Data validation

Whenever you get a 422 HTTP response code, you will get a list of issues that we found in the data you've sent to the Vreasy API.

Errors

Vreasy API takes advantage of the HTTP protocol standard, reusing many of the standarized error codes. As a guideline this is how we use the status codes in Vreasy:

  • Codes in the 2xx range means that everything went ok.
  • Codes in the 3xx range means that the "client" needs to be redirected to some other URL
  • Codes in the 4xx range means that the "client" or the request has or made some kind of error when performing the request.
  • Codes in the 5xx range means that the server has some kind of error (please let us know about these ones!)

API Authentication (api-keys & HTTP Basic)

Vreasy uses HTTP Basic Authentication and enforces HTTP over a secure TLS channel, so that your API key is securely encrypted

Vreasy uses simple api-keys to authenticate the API's requests. As a Vreasy User you can create as many api-keys as you need and distribute them among your developers. You can also revoke any solution provider api-key (though you might not want to do that!).

Solution providers (Vreasy Partners) will get 2 types of api-keys, one with read-only access to many of the resources that are authorized to be read, and individual api-keys for each Vreasy User using their solution where they could operate on behalf of.

To use your api-key and authenticate your request, you just have to specify it as the username using the HTTP Basic Access Authentication.

curl -u "<your-api-key-here>:" -X GET "https://www.vreasy.com/api/account"

Make sure to leave the trailing double colon in the example above, so that curl won't ask for a password. Yes, use the api-key as the username with no password

Solution Provider

You will receive your own api-key credential to access certain parts of the system, but when operating on behalf of a user, you will use individual api-keys that will authenticate you and give you access to some of the user's resources. The user will be able to revoke this key at any time from the account settings screen.

How to obtain all the individual api-keys to act on behalf of users.

As a Vreasy Partner, you will be able to access the api-keys available to you using the /api/keys endpoint, where you will get a list of all the user's api-keys assigned to you.

curl -u "<your-api-key-here>:" -X GET "https://www.vreasy.com/api/keys"

IMPORTANT: To avoid rate limit problems, you should store all these individual api keys somewhere on your system. This way, it won't be necessary to be calling GET 'api/keys' each time you want to act on behalf of a user (as you already have them stored in your system). Be aware individual api keys may be updated, so you will get 401 Unauthorized errors. You may update them all again in your system.

Obtain new user's individual api-keys

If you know there are new users and you want to obtain their individual keys, you can make the same request but ordering them by creation date. Most recently created user will appear first. This way, you can loop all the users and store them until you find a user already present in your system. That means there are no more new users, so you can ignore the rest of the entries.

curl -v -u "<your-api-key-here>:" -X GET "https://www.vreasy.com/api/keys?order_by=created_at&order_direction=desc"

Example:

[
  {
    "id": 294,
    "key": "unique_key_to_act_on_user_294_behalf",
    "user_id": 12002,
    "listor_id": 121,
    "role_id": 9,
    "listor": {},
    "user": {},
    "role": {},
    "created_at": "2016-01-27 10:55:11",
    "updated_at": "2016-05-24 16:30:43"
  },
  {
    "id": 286,
    "key": "unique_key_to_act_on_user_283_behalf",
    "user_id": 1046,
    "listor_id": 121,
    "role_id": 9,
    "listor": {},
    "user": {},
    "role": {},
    "created_at": "2016-01-22 08:49:01",
    "updated_at": "2016-01-22 08:49:01"
  }
]

Resources Available to Solution Providers api-keys

  • Api-Keys
  • Channel's details (available connections, names, etc)
  • Property & Listing details managed by this partner
  • Calendar & Reservation details from listings managed by this partner
  • Rate & Pricing details from listings managed by this partner
  • Ability to generate new listing connections

How to synchronize the availability calendar

1) Full sync

You can make a full sync of a listing's calendar's current state by calling the following api endpoint:

curl -u your_api_key: -X GET https://www.vreasy.com/api/calendars?property_ids={:property_id}

You will get a full list of date ranges with their corresponding status: CONFIRMED, UNAVAILABLE, BLOCKEDBYOWNER or CANCELLATIONREQUESTED

Example:

{
   "1234":[
      {
         "id":1,
         "listing_id":1234,
         "status":"CONFIRMED",
         "checkin":"2015-10-01 11:00:00",
         "checkout":"2015-10-05 09:00:00",
         "portal_uid":"BHXKZ8"
      },
      {
         "id":2,
         "listing_id":1234,
         "status":"CANCELLATIONREQUESTED",
         "checkin":"2015-10-10 11:00:00",
         "checkout":"2015-10-12 09:00:00",
         "portal_uid":"ZFS83A"
      },
      {
         "id":1386896,
         "listing_id":1234,
         "status":"UNAVAILABLE",
         "checkin":"2016-02-21 12:00:00",
         "checkout":"2016-02-26 10:00:00",
         "portal_uid":null
      }
   ]
}

The response is paginated. Use the Link http response header to navigate from one page to another.

2) Get the availability updates for a given datetime

If you subscribed to availability_update events for a listing, whenever the availability changes for that listing, you will receive a notification containing:

  • The listing id whose availability has changed
  • The datetime of when it has changed
  • The url to call in order to get the changes
  • The api key you used to subscribe and that you should use to do the API call

Example:

{
   "event":{
      "event":"availability_update",
      "acting_user":1234,
      "pm_user_id":1234,
      "acting_api":null,
      "acting_agent":"user",
      "resource_id":4567,
      "resource_type":"listing",
      "updated_at":"2015-07-29T10:30:29+00:00",
      "update_url":"http://www.vreasy.dev/api/calendars?property_ids=1234&last_updated=2015-07-23T15%3A05%3A15%2B00%3A00"
   },
   "api_key":"ka8e1e5cs1s7kldw8443k05dkt3kor04sh6gc"
}

curl -u your_api_key: -X GET https://www.vreasy.com/api/calendars?property_ids={:property_id}&last_updated={:last_updated}

where :last_updated is the datetime based on when you want the updates.


How to synchronize rates (consuming)

Vreasy provides two endpoints with information about pricing rates. Both endpoints were built mainly to consume the rate's data, but they were designed with different sync strategies in mind:

  • Pushing strategy: upon an update of a listing's rate you will get an incremental changeset with the changes to the rate's collection. This is the recommended way to synchronize, since we only communicate changes from a specific date and synchronization could happen almost in real time.
  • Polling strategy: poll for changes use the /api/rates endpoint. We do not recommend this, since it is very inefficient and changes are applied with a lot of latency since the user makes them on our backends.

In order to synchronize using the pushing strategy, you will have to:

  • Make a full initial sync using the regular /api/rates endpoint. Save the current time to be used in your next synchronization step.
  • Subscribe to the listing's update_rate event to be notified on the URL of your choice when the rates collection changes (create, update, delete)
  • Upon notification, use the /api/rate-updates to get all the events that have happened since the last time you have done a synchronization (use your saved "last time of sync").
  • The events have all the data you'll need to catch up with the changes in your own copy of the collection. Our events provide a snapshot of how the custom rate was before the change and a changeset with the new values of the rate.
  • Ensure that whenever your system gets up and running, or when it becomes available again, you will perform an incremental sync using the recorded last sync time. You have to do this to avoid getting out of sync when your system is not responsive for more than one hour. Vreasy will try to deliver notifications to unavailable systems for over one hour. Vreasy considers a system as unavailable when the connection times out or when the response from your system has an HTTP error status code (4xx, 5xx).

1) Full sync

Before you can start receiving updates on the listing's rates, you must do a full sync of the current state of the rates. This can be done by calling the following API endpoint.

Example:

curl -u your_api_key: -X GET https://www.vreasy.com/api/rates?listing_id=1234&date_start=2015-09-01&date_end=2015-12-31

You will have to "browse" the date ranges between today and the future until you see no more custom rates. You do so by consuming the collection of rates for a given listing and iterating over all the rates using the Link header cursors if needed.

The rates endpoint will always provide at least one rate using the default property/listing pricing settings. It will also use these default settings to fill in the blank gaps that would appear in between the custom rates. These "default rates" are easily identifiable since they have a null id value.

After doing a full sync you must store the timestamp of that sync. Use the Date header value from the HTTP response from Vreasy. You will then have to use that timestamp the next time you want to do an incremental sync.

2) Incremental syncs

If you are subscribed to the update_rate for a listing, every time that we detect a change in the rates you will receive a notification with the following information: * the listing id whose rates have changed * when the change has occurred * the URL to call in order to sync * the API key you used to subscribe and that you should use to do the API call

Example of message:

{
   "event":{
      "event":"rate_update",
      "acting_user":1234,
      "pm_user_id":1234,
      "acting_api":null,
      "acting_agent":"user",
      "resource_id":4567,
      "resource_type":"listing",
      "updated_at":"2015-07-29T10:30:29+00:00",
      "update_url":"http://www.vreasy.dev/api/rate-updates?listing_id=1234"
   },
   "api_key":"ka8e1e5cs1s7kldw8443k05dkt3kor04sh6gc"
}

You will have to append the last sync timestamp that you used to the update_url.

Example:

curl -u your_api_key: -X GET https://www.vreasy.com/api/rate-updates?listing_id=1234?since={:since}

How to sync?

This endpoint returns a step-by-step transaction of which changes happened in the rates since the given timestamp. You will have to apply those changes one by one in the given order. When this is done, you will then have the correct state of the rates at that moment.

Each step can be one of the following actions:

  • destroy This scenario happens when an existing rate is removed. Either because it has been specifically removed by a user or because a new rate has overlapped it completely, making it invalid.

    You will receive an object describing the deleted rate:

    • listing_id: the listing id the rate belongs to
    • created_at: the datetime the rate was deleted
    • event: "destroy"
    • snapshot: a snapshot of the rate before it was deleted

    Example:

    {
        "listing_id": 1234,
        "created_at": "2015-09-29 13:29:38",
        "event": "destroy",
        "snapshot": {
            "id": 1,
            "listing_id": 1234,
            "rate": {
                "version": 4,
                "security_deposit": 300,
                "currency_id": 1,
                "ui_setting_pm": false,
                "ui_setting_guest": false,
                "daily_default": 210,
                "weekly_percentage_decrease": 0,
                "monthly_percentage_decrease": 0,
                "weekend_increase": 10,
                "minimum_stay": 3,
                "maximum_stay": 30,
                "extra_person_fee": 25,
                "extra_person_fee_trigger_amount": 3,
                "late_checkout_fee": null,
                "late_checkin_fee": 30,
                "early_checkin_fee": null,
                "cleaning_fee": 80,
                "has_tourist_tax": false,
                "cancellation_policies": [
                    {
                        "refund_percentage": 80,
                        "days_before_checkin_due": 14
                    }
                ],
                    "listing_id": 1234
                },
            "date_start": "2015-10-10",
            "date_end": "2015-10-28"
        }
    }
    
    
  • update This scenario happens when a rate's start and/or end date has changed. This happens when a new rate partially overlapped with an existing rate, making part of it invalid.

    You will receive an object describing the updated rate:

    • listing_id: the listing id the rate belongs to
    • created_at: the datetime the rate was updated
    • event: "update"
    • snapshot: a snapshot of the rate before it was updated.
    • changeset: the changes that have been applied to the rate. You should update your system with that new information
    {
        "listing_id": 1234,
        "created_at": "2015-10-02 10:05:52",
        "event": "update",
        "snapshot": {
            "id": 2,
            "listing_id": 1234,
            "rate": {
                "version": 4,
                "security_deposit": 300,
                "currency_id": 1,
                "ui_setting_pm": false,
                "ui_setting_guest": true,
                "daily_default": 114,
                "weekly_percentage_decrease": 0,
                "monthly_percentage_decrease": 0,
                "weekend_increase": 10,
                "minimum_stay": 3,
                "maximum_stay": 30,
                "extra_person_fee": 25,
                "extra_person_fee_trigger_amount": 3,
                "late_checkout_fee": null,
                "late_checkin_fee": 30,
                "early_checkin_fee": null,
                "cleaning_fee": 80,
                "has_tourist_tax": false,
                "cancellation_policies": [],
                "listing_id": 1234
            },
            "date_start": "2015-11-01",
            "date_end": "2015-11-07"
        },
        "changeset": {
            "date_start": "2015-11-04"
        }
    },
    
  • create This scenario happens when a new rate is created either in an existing gap or after scenario destroy or update.

    You will receive an object describing the new rate:

    • listing_id: the listing id the rate belongs to
    • created_at: the time the rate was created
    • event: "create"
    • changeset: the newly created rate
    {
        "listing_id": 1234,
        "created_at": "2015-10-02 10:06:25",
        "event": "create",
        "changeset": {
            "rate": {
                "version": 4,
                "security_deposit": 300,
                "currency_id": 1,
                "ui_setting_pm": false,
                "ui_setting_guest": true,
                "daily_default": 134,
                "weekly_percentage_decrease": 10,
                "monthly_percentage_decrease": 15,
                "weekend_increase": 10,
                "minimum_stay": 3,
                "maximum_stay": 30,
                "extra_person_fee": 25,
                "extra_person_fee_trigger_amount": 3,
                "late_checkout_fee": null,
                "late_checkin_fee": 30,
                "early_checkin_fee": null,
                "cleaning_fee": 80,
                "has_tourist_tax": false,
                "cancellation_policies": [
                    {
                        "refund_percentage": 80,
                        "days_before_checkin_due": 14
                    }
                ]
            },
            "date_start": "2015-10-23",
            "date_end": "2015-11-04",
            "listing_id": 1234
        }
    }
    

Again, after each incremental sync, you will have to store the timestamp of that last sync to use it the next time. Use the Date header value from the HTTP response from Vreasy.


Subscribing to resources' changes and events using API Webhooks

Webhooks allow your system to know when something happens on Vreasy. You could subscribe to a resource's event and we’ll post data to the URL you specify when one of those events occurs.

To see which resources support subscription to its events' notifications, checkout if they have a /subscription endpoint in the endpoints reference below.

Vreasy supports two main category of events: - events for resources' changes such us: created, updated, deleted - events to support data-sync processes like: rate_update, availability_update, etc.

You could subscribe to the following API resource's events:

Resource Event names
Listings listing_create, listing_update, listing_destroy, rate_update, availability_update
Reservations reservation_create, reservation_update
Users user_update, api_key_update

All the events share a general schema (more or less). Below is a JSON example of what you would receive:

{
   "event":{
      "event": "listing_update",
      "acting_user": 1234,
      "pm_user_id":1234,
      "acting_api": 12,
      "acting_agent": "user",
      "resource_id": 4567,
      "resource_type": "listing",
      "updated_at": "2015-07-29T10:30:29+00:00",
      "changeset": "title",
      "update_url": "https://www.vreasy.com/api/listing?fields=title"
   },
   "api_key": "xa8e1efcz1s7kldwy341k09dkt35tr04sh6gc"
}

The apikey is the key you have used to subscribe and the one that you should use to read further info from the `updateurl`

The notification event payload is explained as follows:

Field Description
event An identifier for the type of event that occurred. It could be one of the followings: listing_create, listing_update, listing_destroy, reservation_create, reservation_update, user_update, api_key_update (on the user resource), rate_update or availability_update.
acting_user The user_id of the user (or the user that has been acted on behalf of, e.g. action done by Vreasy will have a value of 1) that triggered the event
pm_user_id The user_id of the pm that owns the resource
acting_api The id of the api-key used to trigger the event (optional: available only if produced by an actor working with an api-key).
acting_agent An identifier for the agent that acted on behalf of the user to trigger the event. Could be one of: user, api, vreasy, vrsync, vrparse, operator, admin, vrhaxml.
resource_id The id of the resource where the event happened.
resource_type An identifier for the type of the resource where the event happened. Could be one of: listing or user.
*****_at The date and time of when the event was recorded in Vreasy. Create events send created_at, update events send updated_at and destroy events send deleted_at. Uses standard W3C/ISO 8601 date format.
changeset A list of the resource's properties that were updated (optional: for resource-update type of events only).
update_url The url to be used to retrieve the data that follows the event (optional: not available for resource-destroy type of events)

Subscribing and unsubscribing to event notifications

To subscribe to an event notification just post a JSON object, to one of the subscription endpoints, following the Subscription schema. For example to subscribe to all your listings' updates, POST to /api/listings/subscriptions the following JSON:

{
    "event": "listing_update",
    "protocol": "https",
    "endpoint": "https://www.example.com/my-api/notify"
}

The API will respond with a subscription object. You should save the subscription id somewhere to be able to unsubscribe from the event notifications. To unsubscribe send a DELETE request to the subscriptions endpoint at /api/subscriptions/:subscription_id using the subscription id.

Webhook acknowledgement and automatic retries

To acknowledge the webhook that you got the notification, you should accept it by returning a successful HTTP status code such as “200 OK” as quickly as possible (any 2xx will do the trick). Sending any other type of response (i.e. “500 Internal Server Error”, “404 Not Found”, etc.) or failing to return a response within 10 seconds will result in automatic retries of the webhooks.

Vreasy will attempt to send each webhook at most 10 times and it will do so by waiting 20 seconds for the first retry and using an exponential backoff strategy from then on.


Updating API keys

IMPORTANT: Whenever a partner uses the API key(s) of a customer, they MUST subscribe to the updates of these key(s) in order to be notified when a partner key is reissued. As a partner, if you are subscribed, you will receive a notification that allows you to update your key. EXAMPLE: A customer updates their security settings and a new set of keys are reissued.

Below is a JSON example of what the partner would receive:

{
   "event":{
      "event": "api_key_update",
      "updated_at": "2015-07-29T10:30:29+00:00",
      "acting_user": 12345,
      "pm_user_id": 1234,
      "acting_api": 12,
      "acting_agent": "user",
      "resource_id": 4567,
      "resource_type": "user",
      "update_url": "https://www.vreasy.com/api/keys?user_id=4567&updated_at=>2015-07-29T10:30:29+00:00"
   },
   "api_key": "xa8e1efcz1s7kldwy341k09dkt35tr04sh6gc"
}

Subscribing and unsubscribing to event notifications

POST using your partner API key, to the endpoint /api/users/:user_id/subscriptions, the following JSON object:

{
    "event": "api_key_update",
    "protocol": "https",
    "endpoint": "https://www.example.com/my-api/notify"
}

The API will respond with a subscription object. You should save the subscription id somewhere to be able to unsubscribe from the event notifications. To unsubscribe send a DELETE request to the subscriptions endpoint at /api/subscriptions/:subscription_id using the subscription id.

See Webhook Subscription section for more information about the event fields and how to acknowledge the webhook.


Errors

Vreasy uses conventional HTTP response codes to indicate success or failure of an API request.

In general, codes in the 2xx range indicate successful requests, codes in the 4xx range indicate an error within your request (e.g. a required parameter was missing, an external service call failed, etc.), and codes in the 5xx range indicate a failure of the Vreasy service (please contact us if you see these).

Standard HTTP Codes Usage

  • 201 Created: whatever you did, you have created a new resource successfully. The brand new resource should be in your response.
  • 200 Ok: Vreasy got your request, all was successfully processed. Checkout your response.
  • 400 Bad request: Vreasy could not understand your request. Check that you are sending a valid json or that your HTTP method is correct for the action you are trying to do.
  • 401 Unauthorized: Vreasy does not know who you are. You need to authenticate yourself before sending this request.
  • 403 Forbidden: Vreasy knows who you are, but you are trying to do something or getting access to a resource that you are not authorized to.
  • 404 Not Found: The resource or action does not exist. Check your URL.
  • 422 Unprocessable Entity: The request you are sending doesn't have all the required info, or some of it is not valid. Checkout the response for the causes of this error.

Error Response Schema

Vreasy always returns json in the response and we have 2 error schemas for that:

  • 422: validation errors return a json object with the invalid field name and a message for that field explaining why it didn't passed our validation requirements. Example:
{
  "title": [
    "Title is required"
  ]
}
  • For the other error codes, the API returns a json object with a message field and a code field (which is the same as the http status code). Also many times there is a request_params field that the "client" could use to see if Vreasy understood the request, since it has what Vreasy read from the request sent.
{
  "message": "Unauthorized: resource not available for the credentials provided",
  "request_params": {
    "module": "api",
    "controller": "properties",
    "action": "post",
    "body": {
      "host_id": 1,
      "cleaning_time": 4,
      "cleaning_fee": false,
      "size": 0,
      "checkin": "15:00",
      "checkout": "11:00",
      "created_at": "2015-08-17 15:53:33",
      "updated_at": "2015-08-17 15:53:33",
      "deleted_at": "",
      "availability_updated_at": "",
      "rate": 1
    },
    "request-id": "VnqVC38AAAEAAAk0S9oAAABP",
    "user_id": 1,
    "agent": "user"
  },
  "code": 403
}

Disclaimer

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Methods