External API

The data available on the External API is organized into different endpoints, and the API Partner must make a request to the proper endpoint in order to find the information they are looking for. Endpoints are like folders, and by housing the data in these folders we make it easier for partners to navigate our system. Endpoints are differentiated by the type of information included (ex. items and availabilities) as well as the type of action that can be taken, like creating, rebooking or cancelling a booking.

Find the details of each endpoint here.

Endpoints show the various fields and values that exist within a charter’s FareHarbor dashboard. These pieces are labeled with PKs (primary keys – numerical IDs) which partners use throughout their API interaction to identify the items, availabilities and customer types and custom fields they want to use. PKs allow partners to interact with the data in a more standardized, programmatic manner.

To perform any action through our API, partners must make requests in the form of URLs to contact our server. These URLs have a specified type, which defines the kind of action that should be triggered by the request. The four main types of request are:

• GET – Retrieves data from a server (ex. Companies, Items, Availabilities.)
• POST – Adds data to an existing file or resource in a server (ex. Creates a new booking.)
• PUT – Replaces an existing file or resource in a server.
• DELETE – Deletes data from a server.

All External API requests to the FareHarbor server have the same “root”, meaning they start the same way, every time: https://help.fareharbor.com/api/external/v1/ (or https://demo.fareharbor.com/api/external/v1/ if using the demo environment). The partner will add more parameters to this URL to indicate which endpoint they are requesting from, each time adding another layer of specificity to the request. Examples of request URLs for each endpoint are shown in the sections below.

A rate limit restricts the number of API calls/requests that a partner can make to FareHarbor in a specified time period.

• What is the rate limit? An External API partner can now only make at most 600 requests per minute per IP address. This could be any type of request to the External API. This is evaluated over a 5-minute period, so going over this limit will result in a 403 response for the following 5-minute window.
• Starting April 19, 2021, we’re imposing a new rate limit with External API Partners. The new limit will be 30 requests per second. This could be any type of request to the External API. If the limit is reached we will respond with a 429 response with the message of “too many requests.”
• Why do we impose a rate limit? Rate limiting is a common technique used to lessen the strain of API calls on our system. We rate limit as a security precaution, as too many API calls can negatively impact FareHarbor’s infrastructure and potentially cause performance issues across the platform.
• What do we recommend to API Partners? An External API partner who is hitting this limit must redistribute the calls within their system. For example, an API partner could previously pull availability for all connected companies at once, but now they will have to spread those availability requests out over the course of the day.

Technical Documentation here

All requests must be authenticated in order to successfully ping the FareHarbor server. To authenticate their requests, API Partners are given API keys by FareHarbor, which they must include in the headers for each request that they make. API keys are a partner’s credentials, necessary to access information on the API. Two separate keys are needed in order to make a request:

• An App Key: This is used to identify the API Partner’s application at the broadest, organizational level. A single app key is given per API Partner, and it is used to authenticate all the requests the partner makes, regardless of the specific affiliate dashboard that they are using to book with on FareHarbor.
• A User Key: This identifies the specific “API” user on a specific affiliate dashboard. Affiliate dashboards for API Partners must be separated by currency so that we can match charter and affiliate currency within FareHarbor. This means that the same API Partner can have multiple user keys, one for each different affiliate dashboard that we create for them. Or, if there is an OTA with multiple platforms and they want to tag each booking with the exact platform it originated from, they could use multiple User Keys under one App Key.
• Headers: Headers are additional information that can be sent with each request.

The keys should be included as headers on each request. We use the following format:

X-FareHarbor-API-App:  APP-KEY
X-FareHarbor-API-User:  USER-KEY

An example request might look like so when run from the command line: $ curl -H "X-FareHarbor-API-App: APP-KEY" -H "X-FareHarbor-API-User: USER-KEY" https://help.fareharbor.com/api/external/v1/companies/

The -H portion of that command signifies that what follows is a header to be attached to the request. Additional information and a more in-depth look at how this works can be found in our Technical Documentation.

The /companies endpoint lists every FareHarbor charter company that the API Partner can access through the API. The charter companies on this list are determined by which charters have that affiliate added on their dashboard and have given them an API Permission Group. The list also mirrors the one that you can find in the “Partners” tab on the affiliate’s dashboard. API Partners use this endpoint to see a list of all of the companies that they can connect to and book.

Example Request URL: https://demo.fareharbor.com/api/external/v1/companies/

When this request is successful, the partner will receive a response from our system showing all the accessible charters, with company name, shortname and currency:

Things to note:

• The /companies endpoint has been programmed so that offboarded dashboards with a “-closed” tag in the shortname do not show up in the response our system provides.
• If an API Partner does not have a permission group added for them on a charter dashboard, that charter shortname will not show up in the response our system provides.

