In order to access the venuedirectory.com API you will be assigned a unique API key. The key must be provided with each request made to the API and is used to determine whether or not you have access to a particular service and which subset of venuedirectory.com data fields you have permission to retrieve.
Calls to the API must provide the API key as a part of a header with the header name TVD-ApiKey, e.g.
If the API key is not provided or if an invalid key is provided then the API will return an error response.
The API will limit the number of requests that can be made by a client in calendar 24 hour period. Once the request limit is reached the API will return 429 – Too Many Requests HTTP response until the request limit is reset at midnight. The limit is typically set to 1000 request per day. The limit can be adjusted on a per client basis as required.
The API uses a dynamic throttle which ensures everyone can enjoy the service and no one takes over by making many requests which will slow down responses to other users. If the API calls quota exceeds the API returns 429 – Too Many Requests HTTP response.
For security purposes for each client the API has a defined list of IP Addresses that have the right to access the API functionality. The list of eligible IP Addresses can be extended per client request.
API clients have different levels of API functionality visibility. The list of permitted methods is being configured for each client. An attempt to access the method that is not included in the list of client methods will result in 429 – Too Many Requests HTTP error.
This sections walks you through the subset of Venuedirectory API methods that allow to communicate with the Venuedirectory reservation system: search available meeting rooms and submit instant bookings.
To begin with please review the 'Submit Instant Booking' flow diagram below.
Venuedirectory Availability API is an aggregator that exposes multiple availability data sources, including third parties. We keep extending the list of availability sources to supply our clients with the best rates
Venue search is used to find a list of relevant venues that can be presented to a user. In the meantime the rate search endpoint can be called.
To initiate the create reservation action you need to pass in the SearchID and ID that have been received as part of availability search. In response the API will return a TemporaryReservation object. In average the API allows 20 minutes to complete the reservation (duration may vary depending on the Provider). Within these 20 minutes the rate you are trying to book will be unavailable for anyone else except you current user. As part of the temporary reservation object the API will return you the list of layout, catering and equipment options as well as available payment options.
Saves selected by user layout and delegates as well as selected catering options and equipment
Saves user contact details
Applies the promocode and brings down the total cost of a booking
This step is applicable if:
| Parameter | Description |
|---|---|
| CallbackFunction | Required. The URL of the page on your website that will capture the payment result |
| Styles | Optional. CSS styles, applicable to Regus Provider only |
| LogoUrl | Optional. Company Logo URL to be displayed on a payment page. *Applicable to card payments where PaymentProvider is set to Stripe |
| Name | Optional. Venue/Company Name. *Applicable to card payments where PaymentProvider is set to Stripe |
In response the API returns the URL of the hosted card capture page that needs to be presented to a user.
Once the user filled in card details and pressed 'Pay' button the API attempts to collect the payment and returns the status (as part of the query string) to a callback function provided. Your callback function should expect:
Confirm reservation method: requires PaymentType parameter that indicates what type of payment option is required to complete the reservation.
Allows to extend the reservation booking time slot. Can be applied to a reservation only once.
Cancels the reservation and releases the availability rate.
Returns PDF file with terms & conditions for a reservation.
Returns the list of duration slots. Please use TimeOfTheDay field for availability search
For an integration stage you'll be given test credentials and endpoints.
Submitting test card payments:
The API will return the following standard HTTP errors in the event of a problem.
| Http Status Code | API Error Code | Exception Reason Phrase | Exception Description |
|---|---|---|---|
| 401 Unauthorized | 1001 | Invalid key provided | The Api Key provided either was not found or does not match ########-####-####-####-############ format. |
| 401 Unauthorized | 1002 | Unknown key provided | The Api Key provided has no associated client profile. |
| 403 Forbidden | 2001 | Invalid client configuration | The client profile has configuration issues. |
| 403 Forbidden | 2002 | Invalid IP Address | The request IP address is not in the list of allowed IP addresses. |
| 403 Forbidden | 2003 | Access Restriction | The client is not authorised to access the method. |
| 403 Forbidden | 2004 | Access Restriction | The source IP address has exceeded the daily allowance threshold (1000 hits by default). |
| 400 BadRequest | 3001 | Validation Issues | The data passed by client has some invalid parameters. |
| 400 BadRequest | 3002 | Dynamic Filtering Exception | OData Exception may occure only for methods that have dynamic model filtering using $select and $expand filters. |
| 502 BadGateway | 4001 | General | Something unexpected has happened when processing the request. Occurrences should be rare. |
| 400 BadRequest | 4004 | NotFound | Resource not found. |
| 500 InternalServerError | 5000 | Internal Server Error | Internal Server Error |
| 504 GatewayTimeout | 5004 | Gateway Time Out | Something unexpected has happened when processing the request. Occurrences should be rare. |
Each response includes a ResponseStatus section. This will provide a standard HTTP Response Codes from the list defined above or will be set to 200 - OK for successful requests. Besides standard HTTP errors each error response will contain a JSON object with Venuedirectory API specific error message and error code fields:
The API search methods return the limited number of records per request. The response content contains also information about the total number of records found per request, current page and total number of pages. At the moment the maximum number of records per page is limited to 20. In order to obtain the next page the optional paramater 'pageno' has to be supplied with the request:
The API search methods support sorting by a set of predefined fields. In order to specify the sorting field and the sorting order the 'orderbyfield' and 'orderby' parameters has to be supplied.
Methods that support pagination and sorting are marked with icon.
Some of the API methods support OData filtering, in particular: $select and $expand. These filters are designed to select a subset of data. For example, if you are planning to search recently updated venues and you are interested only in Venue ID, Venue Name and Venue Postcode then you can supply OData filters with your search request and the response will contain the list of objects with these 3 fields only instead of returning you a full object.
$Select filter is being used to specify what fields have to be included in response. Consider the following example:
The $expand filter is getting handy when the object that is being returned has some nested properties that we want to read as a part of our generic select. Look at the next example
Methods that support OData filtering are marked with icon.
All successful API responses are of a standard HTTP Response type (200 Success) with a JSON data as a part of a response content. A failed API request will prompt a standard HTTP Response error type. Please view 'Exception Types' section for more information about API error types.
We use server side image resizer to serve images, which means you could append parameters to the image URLs returned by the API to resize the images on the fly. For example:
Once the image was accessed it is being cached on a server side. To access uncached image you need to append any unique parameter to an image URL, e.g. ?v=12345