### Fetch Subset of Nested Channel Data with _select Parameter Source: https://developer.hospitable.com/docs/connect-api-docs/8e768e6831f6c-requesting-connect-access Illustrates selecting a balanced subset of reservation and nested listing channel data using the _select parameter. This example shows partial data fetching for reservation.listing.channel information, useful for use cases requiring moderate data payload. ```http GET /customers/{customer}/reservations?_select=id,platform_id,listing.id,listing.platform_id,listing.channel.id,listing.public_name,listing.picture ``` -------------------------------- ### Create Auth Code cURL Request Source: https://developer.hospitable.com/docs/connect-api-docs/39tkbt5uqlulb-create-auth-code cURL command example for making a POST request to the Create Auth Code endpoint. Includes Bearer token authentication, required headers (Accept, Authorization, Connect-Version, Content-Type), and the request body with customer_id and redirect_url parameters. ```shell curl --request POST \ --url https://connect.hospitable.com/api/v1/auth-codes \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' \ --header 'Connect-Version: ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "23fead63-7475-4fc8-b3a8-b4bf8f43dc92", "redirect_url": "https://third-party.com/dashboard" }' ``` -------------------------------- ### Authenticate API Request with Bearer Token using cURL Source: https://developer.hospitable.com/docs/connect-api-docs/8e768e6831f6c-requesting-connect-access Demonstrates how to make an authenticated API request to the Hospitable Connect API using Bearer token authentication in the Authorization header. The token must be generated from the partner portal under Settings > Access tokens. This example fetches the customers endpoint. ```bash curl --request GET \ --url https://connect.hospitable.com/api/v1/customers \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Webhook Signature Verification Source: https://developer.hospitable.com/docs/connect-api-docs/tplzdxad3aa2w-payload-fields Instructions and an example for verifying the authenticity of incoming webhooks using a shared secret and HMAC-SHA256. ```APIDOC ## Webhook Signature Verification ### Description Guides on how to verify that incoming webhooks are indeed from Hospitable using the `Signature` header and a webhook secret. ### Method POST ### Endpoint `/webhooks` (Assumed) ### Parameters #### Request Headers - **Signature** (string) - Required - The signature generated by Hospitable for the webhook payload. #### Request Body - **Payload** (string) - Required - The raw JSON string of the webhook payload. #### Environment Variable - **SECRET** (string) - Required - Your webhook secret, used for verification. ### Request Example Assume: - Payload: `{"foo": "bar"}` - Webhook Secret: `"123456"` - Incoming `Signature` header: `cc99bf5947391ddb0d0d9866f5b9d3a68e8b273c5ac8f699b4ae2399a7433118` ### Response #### Success Response (Verification) - The verification process confirms the sender is Hospitable. #### Response Example (PHP verification function) ```php ``` ``` -------------------------------- ### Create a Customer Source: https://developer.hospitable.com/docs/connect-api-docs/8orcx0lt66rag-connect-a-customer Initiates the process by creating a customer record in Hospitable Connect. A customer represents a user within your business. ```APIDOC ## POST /customers ### Description Creates a new customer in the Hospitable Connect system. This customer represents a user in your own business that will be used to establish a connection with an OTA. ### Method POST ### Endpoint /customers ### Parameters #### Request Body - **identifier** (string) - Required - A unique identifier for the customer within your system. ### Request Example ```json { "identifier": "your-customer-unique-id" } ``` ### Response #### Success Response (201 Created) - **data** (object) - Contains the newly created customer object. - **id** (string) - The unique identifier assigned to the customer by Hospitable Connect. #### Response Example ```json { "data": { "id": "cus_abcdef1234567890", "identifier": "your-customer-unique-id" } } ``` ``` -------------------------------- ### API Endpoints Overview Source: https://developer.hospitable.com/docs/connect-api-docs/8e768e6831f6c-requesting-connect-access An overview of the available API endpoints within the Hospitable Connect API, categorized for clarity. ```APIDOC ## API Endpoints Overview The Hospitable Connect API provides the following primary endpoints: 1. **Customers**: Manage customer-related data. 2. **Auth Codes**: Handle authorization codes. 3. **Listings, Pricing, Availability**: Access and manage listing details, pricing information, and availability. 4. **Reservations**: Retrieve and manage reservation data. 5. **Messaging**: Facilitate communication through messaging features. 6. **Channels**: Interact with various booking channels. 7. **Reviews**: Access and manage customer reviews. 8. **Transactions**: Handle financial transaction data. ``` -------------------------------- ### Create an Auth Code Source: https://developer.hospitable.com/docs/connect-api-docs/8orcx0lt66rag-connect-a-customer Generates an authorization code for an existing customer, which is used to initiate the Platform Connection flow. ```APIDOC ## POST /customers/{customerId}/auth-codes ### Description Issues an authorization code for a pre-existing customer. This code is embedded in a URL that allows the customer to enter the Platform Connection flow and grant Hospitable Connect access to their OTA data. ### Method POST ### Endpoint /customers/{customerId}/auth-codes ### Parameters #### Path Parameters - **customerId** (string) - Required - The unique identifier of the customer created in the previous step. #### Request Body - **redirect_url** (string) - Required - The URL to which the customer will be redirected after completing the connection flow. ### Request Example ```json { "redirect_url": "https://your-application.com/callback" } ``` ### Response #### Success Response (201 Created) - **data** (object) - Contains the authorization code and return URL. - **return_url** (string) - The URL the customer needs to visit to start the connection process. #### Response Example ```json { "data": { "return_url": "https://connect.hospitable.com/connect/authenticate/PHrYq2Z3Py9uZm8OUbNiJtAeMvlZEKt5" } } ``` ### Error Handling - **404 Not Found**: If the specified `customerId` does not exist. - **409 Conflict**: If the customer already has an active connection for the target OTA. ``` -------------------------------- ### Requesting Connect Access Source: https://developer.hospitable.com/docs/connect-api-docs/8e768e6831f6c-requesting-connect-access Information required to become an authorized partner and request access to the Hospitable Connect API. This includes providing your product name, a logo URL, and a webhook URL. ```APIDOC ## Requesting Connect Access To gain access to the Hospitable Connect API, you must become an authorized partner. Qualifying partners need to provide the following information: * **Product Name**: The name of your product as it should be displayed to customers. * **Logo URL**: A URL pointing to a hosted, square-formatted image of your logo. * **Webhook URL**: The URL where your webhooks will be sent. To initiate a request, please complete the designated form. Upon approval, you will gain access to your partner portal. ``` -------------------------------- ### Create Auth Code Response - JSON Source: https://developer.hospitable.com/docs/connect-api-docs/39tkbt5uqlulb-create-auth-code JSON response from a successful (201 Created) Create Auth Code request. Returns an AuthCode object containing an expires_at timestamp (5-minute expiration) and a return_url with a magic link that users access to connect their OTA channel. ```json { "data": { "expires_at": "2023-06-23T11:34:54Z", "return_url": "https//connect.hospitable.com/connect/authenticate/PHrYq2Z3Py9uZm8OUbNiJtAeMvlZEKt5" } } ``` -------------------------------- ### Create a Customer in Hospitable Connect Source: https://developer.hospitable.com/docs/connect-api-docs/8orcx0lt66rag-connect-a-customer Initiates the process by creating a customer object within Hospitable Connect. This customer represents a user in your business and is essential for establishing connections with OTAs. The request requires a unique identifier for the customer. ```javascript { "data": { "id": "my-personal-identifier", ... } } ``` -------------------------------- ### Authentication Source: https://developer.hospitable.com/docs/connect-api-docs/8e768e6831f6c-requesting-connect-access Details on how to authenticate API requests using an access token generated from the partner portal. All requests must include an `Authorization` header with a Bearer token. ```APIDOC ## Authentication Authentication is managed through access tokens generated within your partner portal under **Settings > Access tokens**. This is the sole authentication step required. All requests made to the API must include the `Authorization` header, with the value set to `Bearer `, where `` is your generated access token. ### Example Request ```bash curl --request GET \ --url https://connect.hospitable.com/api/v1/customers \ --header 'Authorization: Bearer ' ``` ``` -------------------------------- ### Generate an Authentication Code for a Customer Source: https://developer.hospitable.com/docs/connect-api-docs/8orcx0lt66rag-connect-a-customer After a customer is registered, this step generates an authentication code. This code is a URL that directs the customer to the Platform Connection flow, allowing them to grant Hospitable Connect access to their Airbnb data. Ensure the customer exists before generating the code. ```javascript { "data": { "return_url": " ... } } ``` -------------------------------- ### Fetching Data with `_select` Parameter Source: https://developer.hospitable.com/docs/connect-api-docs/8e768e6831f6c-requesting-connect-access This section details how to use the `_select` query parameter to control the amount and type of data fetched in a single request, allowing for optimization between fast, small requests and single, larger requests with nested data. ```APIDOC ## Fetching More Data in a Single Request (`_select`) The Hospitable Connect API provides flexibility in controlling the payload fetched by each endpoint, including nested data. You can optimize for: 1. **Few fast, small requests**: Ideal for scenarios like mobile apps where only a subset of data is needed (e.g., a list of reservations). * Example: `GET /customers/{customer}/reservations?_select=id,status,listing.id,listing.public_name,listing.picture` 2. **Single, potentially slower, large request**: Suitable for backend-to-backend calls requiring more comprehensive and nested data. * Example (full dataset for `reservation.listing.channel`): `GET /customers/{customer}/reservations?_select=id,platform,platform_id,booking_date,arrival_date,departure_date,status,guests,guest,listing,listing.id,listing.platform,listing.platform_id,listing.public_name,listing.private_name,listing.picture,listing.address,listing.bathrooms,listing.bedrooms,listing.available,listing.pricing,listing.availability,listing.platform_settings,listing.channel,listing.channel.id,listing.channel.platform,listing.channel.platform_id,listing.channel.name,listing.channel.picture,listing.channel.location,listing.channel.description,listing.channel.first_connected_at` * Example (subset of data for `reservation.listing.channel`): `GET /customers/{customer}/reservations?_select=id,platform_id,listing.id,listing.platform_id,listing.channel.id,listing.public_name,listing.picture` **Important Note**: We do not support `_select all` (e.g., `listing.*`). You must explicitly select the fields you need. This practice aids in better API visibility and long-term improvement. ``` -------------------------------- ### Fetch Minimal Reservation Data with _select Parameter Source: https://developer.hospitable.com/docs/connect-api-docs/8e768e6831f6c-requesting-connect-access Shows how to optimize API requests by selecting only necessary fields using the _select parameter. This approach is ideal for mobile applications or scenarios requiring fast, small requests with subset JSON data. Returns only id, status, and nested listing information. ```http GET /customers/{customer}/reservations?_select=id,status,listing.id,listing.public_name,listing.picture ``` -------------------------------- ### Fetch Complete Nested Reservation Data with _select Parameter Source: https://developer.hospitable.com/docs/connect-api-docs/8e768e6831f6c-requesting-connect-access Demonstrates fetching comprehensive nested data including full reservation, listing, and channel information using the _select parameter. This approach optimizes for single, potentially slower, large requests suitable for backend-to-backend calls with complete dataset requirements. ```http GET /customers/{customer}/reservations?_select=id,platform,platform_id,booking_date,arrival_date,departure_date,status,guests,guest,listing,listing.id,listing.platform,listing.platform_id,listing.public_name,listing.private_name,listing.picture,listing.address,listing.bathrooms,listing.bedrooms,listing.available,listing.pricing,listing.availability,listing.platform_settings,listing.channel,listing.channel.id,listing.channel.platform,listing.channel.platform_id,listing.channel.name,listing.channel.picture,listing.channel.location,listing.channel.description,listing.channel.first_connected_at ``` -------------------------------- ### Create Auth Code Request Body - JSON Source: https://developer.hospitable.com/docs/connect-api-docs/39tkbt5uqlulb-create-auth-code JSON request body for creating an authentication code. Requires a customer_id to identify the customer and a redirect_url where the user will be sent after completing the connect flow. Both fields are required strings. ```json { "customer_id": "23fead63-7475-4fc8-b3a8-b4bf8f43dc92", "redirect_url": "https://third-party.com/dashboard" } ``` -------------------------------- ### Connect API Pricing Updates Source: https://developer.hospitable.com/docs/connect-api-docs/ca0mar8wa17km-calendar-restriction Information on updating Airbnb calendar prices through the Connect API for customers with the Operations scope. ```APIDOC ## PUT /api/connect/properties/{property_id}/pricing ### Description Updates the pricing for a specific property's Airbnb calendar via the Connect API. This is only available for customers with the Operations scope integration. ### Method PUT ### Endpoint `/api/connect/properties/{property_id}/pricing` ### Parameters #### Path Parameters - **property_id** (string) - Required - The unique identifier of the property. #### Query Parameters None. #### Request Body - **date** (string) - Required - The date for which to update the price (YYYY-MM-DD). - **price** (number) - Required - The new price for the given date. ### Request Example ```json { "date": "2023-10-27", "price": 160.00 } ``` ### Response #### Success Response (200) - **status** (string) - Indicates the success of the operation. - **message** (string) - A confirmation message. #### Response Example ```json { "status": "success", "message": "Pricing updated successfully." } ``` ``` -------------------------------- ### Calendar Restriction Summary Source: https://developer.hospitable.com/docs/connect-api-docs/ca0mar8wa17km-calendar-restriction Summary table outlining write capabilities based on integration scope and API used. ```APIDOC ## Calendar Restriction Summary This table summarizes the ability to modify pricing and availability based on the customer's integration with Hospitable and the API used. | Customer Type | Integration | Connection Scope | Modify Pricing | Modify Availability | |---|---|---|---|---| | Your customers | Hospitable Connect | Limited connection | YES | NO | | Your mutual customers with Hospitable | Hospitable Connect | Limited connection | NO | NO | | Your mutual customers with Hospitable | Hospitable Core via Public API | Limited connection | NO | NO | | Your mutual customers with Hospitable | Hospitable Core via Public API | Full connection | YES | YES | ``` -------------------------------- ### Rate Limits Source: https://developer.hospitable.com/docs/connect-api-docs/8e768e6831f6c-requesting-connect-access Information on API rate limits, which are set at 60 requests per minute per vendor. Exceeding this limit will result in a `429 Too Many Requests` response. ```APIDOC ## Rate Limits API endpoints are rate-limited to **60 requests per minute per vendor**. If you exceed this limit, you will receive a `429 Too Many Requests` response. ``` -------------------------------- ### POST /api/v1/auth-codes Source: https://developer.hospitable.com/docs/connect-api-docs/39tkbt5uqlulb-create-auth-code Generates an authentication code required to authenticate customers for using Hospitable Connect. The returned code contains a URL that allows users to connect, reconnect, or refresh their channel connections. ```APIDOC ## POST /api/v1/auth-codes ### Description Generates an authentication code required to authenticate customers for using Hospitable Connect. The returned code contains a URL that allows users to connect, reconnect, or refresh their channel connections. Auth codes expire in 5 minutes if not accessed. ### Method POST ### Endpoint https://connect.hospitable.com/api/v1/auth-codes ### Parameters #### Headers - **Connect-Version** (string) - API version - **Accept** (string) - Optional - Specifies the desired response format, defaults to application/json. - **Authorization** (string) - Required - Bearer token for authentication. #### Request Body - **customer_id** (string) - Required - The key used to identify your customer. - **redirect_url** (string) - Required - The URL to which the user is redirected after completing the connect flow. ### Request Example ```json { "customer_id": "23fead63-7475-4fc8-b3a8-b4bf8f43dc92", "redirect_url": "https://third-party.com/dashboard" } ``` ### Response #### Success Response (201 Created) - **data** (object) - Contains the authentication code details. - **expires_at** (string) - The timestamp when the authentication code will expire. - **return_url** (string) - The URL generated for authentication. #### Error Responses - **401** - Unauthorized - **422** - Unprocessable Entity - **500** - Internal Server Error #### Response Example (201 Created) ```json { "data": { "expires_at": "2023-06-23T11:34:54Z", "return_url": "https//connect.hospitable.com/connect/authenticate/PHrYq2Z3Py9uZm8OUbNiJtAeMvlZEKt5" } } ``` ``` -------------------------------- ### Webhook Payload Structure Source: https://developer.hospitable.com/docs/connect-api-docs/tplzdxad3aa2w-payload-fields Details the standard fields included in every webhook payload sent by the Hospitable API. ```APIDOC ## Webhook Payload Structure ### Description This endpoint describes the common fields present in all webhook payloads. ### Method POST ### Endpoint `/webhooks` (Assumed, as the documentation specifies POST requests to a user-defined URL) ### Parameters #### Query Parameters None specified. #### Request Body - **id** (ULID string) - Required - A unique ordered ID assigned to the payload. - **data** (object OR array of objects) - Required - The main payload content, mirroring relevant API endpoints. - **action** (string) - Required - The action that triggered the webhook (e.g., `channel.activated`). - **created** (UTC Zulu ISO8601 String) - Required - The timestamp when the payload was initially created. - **version** (string) - Required - The version of the webhook payload format. ### Request Example ```json { "id": "01GTKD6ZYFVQMR0RWP4HBBHNZC", "data": {}, "action": "channel.activated", "created": "2023-10-01T09:35:24Z", "version": "1.0" } ``` ### Response #### Success Response (200) - **Status**: `200 OK` indicates successful receipt of the webhook. #### Response Example ```json { "message": "Webhook received successfully" } ``` ``` -------------------------------- ### Core/Public API Calendar Updates Source: https://developer.hospitable.com/docs/connect-api-docs/ca0mar8wa17km-calendar-restriction Details on updating calendars via the Core/Public API for customers with PMS scope integration. ```APIDOC ## PUT /api/properties/{property_id}/calendar ### Description Updates the calendar for a specific property. This endpoint is available for customers with the full PMS scope integration with Airbnb. ### Method PUT ### Endpoint `/api/properties/{property_id}/calendar` ### Parameters #### Path Parameters - **property_id** (string) - Required - The unique identifier of the property whose calendar needs to be updated. #### Query Parameters None. #### Request Body - **date** (string) - Required - The date for which the calendar needs to be updated (YYYY-MM-DD). - **availability** (boolean) - Required - Whether the calendar is available (true) or not (false). - **price** (number) - Optional - The price for the given date. ### Request Example ```json { "date": "2023-10-27", "availability": true, "price": 150.00 } ``` ### Response #### Success Response (200) - **status** (string) - Indicates the success of the operation. - **message** (string) - A confirmation message. #### Response Example ```json { "status": "success", "message": "Calendar updated successfully." } ``` #### Error Response (422) - **status_code** (integer) - The HTTP status code (422). - **reason_phrase** (string) - Explains the reason for the error, e.g., 'This property has a channel that is calendar restricted, and updates can not be made to the calendar'. #### Response Example ```json { "status_code": 422, "reason_phrase": "This property has a channel that is calendar restricted, and updates can not be made to the calendar." } ``` ``` -------------------------------- ### IP Address Whitelisting Source: https://developer.hospitable.com/docs/connect-api-docs/tplzdxad3aa2w-payload-fields Provides the IP address range from which Hospitable webhooks are sent, recommending whitelisting for security. ```APIDOC ## IP Address Whitelisting ### Description Information on the IP range used for sending webhooks to help secure your endpoint. ### Method N/A ### Endpoint N/A ### Parameters N/A ### Request Example N/A ### Response #### Success Response - Our webhooks will be sent from the following IP range: `38.80.170.0/24`. - It is advised to whitelist only this IP range for your webhook handler to enhance security. ``` -------------------------------- ### Requesting Historical Webhooks Source: https://developer.hospitable.com/docs/connect-api-docs/tplzdxad3aa2w-payload-fields Information on how to request the re-sending of failed webhooks after a specified date. ```APIDOC ## Requesting Historical Webhooks ### Description Details the process for requesting historical webhook resends for specific dates. ### Method POST (Assumed, likely via a support or platform team request) ### Endpoint Internal Platform API or Support Channel (Not publicly exposed in documentation) ### Parameters #### Request Body - **date** (string) - Required - The date from which to resend failed webhooks. ### Request Example (This would likely be a request made through a support channel or a specific internal API endpoint, not a standard webhook receiver.) ### Response #### Success Response - Confirmation that the historical webhook resend request has been processed or is being processed. #### Response Example ```json { "message": "Historical webhook resend request submitted for date YYYY-MM-DD." } ``` ``` -------------------------------- ### Webhook Retry Mechanism Source: https://developer.hospitable.com/docs/connect-api-docs/tplzdxad3aa2w-payload-fields Explains the retry policy implemented by Hospitable when a webhook handler does not respond with a 200 OK status. ```APIDOC ## Webhook Retry Mechanism ### Description Details the retry attempts and exponential back-off strategy for failed webhook deliveries. ### Method POST ### Endpoint `/webhooks` (Assumed) ### Parameters None applicable to the retry mechanism itself, but the initial request parameters apply. ### Request Example (Same as initial webhook request) ### Response #### Failure Response (Non-200 status codes) - If the webhook handler does not respond with a `200 OK`, Hospitable will retry the delivery. - Retries occur up to 5 times. - Retries use an exponential back-off strategy: `1 sec, 5 sec, 10 sec, 1 hr, 6 hr`. #### Response Example (for retry) (The system will repeatedly attempt to send the payload until a 200 OK is received or retries are exhausted.) ``` -------------------------------- ### Verify Webhook Signature with HMAC-SHA256 in PHP Source: https://developer.hospitable.com/docs/connect-api-docs/tplzdxad3aa2w-payload-fields Validates incoming webhook requests by computing an HMAC-SHA256 signature of the payload using a shared secret and comparing it with the signature header. This ensures the webhook originates from Hospitable. The function uses PHP's hash_hmac() function with SHA256 algorithm and hash_equals() for constant-time comparison to prevent timing attacks. ```php