Technical Documentation here

The /company endpoint allows the partner to specify one charter company from the list in the /companies endpoint and then view company-level information taken from the charter’s “Settings” pages, such as booking notes, company location, website URL, etc. API Partners use this endpoint to import basic company details during the initial onboarding and to make sure that the company details on their side are accurate.

Example Request URL: https://demo.fareharbor.com/api/external/v1/companies/shortname/

When this request is successful, the API Partner will receive a response from our system showing the following company details:

Things to note:

• There are two fields where company location can be noted: the “address” field and the “location” field. The “address” field represents an old FareHarbor setting that has been replaced by the Locations feature, which means this field is blank on most dashboards.

Technical Documentation here

The /items endpoint shows every bookable item on a specified charter dashboard along with a summary of fields from within each item’s settings. This endpoint pulls fields from the “Item: Info & Policies” and “Item: Options & Prices” pages of a charter dashboard, including item photos, locations, booking notes, and customer types. Only those items and customer types that are visible on the total price sheet in the Affiliate settings will be visible and bookable. API Partners use this endpoint to import item details and content so that they can build that item as a product on their end.

Example request URL: https://demo.fareharbor.com/api/external/v1/companies/shortname/items/

When this request is successful, the partner will receive a response detailing each item in the following manner:

Things to note:

• This endpoint is sometimes referred to as the “Content API,” since it allows a partner to pull an item’s photos and descriptions.
• Unlisted and Private items are not displayed through this endpoint and are not bookable through the External API.
• Public Items can be made unbookable through the API, but they cannot be fully hidden from partners through the API. If the item is hidden on the affiliate total price sheet, the customer types disappear (making the items unbookable) but the item name remains visible.
• The cancellation policies described here pull from the written “Item cancellation notes” on the “Info & Policies” section in the dashboard, which is separate from the cancellation policy that can be assigned to the API Partner in their affiliate settings.

Technical Documentation here

The /availabilities endpoint is used to fetch all bookable availabilities for a single item within a specified date or date range. It allows the API Partner to pull availability data from the Item Calendar of the dashboard. Each individual availability shows a unique PK (which is how the API Partner indicates which exact availability they want to book,) and a summary of its settings, including start/end times, capacity, valid customer types (with PKs) and their prices, custom fields (with PKs,) party size restrictions, etc. Here the API Partner can gather the relevant PKs that they need to create the booking, and they can use the data to connect and display the bookable dates and times on the product calendars on their end. The more they refresh this request, the more accurate their calendars will be.

Availability can be pulled for a single date, in which case a request URL would look like this: https://demo.fareharbor.com/api/external/v1/companies/shortname/items/20767/availabilities/date/2019-11-10/

Availability can be pulled for a date range, in which case a request URL would look like this: https://demo.fareharbor.com/api/external/v1/companies/shortname/items/20767/availabilities/date-range/2019-11-10/2019-12-10/

Things to note:

• Unlisted availabilities on a public item are visible and bookable through the API.
• If an API Partner does not want to pull custom field information when performing an availability request they may opt to use a “minimal” availability request, which excludes all custom field information from the response our system provides. This can make their request perform faster. To perform a minimal availability request, the partner must edit their request URL to include the “minimal” tag, in the following manner: https://demo.fareharbor.com/api/external/v1/companies/shortname/items/20767/minimal/availabilities/date/2019-11-10/
• API Partners may pull availability from FareHarbor at whatever intervals they want, but we recommend that at a minimum they pull availability for the next 90 days once a week, for the next 30 days once a day, and for the current day every couple of hours.
• The largest date range that can be pulled in one single request is 100 days.
• The “customer_type_rate” section details each customer type as it is applied to the availability and within it we can find the “customer_prototype” section, which details the customer type as it is configured on the “Options & Prices” settings on the dashboard, and the “customer_type”, which details the customer type as configured on the dashboard level. Each of these has its own PK number to identify them.
  • The prices for the “customer_type_rate” and the “customer_prototype” should always match. If they don’t, it means that the customer types have been repriced on the availability level in FareHarbor, an inadvisable practice.
• Public headlines are displayed for each availability on the External API through the headline field, meaning that API Partners are able to make use of this field to differentiate between availabilities, especially in the case of items that have multiple availabilities starting at the same time (like with some tours offered in multiple languages).
• The capacity noted at the end of each availability is the sum of the available seats for all bookable customer types on that availability, but this number might not be evenly split across the different customer types. There is a capacity noted for each bookable customer type as well, which is affected by the resources (not displayed through the API) and maximum party size restrictions set in FareHarbor.
• A request can also be done to pull information for a single availability within FareHarbor. To do this, a partner must note that availability’s individual PK number in the request URL, in the following manner: https://demo.fareharbor.com/api/external/v1/companies/shortname/availabilities/12837654/

