Airbnb
This guide walks through connecting Airbnb to Channex over the API: generating the OAuth connection link, handling the redirect, discovering the listings, mapping them to rate plans, activating the connection, and managing the listings afterwards.
Airbnb is the exception among channels. Where other OTAs are connected by creating a channel with credentials (POST /api/v1/channels), an Airbnb connection is established through OAuth: you generate a connection link, the property owner opens it, signs in to Airbnb and authorizes Channex — and the channel connection is created automatically. Mappings are also different: instead of the rate_plans array of the connection payload, Airbnb listings are mapped one by one through dedicated mapping endpoints.
API requests are authenticated with an API key sent in the user-api-key header.
The flow at a glance
Generate a connection link and hand it to the property owner.
The owner authorizes Channex on Airbnb; the connection is created automatically — inactive.
Handle the redirect and read the connection.
List the Airbnb listings of the connected account.
Map each listing to a rate plan.
Activate the connection.
Load the existing reservations.
After that, the connection is live: Channex pushes availability, rates and restrictions to Airbnb and receives bookings back. The listings themselves — their pricing, availability rules, booking settings, publication state, promotions and more — are managed through the connection, covered in the second half of this guide.
1. Generate the connection link
Generate an Airbnb connection link. Airbnb connections are established through OAuth: the link is opened by the property owner, who signs in to Airbnb and authorizes Channex, and a channel connection is created automatically — inactive, ready to be mapped and activated. The link supports third-party redirects, so the flow can be embedded in an external application without sending the user to the Channex interface.
After the authorization completes, the user is redirected to redirect_uri with ?success=true&channel_id={channel_id}&token={token} appended — the ID of the created (or re-connected) channel connection and the token submitted here. On failure the user is redirected to failure_redirect_uri with ?success=false. The link is valid for two hours.
An Airbnb account holds one connection: re-connecting an existing connection is done by passing its channel_id.
Request payload of the connection link generation.
The request has succeeded.
JSON:API document wrapping a single resource.
The request has missing or invalid arguments; details lists the messages per argument.
The request to the channel took too long and was aborted; retry later.
POST /api/v1/meta/airbnb/connection_link HTTP/1.1
Host: app.channex.io
Content-Type: application/json
Accept: */*
Content-Length: 303
{
"connection_link": {
"group_id": "a60df2a7-fbaf-49b5-a8bb-35e736d5e24d",
"properties": [
"1519fa73-a0f4-44f3-ab8d-d29412834588"
],
"channel_id": "3a3692e9-4790-4bae-9505-160681277d5c",
"redirect_uri": "https://example.com",
"failure_redirect_uri": "https://example.com",
"token": "text",
"title": "text",
"settings": {}
}
}{
"data": {
"type": "connection_link",
"attributes": {
"url": "https://example.com"
}
}
}Pass the group and the properties the new connection should belong to. Multiple properties can be connected through one Airbnb connection.
Three fields shape the flow for an external application:
redirect_uri— where the user lands after a successful authorization. Channex appends?success=true&channel_id={channel_id}&token={token}: the ID of the created connection and yourtokenechoed back.failure_redirect_uri— where the user lands when the connection fails. Channex appends?success=false.token— a free-form value of yours (a session key, a user ID) to associate the incoming redirect with the right user in your system.
The settings object becomes the connection's settings once it is created — see the settings reference below.
The returned url is the Airbnb authorization page. Hand it to the property owner; it is valid for two hours.
2. The authorization and the created connection
When the owner authorizes Channex on Airbnb, Channex creates the channel connection automatically and redirects the browser to your redirect_uri. The connection starts inactive — it is the connection you now map and activate. Its default title is New AirBNB Channel unless a title was given at link generation.
One Airbnb account holds one connection. To re-connect an existing connection (for example, after its authorization was revoked), generate a new link with its channel_id — the owner re-authorizes, and the tokens are refreshed on the same connection.
3. Read the connection
Retrieve a single channel connection.
Unlike the list, the response carries the connection's known mappings — see the known_mappings relationship.
API key for programmatic access, sent in the user-api-key header.
Channel connection ID.
716305c4-561a-4561-a187-7f5b8aeb5920The request has succeeded.
JSON:API document wrapping a single resource.
Authentication credentials are missing or invalid.
The authenticated user lacks permission to perform this action.
The requested resource does not exist.
A backing service is temporarily unavailable; retry the request later.
GET /api/v1/channels/{id} HTTP/1.1
Host: app.channex.io
user-api-key: YOUR_API_KEY
Accept: */*
{
"data": {
"type": "channel",
"id": "716305c4-561a-4561-a187-7f5b8aeb5920",
"attributes": {
"id": "96177287-c3b2-4d98-9eb7-5c1927795825",
"title": "Booking.com - Main",
"channel": "BookingCom",
"currency": "USD",
"is_active": true,
"settings": {
"derived_option": {}
},
"rate_plans": [
{
"id": "b217a47d-c282-4591-a873-7758f2883237",
"rate_plan_id": "7e9409b4-160b-4412-941f-09c2c205b13b",
"settings": {
"derived_option": {}
}
}
],
"properties": [
"daec1c06-a9f6-4a25-88fa-cc4e9dbea436"
],
"actions": [
"load_future_reservations"
],
"expected_removal_date": "2026-08-17",
"inserted_at": "2026-08-12T10:12:04.740476",
"updated_at": "2026-08-12T10:14:37.786888",
"status": "active"
},
"relationships": {
"group": {
"data": {
"id": "5b79c003-a0b0-45b5-8428-e006a26b6a82",
"type": "group"
}
},
"properties": {
"data": [
{
"id": "daec1c06-a9f6-4a25-88fa-cc4e9dbea436",
"type": "property"
}
]
},
"known_mappings": {
"data": [
{
"id": "d1a48009-fc52-4940-9f68-e7f609b73f01",
"type": "known_mapping",
"attributes": {
"id": "d1a48009-fc52-4940-9f68-e7f609b73f01",
"type": "auto",
"rate_plan_code": "text",
"room_type_code": "text",
"rate_plan_id": "7e9409b4-160b-4412-941f-09c2c205b13b",
"room_type_id": "06ededd7-16c1-40f7-97ee-b98bf8796fb9"
}
}
]
}
}
}
}Use the channel_id from the redirect. The interesting parts of an Airbnb connection are its settings (the values submitted with the link, plus the OAuth tokens managed by Channex) and rate_plans — the listing mappings, empty so far.
4. Discover the listings
List the Airbnb listings of the channel connection's Airbnb account: identifier, title, type, location, occupancy options, quality status, and synchronization category of each listing. The listing identifiers are used to map listings — see POST /channels/{channel_id}/mappings. Listings without a title are omitted.
The listings are requested from Airbnb. For Airbnb channel connections; other channels receive 400 Bad Request.
API key for programmatic access, sent in the user-api-key header.
Channel connection ID.
716305c4-561a-4561-a187-7f5b8aeb5920The request has succeeded.
JSON:API document wrapping a single resource.
The request cannot be processed in the current state.
Authentication credentials are missing or invalid.
The authenticated user lacks permission to perform this action.
The requested resource does not exist.
The channel could not return the details; errors carries the reason the channel reported, or null when it gave none.
A backing service is temporarily unavailable; retry the request later.
GET /api/v1/channels/{channel_id}/action/listings HTTP/1.1
Host: app.channex.io
user-api-key: YOUR_API_KEY
Accept: */*
{
"data": {
"listing_id_dictionary": {
"values": [
{
"id": "42544559",
"title": "Test Property · Test Channex Property",
"type": "apartment",
"occupancies": [
1,
2,
3,
4
],
"synchronization_category": "text",
"city": "text",
"country_code": "DE",
"quality_status": "text"
}
]
}
}
}Returns the listings of the connected Airbnb account: identifier, title, type, location, occupancy options, quality status. The listing id is what a mapping needs.
For a deeper look at one listing — rooms and beds, amenities, photos, descriptions, and its current booking settings, pricing settings and availability rules:
Retrieve the details of an Airbnb listing: the listing record as Airbnb reports it — location, capacity, rooms and beds, amenities, photos, descriptions — supplemented with the listing's booking settings, pricing settings, and availability rules.
The details are requested from Airbnb. For Airbnb channel connections; other channels receive 400 Bad Request.
API key for programmatic access, sent in the user-api-key header.
Channel connection ID.
716305c4-561a-4561-a187-7f5b8aeb5920Airbnb listing ID.
The request has succeeded.
JSON:API document wrapping a single resource.
The request cannot be processed in the current state.
Authentication credentials are missing or invalid.
The authenticated user lacks permission to perform this action.
The requested resource does not exist.
The channel could not return the details; errors carries the reason the channel reported, or null when it gave none.
A backing service is temporarily unavailable; retry the request later.
GET /api/v1/channels/{channel_id}/action/listing_details?listing_id=text HTTP/1.1
Host: app.channex.io
user-api-key: YOUR_API_KEY
Accept: */*
{
"data": {
"listing": {
"id": 42544559,
"id_str": "42544559",
"name": "Test Property · Test Channex Property",
"listing_nickname": "Test Property",
"property_type_category": "apartment",
"property_type_group": "apartments",
"room_type_category": "entire_home",
"tier": "marketplace",
"person_capacity": 4,
"bedrooms": 2,
"beds": 3,
"bathrooms": 1,
"bathroom_shared": null,
"bathroom_shared_with_category": null,
"common_spaces_shared": null,
"common_spaces_shared_with_category": null,
"listing_currency": "EUR",
"listing_price": 9,
"has_availability": true,
"rate_plan_enabled": false,
"synchronization_category": null,
"amenity_categories": [
"allows_pets"
],
"amenities": {
"ALLOWS_PETS": {
"instruction": "",
"is_present": true,
"metadata": null
}
},
"apt": "",
"city": "Berlin",
"state": "Berlin",
"street": "Musterstraße 12",
"zipcode": "10115",
"country_code": "DE",
"lat": 52.520008,
"lng": 13.404954,
"user_defined_location": false,
"display_exact_location_to_guest": false,
"directions": "",
"check_in_option": null,
"house_manual": null,
"wifi_network": null,
"wifi_password": null,
"permit_or_tax_id": null,
"property_external_id": null,
"listing_approval_status": null,
"listing_import_id": null,
"listing_views": null,
"total_inventory_count": null,
"rooms": [
{
"id": 55201931,
"id_str": "55201931",
"listing_id": 42544559,
"listing_id_str": "42544559",
"room_number": 1,
"room_type": "bedroom",
"room_amenities": [],
"beds": [
{
"quantity": 1,
"type": "double_bed"
}
]
}
],
"images": [
{
"id": "42544559_284116093",
"listing_id": 42544559,
"listing_id_str": "42544559",
"caption": "",
"category": "LISTING",
"sort_order": 1,
"room_id": null,
"room_id_str": null,
"amenity": null,
"thumbnail_url": "https://a0.muscache.com/im/pictures/82f0aac5-9788-4128-831f-3b9b819face0.jpg?aki_policy=x_small",
"small_url": "https://a0.muscache.com/im/pictures/82f0aac5-9788-4128-831f-3b9b819face0.jpg?aki_policy=small",
"large_url": "https://a0.muscache.com/im/pictures/82f0aac5-9788-4128-831f-3b9b819face0.jpg?aki_policy=large",
"extra_medium_url": "https://a0.muscache.com/im/pictures/82f0aac5-9788-4128-831f-3b9b819face0.jpg?aki_policy=x_medium",
"extra_large_url": "https://a0.muscache.com/im/pictures/82f0aac5-9788-4128-831f-3b9b819face0.jpg?aki_policy=x_large"
}
],
"descriptions": {
"listing_id": 42544559,
"listing_id_str": "42544559",
"locale": "en",
"machine_translated": false,
"name": "Test Channex Property",
"summary": "Test Channex Property",
"description": "Test Channex Property\n\nDescription\n\nGuest access details",
"space": "Description",
"access": "Guest access details",
"neighborhood_overview": "Overview",
"transit": "Getting around",
"notes": "Other things to note",
"house_rules": null,
"interaction": null
},
"booking_settings": {
"instant_booking_allowed_category": "everyone",
"instant_book_welcome_message": null,
"cancellation_policy_settings": {
"cancellation_policy_category": "flexible",
"lts_cancellation_policy_id": null,
"non_refundable_price_factor": null
},
"check_in_time_start": "15",
"check_in_time_end": "NOT_SELECTED",
"check_out_time": null,
"guest_controls": {
"allows_children_as_host": null,
"allows_events_as_host": null,
"allows_infants_as_host": null,
"allows_pets_as_host": true,
"allows_smoking_as_host": null,
"children_not_allowed_details": null,
"pet_capacity": 5
},
"listing_expectations_for_guests": []
},
"pricing_settings": {
"listing_currency": "EUR",
"default_daily_price": 9,
"weekend_price": 11,
"price_per_extra_person": 6,
"guests_included": 5000,
"cleaning_fee": null,
"security_deposit": null,
"monthly_price_factor": 0,
"weekly_price_factor": 0,
"eligible_for_pass_through_taxes": true,
"pass_through_taxes": [],
"pass_through_taxes_collection_type": "NO_AIRBNB_COLLECTED_TAX",
"default_pass_through_taxes_collection_type": "NO_AIRBNB_COLLECTED_TAX",
"allowed_pass_through_taxes_collection_types": [
"NO_AIRBNB_COLLECTED_TAX"
],
"standard_fees": [
{
"amount": 2,
"amount_type": "flat",
"charge_type": "PER_GROUP",
"fee_type": "PASS_THROUGH_PET_FEE",
"fee_unit_type": null,
"offline": false
}
],
"default_pricing_rules": []
},
"availability_rules": {
"booking_lead_time": 6,
"max_days_notice": -1,
"allow_rtb_beyond_max_days_notice": false,
"allow_rtb_above_max_nights": false,
"turnover_days": 1,
"default_min_nights": 1,
"default_max_nights": 1125,
"seasonal_min_nights": [],
"day_of_week_check_in": [
true,
true,
true,
true,
true,
true,
true
],
"day_of_week_check_out": [
true,
true,
true,
true,
true,
true,
true
],
"day_of_week_min_nights": [
-1,
-1,
-1,
-1,
-1,
-1,
-1
]
}
}
}
}5. Map the listings
Each Airbnb listing is mapped to a Channex rate plan with its own mapping object — one create call per listing:
Create a rate plan mapping on a channel connection: associate a rate plan of the property with a room and rate of the channel, described by the adapter-specific settings. If the rate plan's property is not attached to the channel connection yet, it is attached automatically. The stored settings are the adapter's defaults merged with the submitted keys, and the created mapping appears in the connection's rate_plans. An ARI synchronization of the new mapping is performed in the background.
For Airbnb connections the settings are seeded from the listing's availability rule and pricing settings, mapping the same listing twice is rejected, and the mapping is submitted to Airbnb immediately — a failure reported by Airbnb cancels the creation.
API key for programmatic access, sent in the user-api-key header.
Channel connection ID.
716305c4-561a-4561-a187-7f5b8aeb5920Request payload of the mapping create and update operations.
The request has succeeded.
JSON:API document wrapping a single resource.
Authentication credentials are missing or invalid.
The requested resource does not exist.
The request has missing or invalid arguments; details lists the messages per argument.
A backing service is temporarily unavailable; retry the request later.
POST /api/v1/channels/{channel_id}/mappings HTTP/1.1
Host: app.channex.io
user-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 113
{
"mapping": {
"rate_plan_id": "7e9409b4-160b-4412-941f-09c2c205b13b",
"settings": {
"listing_id": "54843145465465419"
}
}
}{
"data": {
"type": "channel_rate_plan",
"id": "716305c4-561a-4561-a187-7f5b8aeb5920",
"attributes": {
"id": "b217a47d-c282-4591-a873-7758f2883237",
"settings": {
"listing_id": "54843145465465419",
"published": false,
"sync_category": "pending",
"primary_occ": true,
"listing_type": null,
"pricing_availability_model": {
"type": "standard",
"in_model_transition": null
},
"availability_rule": {
"booking_lead_time": 0,
"max_days_notice": -1,
"default_min_nights": 1,
"default_max_nights": 1125,
"allow_rtb_above_max_nights": false,
"turnover_days": 1,
"day_of_week_check_in": [
true,
true,
true,
true,
true,
true,
true
],
"day_of_week_check_out": [
true,
true,
true,
true,
true,
true,
true
],
"day_of_week_min_nights": [
-1,
-1,
-1,
-1,
-1,
-1,
-1
]
},
"pricing_setting": {
"listing_currency": "USD",
"min_stay_type": "Arrival",
"default_daily_price": 0,
"weekend_price": 0,
"guests_included": 0,
"price_per_extra_person": 0,
"cleaning_fee": 0,
"security_deposit": 0,
"weekly_price_factor": 0,
"monthly_price_factor": 0,
"eligible_for_pass_through_taxes": true,
"pass_through_taxes_collection_type": "NO_AIRBNB_COLLECTED_TAX",
"pass_through_taxes": [],
"standard_fees": [],
"default_pricing_rules": []
}
}
},
"relationships": {
"channel": {
"data": {
"id": "96177287-c3b2-4d98-9eb7-5c1927795825",
"type": "channel"
}
}
}
}
}Airbnb Create Mapping API is async and take about 30 seconds to connect and receive all required information from Airbnb side.
For Airbnb the mapping settings carry the listing_id from step 4. On creation Channex seeds the mapping's settings from the listing itself — its availability rule and pricing settings — and submits the mapping to Airbnb immediately; mapping the same listing twice is rejected.
To remove a listing from the connection:
Remove a rate plan mapping from a channel connection. The removal is propagated to the channel in the background.
API key for programmatic access, sent in the user-api-key header.
Channel connection ID.
716305c4-561a-4561-a187-7f5b8aeb5920Mapping ID — the rate_plans[].id of the channel connection.
716305c4-561a-4561-a187-7f5b8aeb5920The request has succeeded.
Success response carrying only a meta message (no resource body).
Authentication credentials are missing or invalid.
The requested resource does not exist.
A backing service is temporarily unavailable; retry the request later.
DELETE /api/v1/channels/{channel_id}/mappings/{mapping_id} HTTP/1.1
Host: app.channex.io
user-api-key: YOUR_API_KEY
Accept: */*
{
"meta": {
"message": "Success"
}
}Airbnb Remove Mapping API is async and take about 30 seconds to receive confirmation from Airbnb side. On re-mapping flow, please, add a pause between remove and create mapping requests.
6. Activate the connection
Activate a channel connection. The connection starts exchanging data with the channel: a full synchronisation pushes availability, rates and restrictions, and any scheduled removal date is cleared. Reviews and scores begin to be collected for Airbnb, Booking.com and Expedia connections.
The connection must be mapped first — it needs at least one property, and at least one mapped rate plan unless the channel does not require rate mapping. Activating an already active connection succeeds without changes.
API key for programmatic access, sent in the user-api-key header.
Channel connection ID.
716305c4-561a-4561-a187-7f5b8aeb5920The request has succeeded.
Success response carrying only a meta message (no resource body).
Authentication credentials are missing or invalid.
The authenticated user lacks permission to perform this action.
The requested resource does not exist.
The request body failed validation.
A backing service is temporarily unavailable; retry the request later.
POST /api/v1/channels/{id}/activate HTTP/1.1
Host: app.channex.io
user-api-key: YOUR_API_KEY
Accept: */*
{
"meta": {
"message": "Success"
}
}Activation requires at least one mapped rate plan. It starts the synchronization: Channex pushes the full current availability, rates and restrictions to Airbnb and begins collecting bookings, reviews and scores.
The counterpart is deactivation, which stops the synchronization but keeps the connection and its mappings:
Deactivate a channel connection. The connection stops sending updates to the channel, and its removal is scheduled for 30 days later — see expected_removal_date. No synchronisation is sent to the channel.
Existing mappings are kept. A connection spanning more than one property, and an Airbnb connection, must have its rate plan mappings removed before it can be deactivated. Deactivating an already inactive connection succeeds without changes.
API key for programmatic access, sent in the user-api-key header.
Channel connection ID.
716305c4-561a-4561-a187-7f5b8aeb5920The request has succeeded.
Success response carrying only a meta message (no resource body).
Authentication credentials are missing or invalid.
The authenticated user lacks permission to perform this action.
The requested resource does not exist.
The request body failed validation.
A backing service is temporarily unavailable; retry the request later.
POST /api/v1/channels/{id}/deactivate HTTP/1.1
Host: app.channex.io
user-api-key: YOUR_API_KEY
Accept: */*
{
"meta": {
"message": "Success"
}
}7. Load the existing reservations
A freshly connected account usually already holds future reservations. Pull them into Channex:
Body (optional):
The preferred form is per listing (listing_id in the body) — call it for each newly mapped listing. Without a body the load covers every mapped listing of the connection. The import runs in the background and does not trigger guest notifications or availability changes.
Airbnb connection settings reference
The connection settings, submitted with the connection link and stored on the connection:
min_stay_type
Arrival or Through — which of the property's minimum-stay restrictions is sent to Airbnb. Airbnb supports a single minimum-stay type.
booking_amount_settings
Payout Amount or Total Paid Amount — which total is saved on bookings.
cohost_payout_calculations
When true, booking amounts are decreased by the co-host commission.
send_email_notifications
When true, Channex sends email notifications about new bookings.
email
The address the notifications go to.
When the connection's Airbnb authorization becomes invalid (revoked by the host, expired), bookings and synchronization stop — re-connect through a new connection link with the channel_id, as in step 1.
Last updated