Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
x-stoplight:
id: obltqlvi1ac1n
info:
title: FareHarbor Integration Center
version: '1.0'
contact:
email: support@fareharbor.com
name: FareHarbor
url: 'https://help.fareharbor.com/hc/'
servers:
- url: 'https://fareharbor.com/api/external/v1'
description: production
- url: 'https://demo.fareharbor.com/api/external/v1'
description: demo
tags:
- name: Getting Started
description: |
FareHarbor offers powerful APIs and webhooks designed to streamline integrations, increase automation, and scale your business--whether you're an affiliate aiming to integrate live booking capabilities, or a software partner enhancing backend operations.
### Who Can Access the API?
FareHarbor offers API access to:
- **Affiliates** looking to sell FareHarbor client inventory directly within their own platforms
- **Software Partners** integrating FareHarbor into systems like CRMs, POS, accounting tools, or waiver and photo platforms
All requests are reviewed for eligibility. To begin, email [support@fareharbor.com](mailto:support@fareharbor.com) with a brief summary of your use case. If you are a distribution affiliate, please fill out our application for API [here](https://airtable.com/appn3FgNIepgAu6GD/shra6tuh90diXXOFr).
### For Affiliates
Affiliates can use our External API to access and book inventory in real time. This enables platforms like OTAs, concierges, and marketplaces to create seamless booking experiences.
#### Key Capabilities:
- **API Access:** Available to qualified Affiliates for distribution purposes
- **Query Inventory:** Retrieve real-time availability, pricing, and item metadata ("items") for operators in your partner network or through the FareHarbor Distribution Network (FHDN)
- **Create and Manage Bookings:** Use the Bookings endpoints to create and manage bookings and manage customer data
- **Testing Environment:** Safely test your implementation in our demo environment
### For Software Partners
Software and integration partners can connect with FareHarbor to automate workflows and synchronize client data.
#### Typical Use Cases:
- CRMs, POS systems, accounting tools
- Waiver and photo capture platforms
- Support and marketing automation tools
#### Integration Capabilities:
- **Webhook Access:** Built for Software Partners to support non-distribution use cases
- **Real-Time Sync:** Configure webhooks so that you receive automatic updates on bookings, customers, and payments
- **Data Management:** Use the External API to pull booking, availability, and customer records
- **Custom Integrations:** Build tailored workflows using booking-level data, custom fields, and waiver metadata
### Resources and Support
Both affiliates and software partners have access to the following tools and documentation to support their FareHarbor integrations:
- **Production API Documentation:** [https://developer.fareharbor.com/](https://developer.fareharbor.com/) — Contains all necessary technical details about endpoints, data formats, and sample code
- **Demo API Environment:** [https://demo.fareharbor.com/api/external/v1/](https://demo.fareharbor.com/api/external/v1/) — A testing platform where you can safely experiment with API calls without affecting live data
- **Help Center:** [https://fareharbor.com/help/](https://fareharbor.com/help/) — Guidance and support articles for technical and operational questions
- **Technical Support:** Our experienced support team is ready to assist you with any questions or challenges during your integration process
Get started today to enhance your platform's capabilities and provide a seamless experience to your users with FareHarbor's comprehensive integration solutions.
## API Certification
To receive your live API credentials you must first successfully complete API Certification. This process ensures your integration accurately supports core FareHarbor functionality for scalability with FareHarbor operators.
Once certification is complete, we will provide a short survey before issuing your production API credentials.
If you have any questions throughout development or certification, please contact your FareHarbor representative at [api-support@fareharbor.com](mailto:api-support@fareharbor.com).
### Required Integration Capabilities
Your integration must support the following FareHarbor functionality before certification can be completed.
- Must pull ticket pricing from FareHarbor (see [Availabilities endpoints](#tag/Availabilities-Endpoints)).
- Must support multiple [API User keys](#tag/Authentication) (issued per currency).
- Must support [Custom Fields](#tag/Custom-Fields) and applicable [Custom Field pricing](#tag/Custom-Fields/Priced-vs-unpriced-custom-fields).
- Must support Product Tour Options under a single ID (see [Items endpoints](#tag/Items-Endpoints)).
- Must correctly display availability level [Public Headlines](#tag/Data-Types/Schemas/Availability) (may require a demo/sample product for review).
- Must correctly translate General Admission or Opening Hours products with entry times (see [Availabilities endpoints](#tag/Availabilities-Endpoints)).
- Must support multiple FareHarbor [customer types](#tag/Data-Types/Schemas/Customer-Type) within a single ticket category, if set categories exist.
- Must utilize the [Validate Endpoint](#tag/Bookings-Endpoints/operation/post-validate) prior to instant confirmation.
- Utilize the [Bookings Webhook](#tag/Webhooks/Configuring-webhooks/Booking-notifications) to register booking updates (i.e. supplier initiated cancellations).
**NOTE:** It's not required, but highly recommended, to use the [Items Webhook](#tag/Webhooks/Configuring-webhooks/Item-notifications) to register content updates.
### Certification Testing
Create at least one booking for every product available in the assigned Dolphin Tours sandbox environment (see [POST bookings](#tag/Bookings-Endpoints/operation/post-bookings)).
- Each booking must include:
- Customer name
- Phone number
- Email address
- Submit at least one booking containing a [Booking Note](#tag/Bookings-Endpoints/operation/put-update-booking-note).
- Create bookings using at least two different [Customer Types](#tag/Data-Types/Schemas/Customer-Type), where applicable.
- Create a booking using all [custom fields](#tag/Custom-Fields) identified in the Dolphin Tour (custom field) item. Verify pricing at time of booking, where applicable.
- If applicable, submit bookings using at least two different [Transportation/Lodging](#tag/Lodging-Endpoints) selections.
- [Rebook](#tag/Rebooking) one existing booking.
- [Cancel](#tag/Bookings-Endpoints/operation/delete-booking) one existing booking.
### Certification Validation
As part of certification, FareHarbor will assess your integration using a variety of sample booking scenarios to confirm your integration correctly supports the required functionality across different operator configurations.
Validation may include a review of either a sample product or live demo of the expected booking process to ensure feature implementation.
## Rate Limits
We enforce two rate limits on requests to the FareHarbor External API. Both are applied per IP address, not per app key.
- At most 30 requests per second per IP.
- At most 3,000 requests per 5-minute period per IP.
If multiple app keys are being used from the same IP, their requests all count toward the same pool. Going over either limit will result in an HTTP 429 Too Many Requests or 403 Forbidden response until the time window resets.
To avoid hitting these thresholds, partners should spread requests evenly across time rather than sending large batches all at once.
## Timeouts
Certain requests to the FareHarbor External API are especially time-intensive, such as some of the [Availabilities endpoints](#tag/Availabilities-Endpoints).
Our infrastructure enforces an upper bound of 60 seconds on the duration of all requests to our endpoints. When a request exceeds this limit, it will be terminated with a `504 Gateway Timeout` HTTP status code.
If you experience a 504 timeout for an availability request (such as by date range), we recommend re-trying the request after shortening the requested date range.
## TLS Version
As of 2020-09-01 we require clients that connect to our API to make use of TLS1.2 in order to ensure a speedy and secure connection. You can test this by running a curl command against our API and if you see something like `SSL_ERROR_SYSCALL in connection to fareharbor.com:443` or `Unknown SSL protocol error in connection` you are trying to use a TLS version we do not support. If that is the case it is likely that you will need to upgrade your local openssl version, which is outside the scope of this document.
## Determining User Keys
FareHarbor will provide approved API partners with User Keys that can be used to make requests and create bookings for suppliers.
The supplier must confirm their approval of your API access before you are able to make bookings for them via API.
If you are using the FareHarbor API to book for suppliers across multiple countries/currencies, you may be provided with one User Key per currency.
You can find more information about the authentication process [here](#tag/Authentication). Alternatively, you may contact <support@fareharbor.com> for assistance with User Keys.
## Structuring Requests and Responses
All requests and responses are simple JSON objects; see [`Format`](#tag/Format).
## Interacting with the API
The FareHarbor API provides a powerful way to manage bookings, customers, and inventory programmatically. Here's a quick start guide to help you set up and begin integrating with the FareHarbor API.
### Step 1: Obtain API Credentials
Register for API Access: Contact FareHarbor to request API access. This typically involves setting up an account and verifying your business details.
Receive API Keys: Once approved, you will be provided with API keys which are essential for authenticating requests.
### Step 2: Set Up Your Environment
Choose an API Client: Decide on a programming environment and API client that suits your development needs (e.g., Postman, cURL, or any HTTP client libraries available for your preferred programming language).
Install Necessary Libraries: For example, if you're using Python, you might use requests library to handle API calls.
### Step 3: Making Your First API Call
Test API Connection: Start by making a simple API request to ensure your API keys are working correctly. A typical first request might be to retrieve information about available companies.
Request:
curl -X GET 'https://fareharbor.com/api/external/v1/companies/'
-H "X-FareHarbor-API-App: APP-KEY"
-H "X-FareHarbor-API-User: USER-KEY"
Response:
{
"companies": [
{
'name': 'XYZ Scuba',
'shortname': 'xyz'
}
]
}
### Step 4: Common API Interactions
Retrieve a list of available companies: The first thing you might want to do is retrieve the list of companies that a given affiliate has access to in FareHarbor. See [`Companies`](#tag/Company-Endpoints) to learn more.
Retrieve a list of bookable items: Next you can identify all of the items on a particular provider that a given affiliate can book. Continuing the above example, we can determine which items on "XYZ Scuba" the user identified by USER-KEY can book. See [`Items`](#tag/Items-Endpoints) to learn more.
Retrieve a list of availability for an item: Having found an item to book, you can access its availability on a per-day basis. See [`Availabilities`](#tag/Availabilities-Endpoints) to learn more.
Create a booking for an availability: Once you've found a bookable availability you can book it by simply POSTing to the availability's booking collection. See [`Bookings`](#tag/Bookings-Endpoints) to learn more.
Retrieve a booking: Given a booking by uuid it's straightforward to access the booking details. See [`Get Booking`](#tag/Bookings-Endpoints/operation/get-booking) to learn more.
### Step 5: Handling API Responses
Check Response Status: Ensure each API call successfully completes by checking the status codes and response messages.
Parse Data: Extract relevant information from the JSON responses for use within your application.
### Step 6: Automate and Scale
Automate Frequent Tasks: Develop scripts or applications that automate common tasks, such as getting availability or fetching regular booking reports.
Handle Errors: Implement robust error handling to deal with potential issues like network errors, API limits, or data inconsistencies.
### Step 8: Security and Compliance
Secure API Keys: Protect your API keys to prevent unauthorized access.
Data Protection: Follow best practices for data protection and ensure compliance with relevant legal regulations such as GDPR (if operating in Europe) or others specific to your location and industry.
### Step 8: Explore Advanced Features
Webhooks: Use FareHarbor's webhook system for real-time updates on bookings and availability changes. See [`Webhooks`](#tag/Webhooks) to learn more.
Custom Integration: Depending on your needs, explore custom integrations that go beyond the basic functionalities, such as integrating with third-party CRM or financial software.
### Documentation and Support
Refer to the Official Documentation: Regularly consult the FareHarbor API documentation for detailed advice on different API endpoints and updates.
Seek Support When Needed: Utilize FareHarbor’s developer support for troubleshooting and guidance on complex integration scenarios.
- name: Availabilities Endpoints
description: |
The `/availabilities` endpoint is used to retrieve all bookable availabilities for a single item within a specified date or date range. The request pulls availability data from the Item calendar of the FareHarbor dashboard. Each individual availability shows a unique PK, which is then used during the booking process, as well as a summary of its related settings, including start/end times, capacity, valid ticket options and their prices, custom fields, party size restrictions, and more.
Here the API Partner can gather the relevant PKs that they need to create their booking, and they can use the data on the API to connect and display the bookable dates and times on the product calendars on their end. The more frequently they hit this endpoint, the more accurate their product calendars will be in respect to FareHarbor.
Online Booking Status: Each availability has an online booking status, which controls how it can be viewed and booked by online customers. In most cases, the status will be set to `auto`, which automatically prevents online customers from booking after a certain time cutoff, based on [item’s settings](https://help.fareharbor.com/dashboard/items/online-booking-settings/).
For a complete description of these statuses and their meaning, go to [https://help.fareharbor.com/dashboard/availabilities/updating/online-booking-status/](https://help.fareharbor.com/dashboard/availabilities/updating/online-booking-status/).
Booking Cutoff: The `effective_booking_cutoff` field exposes the last possible moment bookings are allowed for an availability, accounting for the item's online bookability settings and any custom booking restrictions. This field is only included in the response when `?detailed=yes` is passed on the request.
**Things to Note:**
* API Partners may pull availability at whatever intervals they want, as long as they fall within the rate limit, but we generally recommend that, at minimum, partners pull availability for the next 90 days (in 7 day segments) once per week, for the next 30 days once per day, and for the current day every 2 hours.
* The standard availability endpoints will return the fully detailed availability, including custom field information and headlines. If you are not connecting to custom fields, you can include `/minimal` in your request to exclude custom field information from the response. This can also help with performance speed.
* We are constantly monitoring our API and optimizing for performance. Depending on the complexity of certain products and how they are configured in our system, availability requests for some products may take longer than others. In these cases it helps to reduce the date range being pulled.
* Availability Restrictions:
* FareHarbor supports optional party size booking restrictions at the availability level. The following properties will be included for each availability provided by the availability endpoints to indicate applicable restrictions:
* `minimum_party_size`: minimum number of customers currently allowed on a booking.
* `maximum_party_size`: maximum number of customers currently allowed on a booking.
* Note: a number value will be provided for enabled restrictions; a null value will be provided for restrictions that are not enabled.
* Customer Type Rate Restrictions:
* FareHarbor also supports optional party size booking restrictions at the customer type rate level. The following properties will be included for each customer type rate provided by availability endpoints to indicate applicable restrictions:
* `minimum_party_size`: minimum number of the associated customer type allowed in a party.
* `maximum_party_size`: maximum number of the associated customer type allowed in a party.
* Note: the minimum_party_size restriction only applies when at least one customer of the associated customer type is in the party.
* Note: a number value will be provided for enabled restrictions; a null value will be provided for restrictions that are not enabled.
* Availability start and end times are in the company's local timezone. When providing a date or date range for availabilities, those dates are taken as local time of the company.
- name: Bookings Endpoints
description: |
The bookings endpoints in the FareHarbor API provide comprehensive functionalities for managing reservations efficiently. These endpoints enable developers and business owners to integrate and automate booking-related operations seamlessly into their services. Through these endpoints, users can create, retrieve, update, and cancel bookings directly through the API.
Key functionalities offered by the bookings endpoints include:
* **Creating Bookings:** Enables the creation of new bookings, allowing customers to reserve spots for tours and activities directly through third-party applications.
* **Retrieving Bookings:** Offers the ability to query and retrieve details of existing bookings, providing essential information like booking status, customer details, and payment information.
* **Updating Bookings:** Supports modifications to existing bookings, which is crucial for managing changes in customer plans.
* **Cancelling Bookings:** Allows for the cancellation of bookings, helping to manage availability and customer expectations effectively.
These endpoints are designed to foster a more connected experience between tour and activity operators and their customers by simplifying the booking process through automation and integration. This ensures that businesses can focus more on providing an exceptional service experience, while the logistical aspects of bookings are handled efficiently through the API.
**Things to Note:**
* Orders:
* Orders are a way of grouping collections of bookings so that they can be created or cancelled as a block.
* A booking can belong to an order, but it doesn't have to. An order can include any number of bookings.
* When `order` is not `null`, `order` is an object that provides the following property:
* `display_id`: `string` - A unique identifier for the order.
* See [Orders](#tag/Orders) to learn more about creating and retrieving orders.
- name: Checkin Endpoints
description: |
The check-in endpoints in the FareHarbor API provide essential capabilities for managing the check-in processes efficiently and seamlessly. These endpoints are crucial for businesses in the tour and activity sector, as they allow for real-time, automated check-in operations through integrated systems.
Key functionalities offered by the check-in endpoints include:
* **Checking In Participants:** Automates the process of marking customers as present for an activity, streamlining operations and reducing manual errors.
* **Listing Check-In Status:** Provides the ability to pull information on who has checked in and who hasn't, ensuring staff are well-informed and can make necessary arrangements.
* **Updating Check-In Records:** Supports modifications to check-in records, which can be crucial for managing late arrivals or last-minute changes in customer plans.
* **Integration with Scanning Devices:** Some endpoints are designed to work with barcode or QR code scanning devices to facilitate faster and more reliable check-in procedures.
Integrating these check-in endpoints into business systems helps in providing a smoother and more efficient customer service experience, minimizing wait times, and allowing staff to focus on customer interaction rather than manual check-in processes. By leveraging these APIs, businesses can enhance operational efficiency and improve customer satisfaction.
- name: Company Endpoints
description: |
The Company endpoints in the FareHarbor API provide robust functionalities for accessing and managing information related to companies that offer tours and activities. These endpoints are crucial for developers who need to integrate company-specific data into their applications, ensuring that users have up-to-date and detailed information about the services they are interested in.
Key functionalities offered by the Company endpoints include:
* **Retrieving Company Information:** Enables access to detailed information about a company, including its description, contact details, and available locations. This is vital for providing comprehensive data to users looking to book activities or tours.
* **Listing Services Offered:** Allows for the enumeration of all services and activities offered by a company, which is essential for users to find and book relevant offerings.
* **Accessing Operational Details:** Provides insights into the operational aspects of a company, such as business hours, peak times, and special events, assisting in better planning and resource management.
These endpoints serve as a critical connection between companies in the tour and activity sectors and their potential customers, facilitating seamless information sharing and service discovery. By leveraging these API endpoints, businesses can offer enriched, detailed, and updated data to users, which enhances transparency and trust while promoting ease of access to company offerings.
- name: Items Endpoints
description: |
The Items endpoints in the FareHarbor API provide comprehensive access to detailed information about the various activities and services offered by a company. These endpoints are essential for any application that needs to integrate, display, or manage bookings for specific items or activities within a company's portfolio.
Key functionalities offered by the Items endpoints include:
* **Retrieving Item Details:** Facilitates access to in-depth information about each item, including descriptions, pricing, availability, and any special requirements or features associated with the item.
* **Listing All Items:** Allows users to obtain a list of all available items offered by a company, making it easier to browse and select suitable options based on preferences and requirements.
* **Item Availability:** Provides endpoints to check the availability of items, helping to ensure that the booking process is up-to-date and accurate, preventing overbookings and scheduling conflicts.
* **Customizable Responses:** Supports filtering and customization of the data returned, enabling developers to tailor the API responses to specific needs and ensure that the integration feels native to the application.
By integrating these Items endpoints, developers can enhance their applications with powerful, real-time access to activity data, ensuring that users receive a seamless, accurate, and engaging booking experience. This integration is crucial for facilitating efficient and effective interactions between customers and tour or activity providers.
- name: Crew Members Endpoints
description: |
The Crew Members endpoints in the FareHarbor API provide comprehensive functionality for managing crew assignments on availabilities. These endpoints allow you to assign, update, and remove crew members from specific availability slots, ensuring proper staffing and crew coordination for tours and activities.
Key functionalities offered by the Crew Members endpoints include:
* **Listing Crew Members:** Retrieve all crew members currently assigned to a specific availability, including their roles and notes.
* **Adding Crew Members:** Assign users to availabilities as crew members with optional role assignments and notes.
* **Updating Crew Members:** Modify existing crew member assignments, specifically changing roles or updating notes.
* **Removing Crew Members:** Remove crew members from availabilities when they are no longer needed.
These endpoints are essential for tour operators who need to manage staffing levels, assign specific roles to crew members, and maintain clear communication about crew responsibilities through notes and role assignments.
- name: Users Endpoints
description: |
The Users endpoints provide access to user information within the context of company operations, specifically for crew management purposes.
- name: Roles Endpoints
description: |
The Roles endpoints provide access to role definitions within companies, enabling structured crew member assignments with specific responsibilities and permissions.
- name: Lodging Endpoints
description: |
With our `/lodgings` endpoints our 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.
- name: Affiliates And Integrations
description: |
Read about the robust network and capabilities that FareHarbor offers through its affiliate networks and integrations, facilitating enhanced services and operations for different user types.
## For Affiliates
Available Integrations:
* **FHDN API:** Learn more about our distribution network [here](https://fareharbor.com/scale/distribution-network/fareharbor-distribution-network/)
* **Inventory Access:** Affiliates can access real-time inventory across diverse operators.
- Access companies items & availabilities
- Check customers in via QR codes
- Provide lodging & transportation options
* **Booking Capabilities:** Direct booking functionalities integrated into affiliate platforms.
- Create bookings for customers
- Update bookings
- Collect custom fields for unique business requirements
## For Software Partners
To learn more about software partners visit [here](https://compass.fareharbor.com/partners/software/).
Connected Software Partners:
* **CRM Systems:**
- Call Centers & Automated Inbound Calling
- Web Chats
- Review Management
- Podium
- Yonder
* **Marketing Tools:**
- SMS Marketing
- Digital Marketing
- Sojern
- TourisSolved
- EMail Marketing
- TourAdvantage
- Mailchimp
* **Customer Experience Tools:**
- Advanced Ticketing
- Datatrax
- Waivers
- Wherewolf
- Smartwaiver
- Photos
- Fotaflo
- PicThrive
- Turnstiles
- Alvarado
- Boat Insurance
- Buoy
* **Other Software Partners:**
- Independent Accounting Solutions
- Business Consultants
- Escape Rooms
- Virtual Reality Management
- name: Authentication
description: |
An app key and a user key are required to authenticate all requests to
the FareHarbor external API. The app key identifies your application,
and can be used for all of your affiliates. The user key identifies a specific
user on a specific affiliate.
These keys are in UUID format. Note that these keys *must* be kept private.
If your key is disclosed publicly please contact support@fareharbor.com to have it rotated.
## Keys sent as headers (recommended)
The recommended approach to passing your keys is via the custom headers
`X-FareHarbor-API-App` and `X-FareHarbor-API-User`.
```
GET /api/external/v1/companies/ HTTP/1.1
Host: fareharbor.com
X-FareHarbor-API-App: APP-KEY
X-FareHarbor-API-User: USER-KEY
$ curl -H "X-FareHarbor-API-App: APP-KEY" -H "X-FareHarbor-API-User: USER-KEY" https://fareharbor.com/api/external/v1/companies/
```
## Requesting Keys
If you would like to pursue an integration with the FareHarbor API, please contact strategicpartnerships@fareharbor.com so that we can review your request.
Note that we cannot grant access in all cases.
# --- truncated at 32 KB (754 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fareharbor/refs/heads/main/openapi/_original/fareharbor-home-openapi.yml