Technical Documentation here

The FareHarbor Transportation module is supported through the External API, meaning that API Partners are able to retrieve our charters’ lodging options, both on a dashboard level as well as on the availability level, and offer these for customers to choose from when creating a booking. After a booking is created on an item with transportation enabled, our system provides the API Partner with booking information that includes pickup information (in the form of a pickup point and pickup time) when a lodging with available transportation was specified, or arrival information, when no lodging was specified or transportation is not available for the specified lodging (or any lodging).

API Partners are able to check all of the lodging options available on a dashboard by using the following endpoint:

https://demo.fareharbor.com/api/external/v1/companies/shortname/lodgings/

They are also able to check lodging options on a specific availability, which provides them with extra information, as this response includes whether pick-up is available for each lodging option. The request URL would look like the following:

https://demo.fareharbor.com/api/external/v1/companies/shortname/availabilities/12835706/lodgings/

Technical Documentation here

Our API currently supports 5 different types of FareHarbor custom fields:

• Single line text input (type: “short”)
• Multiple line text input (type: “long”)
• Dropdown (type: “extended-option”)
• Checkbox (type: “yes-no”)
• Quantity (type: “count”)

These custom fields show in our system’s response to an /availabilities request, as long as they are visible on the total price sheet assigned to the API Partner. The details shown for custom fields on the /availabilities endpoint pull from “Options & Prices” at the item level. The API Partner will be able to include a custom field in a booking by noting the PK our system shows for the field, and they’ll be able to answer the field using the valid value format that applies to each type of custom field.

Single and Multiple line text input (type: “short” and “long”)

Both types of text input fields can be answered with any string of characters that is fewer than 2048 characters long.

Dropdown (type: “extended-option”)

The dropdown custom field is shown with all of the possible response options. Each option has its own PK number so that API Partners can easily note in a standardized manner which answer the customer has chosen when creating a booking.

Checkbox (type: “yes-no”)

The checkbox custom field accepts boolean data types, which is to say that there are only two possible ways to answer it. In our case, the API Partners will have to answer with either “true” (when the box is checked) or “false” (unchecked).

Quantity (type: “count”)

The quantity custom field accepts any whole number that falls between the ranges noted in the FareHarbor settings. However, this range restriction is not currently being exposed through the API, which can cause booking errors for API Partners trying to book using this custom field since they cannot show the minimum and maximum values to their customers.

Things to note:

• The PK that is used to note a custom field matches the number found in the URL of that custom field’s settings in FareHarbor (example: https://demo.fareharbor.com/gstadiumtours/dashboard/settings/custom-fields/65752/).
• The conditional custom field feature is not supported. A field restricted by this feature will be shown without any reference to the condition settings and will be bookable without having to abide by the logic set up in FareHarbor.
• Private custom fields are not shown.
• Custom fields that are set to be “required” do not actually prevent a booking from being made through the API when they are left unanswered.
• The Code, Label, Waiver and Gift card custom fields are not currently supported through the API.
  • Although it is not shown on the /availabilities endpoint and it is not bookable through the API, the Code custom field is shown when retrieving information for a booking where it has been used. This booking would have to be made outside of the API to be able to use the custom field, and have an API Partner tagged as the affiliate in order to be retrieved.
• Transportation is supported through the API, the functionality is explained in the section below.

Technical Documentation here

To create a booking, the API Partner must assemble 1) the request URL for the availability being booked, and 2) the booking body template, with all the details of the booking they want to create.

The request URL must include the PK for the specific availability that they wish to book. This PK can be found in the /availabilities endpoint. Creating a booking must be performed as a “POST” request, because new information (a booking) is being “posted” to FareHarbor.

https://demo.fareharbor.com/api/external/v1/companies/shortname/availabilities/12835706/bookings/

The booking body template is where the API Partner assembles the various details and PKs that make up the actual booking. This includes standardized fields such as customer name, phone, email, booking note and voucher number. The voucher number is where API Partners put the booking reference number from their own system. The API Partner includes the customer_type_rate PKs (from the /availabilities endpoint) to indicate how many and which customer types are on the booking, and any other custom field PKs and their values.

Here is an example of what a booking request for one customer looks like.

If the request is valid (i.e. if the PKs and values are valid according to the availability and its settings) then our system will synthesize them into a booking in the FareHarbor dashboard. The booking will indicate that it was created by the API Partner via API in the booking history. If the data is not valid, then our system will provide an error response noting the reason why the booking is not able to be made.

Upon creation, FareHarbor will return a full representation of that booking, including the customer types booked, custom fields, customer contact information, a price breakdown, an invoicing breakdown, and the cancellation policy attached to the booking. A couple of new fields are automatically generated and shown, like the Confirmation URL which leads to the booking on the FareHarbor dashboard, and the UUID (Universally Unique IDentifier), which is the code used when referring to that specific booking through the API.

