Introduction to the API
The Pitchup REST API allows access to bookings, availability and pricing from an external system.
A booking system can integrate with the API to provide access to bookings taken through the Pitchup system along with direct bookings to a site owner / operator. It can be used to automatically update pricing in line with a campsite's own pricing. It may also be used to adjust the amount of inventory allocated to Pitchup from the site's total inventory.
Rest API fundamentals
The recommended way of interacting with our API is through JSON requests. JSON is a simple, human readable, text based data interchange format. While JSON is quite simple there are a few rules which must be followed to ensure that the data is formatted correctly. Most programming environments will have a set of libraries for converting between its own standard data-types and JSON strings which will ensure the formatting is maintained correctly.
When manually formatting JSON care should be taken to ensure all of the properties are fully quoted strictly using double quotes and that those quotes have not been transformed into the unicode left and right double quotation marks.
There are a number of JSON format validators which can be used if an error is suspected, such as http://jsonlint.com/.
A RESTful API consists of a number of HTTP end points which represent the resources in a system. Some of the end points in the system will produce a list of resources, for example
/rest/api/campsite/my-campsite/booking/ will list all of the bookings for "my-campsite". Others will detail a particular resource, for example
The HTTP verbs GET / POST / PATCH / PUT are used in conjunction with these end points to view and manipulate the resources.
Used to retrieve resources from the API. For example
Used to create new resources within the API.
Used to modify a whole resource.
Used to update only selected fields on a resource.
Links to other resources
Some resources will link to other resources. The campsite resource at
/rest/api/campsite/my-campsite/ will contain links to the various pitchtype resources belonging to that campsite like
It should be noted that the API implementation should follow these links whenever possible (caching where necessary) rather than permanently hard-coding them, or worse attempting to generate them through string concatenation. Doing so makes the implementation dependent on the structure of the API and should be avoided.
Care should be taken to pay attention to the pagination of resources. It is easy to miss the fact that all resources can be paginated, especially as this may only come up with production volumes.
Pagination is indicated by the presence of the previous and next links on a list resource. As with resource links, these links should be followed rather than being manually generated.
Some end points support filtering as detailed below. The filters are simply added as a get request to the list end-point. For example
https://www.pitchup.com/rest/api/campsite/my-campsite/booking/?after=2016-01-01&before=2016-02-01. If manually generating the get parameters by string operations care should be taken to make sure the question mark and ampersands are correctly placed.
A webhook can be setup which will post the details of any new bookings in JSON format to a URL endpoint provided. The format is the same as the Booking resource below. There are some manual steps which are required to setup and test the webhook. Please contact your account manager if you require one to be setup.
Finding authentication details
Authentication is acheived using an authentication token. This token can be found in the 'My details' section of the Pitchup manager portal.
Only 'API key (other booking systems)' can be used in conjunction with this API.
Using authentication details
This is passed to the API as an Authorization header. With curl this looks like the below:
curl -H 'Authorization: Token 7c33fec676104967958ab8ece0a1b76c' https://www.pitchup.com/rest/api/
Alternative authentication methods
As well as the token based authentication method it is possible to browse the API using the users logged in account. This is convenient during development where the credentials are available.
A authenticated user will be able to see any of the campsites and linked resources which belong to that user account. They will not be able to see any resources relating to any other campsites or be able to assign them as linked resources.
When logged in as a campsite owner the user may browse the API. This is useful to quickly get an idea of how the API is structured. This is accessed simply by logging in at https://www.pitchup.com and then navigating to the page https://www.pitchup.com/rest/api/.
Pitchup.com provides a sandbox which can be used for testing purposes. This is accessible from https://www.sandbox.pitchup.com
Accounts and test campsites can be setup using the normal signup form at http://www.sandbox.pitchup.com/supplier2/signup
Bookings can be created in the sandbox for testing by using the card details from https://stripe.com/docs/testing and any other test data.
ExtraPrice end-points support adding multiple resources in the same request.
"price": "17.51 GBP",
"price_adult": "17.41 GBP",
"price_child": "13.07 GBP",
"price_infant": "09.05 GBP"
"price": "19.51 GBP",
"price_adult": "17.41 GBP",
"price_child": "13.07 GBP",
"price_infant": "09.05 GBP"
ExtraPrice end-points also support an "upsert" type operation. Attempting to create one of these resources using the POST method will override the existing data (matching on the unique fields). This means there is no need to look up the detail view and PATCH each one individually.
In order to start exploring the API it is useful to setup a test campsite in the sandbox environment. Starting at https://www.sandbox.pitchup.com/supplier2/signup/ the process is quite self explainitory. Alternatively, when developing an integration for an existing Pitchup.com client, it might be helpful to request their API key which can again be used directly in the sandbox. This has the advantage of having their site already setup with the correct pitchtypes.
Curl can be used to make requests to the API as follows.
> curl -H "Content-Type: application/json" -H "Authorization: Token <TOKEN>" "https://www.sandbox.pitchup.com/rest/api/"
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 559 100 559 0 0 15568 0 --:--:-- --:--:-- --:--:-- 15971
"campsite" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/",
"arrival_days" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/arrival/",
"extra_prices" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/extraprice/",
"extras" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/extra/",
"bookings" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/booking/",
"allocation" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/allocation/"
Note that the format of the two headers passed in are important and can lead to surprising errors if they are not used correctly.
If starting with a new test campsite it will be necessary to create at least one PitchType resource (which will atomatically create a matching default chargetype). This can be done by going to https://www.sandbox.pitchup.com/supplier2/ and selecting the "Pitch types and extras" tab. The "Add pitch pitch type" button on the right hand side will start the process.
Having created a PitchType and ChargeType using this form the browsable API will show the details at the relevant end points. Start at https://www.sandbox.pitchup.com/rest/api/campsite/ and note that you can now see the PitchType and ChargeType created using the supplier portal.
You can now begin adding allocation and rates for this PitchType - ChargeType combination. An easy way of getting started is to open the test campsite in the portal and use the
Rates > Rates batch update form to create an Arrival Day. And the
Allocation tab to add allocation to that date. You can then browse to the relevant sections in the API to use these elements as a template.
Taking one of the Arrival Days from the results section and adding it to a file called
arrival_day.json. We can make a few modifications and use it to change the price for this day.
$ cat arrival_day.json
"price": "12.00 GBP",
"price_adult": "6.00 GBP",
"price_child": "5.00 GBP",
"price_infant": "2.00 GBP",
$ curl -H "Content-Type: application/json" -H "Authorization: Token <Token>" -d @arrival_day.json "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/arrival/"
A similar process can be followed to modify the allocation for one of the dates already setup, or indeed for any other date.