Technical Documentation here

Validation is a step that can be taken right before a booking is created, to 1) confirm that the requested booking is valid and still available, and 2) calculate the total price and tax of that requested booking. This serves as a final check and can help the API Partner identify any potential errors before they confirm the booking to the customer and take payment. If the request is bookable, our system’s response will show a price breakdown including subtotal and tax amounts and “is_bookable: true.” If it is not bookable, then our system will show “is_bookable: false,” and an error explaining why the request is not bookable.

This endpoint is especially useful to API Partners who pull pricing from FareHarbor. They can use the validation endpoint to calculate the total price of a booking so that they may show the price to the online customer before the customer completes the booking.

The request URL used to validate a booking request is very similar to the one used when trying to create the reservation:

https://demo.fareharbor.com/api/external/v1/companies/shortname/availabilities/12835706/bookings/validate/

Technical Documentation here

Retrieving a booking allows an API Partner (or the Connectivity Team) to view the exact fields and PKs that make up an existing booking. To retrieve a booking from our system, the API Partner must have that booking’s UUID, which they will place into a request URL that will look like the following:

https://demo.fareharbor.com/api/external/v1/companies/shortname/bookings/0f926e45-2e79-43a1-8349-fc6d33193f95/

The response from our system will show the same type of overview information as that which was shown when the booking was initially created, with a list of details concerning the booking.

Technical Documentation here

If an API Partner needs to change the time, date or details of an existing booking, they may do so by rebooking. This process will replace the original booking with a newly created booking, but keep the two bookings tied together in the FareHarbor booking history. This process allows the API Partner to recycle the body from their original booking request, and only replace the details that need to be changed – instead of creating the whole new booking request body again. The request URL follows the same pattern as to when originally creating a booking.

https://demo.fareharbor.com/api/external/v1/companies/shortname/availabilities/12835706/bookings/

To note that it is a rebooking and not a new booking, the API Partner must include the “rebooking” field in the body of their new request, and populate it with the UUID of the booking that they wish to rebook.

  "rebooking": "d75102be-9732-4523-90a8-c698eff2b983",
   "contact": {
     "name": "John Doe",
     "phone": "415-789-4563",
     "email": "johndoe@example.com”

Technical Documentation here

To cancel a reservation, an API Partner uses the same request URL as when retrieving a reservation, using the booking’s UUID:

https://demo.fareharbor.com/api/external/v1/companies/shortname/bookings/0f926e45-2e79-43a1-8349-fc6d33193f95/

While the URL is the same, however, the request is sent as one of a different type, with the aim to “delete” data from our server, instead of retrieving (like when pulling availability) or adding data to it (such as when creating a booking).

Our system’s response to a successful cancellation request will show the same information as when retrieving a booking, noting a list of details concerning the reservation, with the one change being the booking “status’’, which will now show a “cancelled” value.

• All API Partners (including Channel APIs) are set up in FareHarbor with a default cancellation policy that allows them to cancel a booking up until availability start time, with refunds being shown if the cancellation comes in at least 48 hours prior to the availability start time.
• Payment funds for External API bookings never enter FareHarbor’s system, which means that if a booking is “cancelled and refunded” in FareHarbor, no refund is actually issued to any party.
• Refunds must be discussed with and issued by the External API Partner, as they are the party who collected the funds from the customer.
• API Partners are not restricted to the Cancellation Notes described in the “Info and Policies” section of the company’s dashboard. They have their own cancellation policies, which are set in concert with the client.
• The cancellation policy set at the affiliate level in FareHarbor overrides any item-level cancellation policies.

Technical Documentation here

The main tasks for the Connectivity Team concerning External API integrations are to provide technical support between our clients and these live partners, guide our live partners as to how best to integrate the data we provide, troubleshoot any errors they might experience with the integration, and find ways to improve our External API connectivity platform, processes and communication.

Connectivity Specialists work on External API tickets in Zendesk, and the tickets may originate from clients, External API Partners, or internal teams. Internal teams may direct questions about live External API integrations to @connectivity_team in the #connectivity room in Slack. External API Partners correspond directly with the Connectivity Specialists via the api-support@fareharbor.com alias in Zendesk.

To gain practical knowledge of how the External API works, troubleshoot connections and test for errors, Connectivity Specialists uses Postman, an API workflow tool. Postman allows us to see in a clear and organized manner how the data in FareHarbor is being communicated to partners in JSON format and how different requests and interactions take place.

Here’s a short tutorial on Postman.

• API Partner Glossary
• Technical Documentation of the External API
• Partnership Team Process for becoming an API Partner
• Difference between External API & Channel API
• External API Partner Feature Airtable