openapi: 3.2.0 info: title: Hostfully Leads Test Endpoint API license: name: Apache 2.0 url: https://www.hostfully.com/ version: v3.0.1 servers: - url: https://sandbox-api.hostfully.com security: - JWT-Authentication: [] - Agency-API-key: [] tags: - name: Leads Test Endpoint paths: /api/v3.3/leads-test/group-booking: post: tags: - Leads Test Endpoint summary: Create a new group booking lead description: Creates given group booking lead in the system. Api client creating lead will have access to that lead's personal and confidential information. operationId: createGroupBookingLead requestBody: content: application/json: schema: $ref: '#/components/schemas/LeadApiV3GroupBookingCreationDto' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/LeadApiV3GroupBookingDto' /api/v3.3/leads-test/group-booking/{groupUid}/cancel: post: tags: - Leads Test Endpoint summary: Cancel group-booking by 'groupUid' description: Cancellation of the entire group booking. The main lead and all the sub leads. operationId: cancelGroupBooking parameters: - name: groupUid in: path required: true schema: type: string responses: '200': description: OK components: schemas: QuoteFeeOverridesApi3Dto: type: object properties: feeId: type: integer format: int32 deprecated: true feeUid: type: string name: type: string amountType: type: string enum: - AMOUNT - TAX amount: type: number taxationRate: type: number scope: type: string enum: - PER_NIGHT - PER_STAY - PER_GUEST_PER_NIGHT - PER_GUEST - PER_PET - PER_PET_PER_NIGHT - PERCENTAGE_OF_TOTAL - PERCENTAGE_OF_RENT type: type: string enum: - CLEANING - EARLY_ARRIVAL - LATE_DEPARTURE - PET - TAX - CUSTOM isOptional: type: boolean netPrice: type: number enabled: type: boolean removed: type: boolean LeadGuestInformationForCreationApiV3Dto: required: - email type: object properties: firstName: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information lastName: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information address1: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information address2: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information zipCode: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information city: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information state: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information countryCode: type: string description: Replaced with null if api caller has no access to see lead's personal and confidential information enum: - AF - AL - DZ - AS - AD - AO - AI - AG - AN - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BR - BN - BG - BF - BI - BQ - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - YT - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FJ - FI - FK - FO - FR - GF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GU - GT - GN - GW - GY - GP - HT - VA - HN - HK - HL - HU - IS - IN - ID - IR - IQ - IE - IL - IT - JM - JP - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LC - LS - LR - LY - LI - LT - LU - MO - MQ - MK - MG - MW - MY - MV - ML - MT - MH - MR - MU - MX - FM - MD - MC - MN - MS - MA - MZ - MM - ME - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - 'NO' - OM - PK - PW - PA - PG - PS - PY - PE - PF - PH - PL - PN - PT - PR - QA - RO - RU - RW - KN - WS - RE - PM - SH - ST - SM - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - ES - LK - SR - SJ - SZ - SE - CH - SY - TC - TW - TJ - TZ - TH - TG - TO - TT - TN - TR - TM - TV - UG - UA - AE - GB - JE - IM - US - UY - UZ - VC - VU - VE - VN - VG - VI - WF - EH - YE - YU - ZM - ZW passportId: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information passportCountryCode: type: string description: Replaced with null if api caller has no access to see lead's personal and confidential information enum: - AF - AL - DZ - AS - AD - AO - AI - AG - AN - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BR - BN - BG - BF - BI - BQ - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - YT - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FJ - FI - FK - FO - FR - GF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GU - GT - GN - GW - GY - GP - HT - VA - HN - HK - HL - HU - IS - IN - ID - IR - IQ - IE - IL - IT - JM - JP - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LC - LS - LR - LY - LI - LT - LU - MO - MQ - MK - MG - MW - MY - MV - ML - MT - MH - MR - MU - MX - FM - MD - MC - MN - MS - MA - MZ - MM - ME - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - 'NO' - OM - PK - PW - PA - PG - PS - PY - PE - PF - PH - PL - PN - PT - PR - QA - RO - RU - RW - KN - WS - RE - PM - SH - ST - SM - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - ES - LK - SR - SJ - SZ - SE - CH - SY - TC - TW - TJ - TZ - TH - TG - TO - TT - TN - TR - TM - TV - UG - UA - AE - GB - JE - IM - US - UY - UZ - VC - VU - VE - VN - VG - VI - WF - EH - YE - YU - ZM - ZW adultCount: type: integer description: In case it is not supplied, the default value of 1 will be assumed format: int32 childrenCount: type: integer description: In case it is not supplied, the default value of 0 will be assumed format: int32 petCount: type: integer description: In case it is not supplied, the default value of 0 will be assumed format: int32 infantCount: type: integer description: In case it is not supplied, the default value of 0 will be assumed format: int32 riskScore: maximum: 100 minimum: 0 type: integer description: Declared departure datetime in property's timezone by the guest on the pre arrival form. format: int32 email: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information secondaryEmail: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information phoneNumber: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information cellPhoneNumber: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information flightNumber: type: string reasonForTrip: type: string willHaveParty: type: boolean willHaveVisit: type: boolean preferredCurrency: type: string enum: - USD - EUR - GBP - CAD - JPY - INR - MYR - AUD - KES - MXN - HKD - NZD - CHF - BRL - CLP - COP - PEN - ARS - UYU - VEF - CNY - THB - KRW - IDR - SGD - TWD - AED - ZAR - CZK - DKK - DOP - SEK - BGN - ILS - NOK - RON - RUB - PHP - VND - HUF - IKR - PLN - PYG - TRY - GTQ - VUV - JOD - SAR - EGP - TTD - MAD - CVE - BBD - AWG - BHD - NONE preferredLocale: type: object properties: language: type: string displayName: type: string country: type: string variant: type: string script: type: string unicodeLocaleAttributes: uniqueItems: true type: array items: type: string unicodeLocaleKeys: uniqueItems: true type: array items: type: string displayLanguage: type: string displayScript: type: string displayCountry: type: string displayVariant: type: string extensionKeys: uniqueItems: true type: array items: type: string iso3Language: type: string iso3Country: type: string arrivalLocalDateTime: type: string example: '2026-04-20T11:52:36' departureLocalDateTime: type: string example: '2026-04-20T11:52:36' description: Ignored for BLOCK type of a lead LeadApiV3AssigneeDto: type: object properties: uid: type: string type: type: string enum: - EMPLOYEE - OWNER - AGENT PriceOverridesApi3Dto: required: - netPrice type: object properties: netPrice: type: number taxationRate: type: number LeadApiV3SubLeadCreationDto: required: - propertyUid - status - unitUid type: object properties: propertyUid: type: string unitUid: type: string checkInLocalDate: type: string description: Check in date. Not Specifying Time. format: date checkOutLocalDate: type: string description: Check out date. Not Specifying Time. format: date status: type: string enum: - BLOCKED - NEW - ON_HOLD - CLOSED - PENDING - PENDING_APPROVED - DECLINED - BOOKED - CANCELLED - IGNORED - DUPLICATE - SAMPLE guestInformation: $ref: '#/components/schemas/LeadGuestInformationForCreationApiV3Dto' externalBookingId: type: string description: Ignored for BLOCK type of a lead description: List of sub-leads belonging to the group-booking QuoteOverridesApi3Dto: type: object properties: rent: $ref: '#/components/schemas/QuoteRentOverridesApi3Dto' securityDeposit: type: number fees: $ref: '#/components/schemas/QuoteFeesOverridesApi3Dto' totalPrice: type: number force100PercentPaymentAtReservation: type: boolean LeadApiV3GroupBookingDto: type: object properties: uid: type: string propertyUid: type: string agencyUid: type: string checkInZonedDateTime: type: string description: Check in datetime with the timezone offset format: date-time checkOutZonedDateTime: type: string description: Check out datetime with the timezone offset format: date-time checkInLocalDateTime: type: string example: '2026-04-20T11:52:36' checkOutLocalDateTime: type: string example: '2026-04-20T11:52:36' status: type: string enum: - BLOCKED - NEW - ON_HOLD - CLOSED - PENDING - PENDING_APPROVED - DECLINED - BOOKED - CANCELLED - IGNORED - DUPLICATE - SAMPLE type: type: string enum: - INQUIRY - BOOKING_REQUEST - BLOCK - BOOKING source: type: string enum: - HOSTFULLY_UI - HOSTFULLY_DBS - HOSTFULLY_API - HOSTFULLY_LINKED - HOSTFULLY_OWNER_PORTAL - HOSTFULLY_ICAL - DIRECT_HOMETOGO - DIRECT_BOOKINGDOTCOM - DIRECT_AIRBNB - DIRECT_VRBO - DIRECT_HVMI - DIRECT_REDAWNING - DIRECT_GOOGLE channel: type: string description: Represents the list of known channels in Lead API V3. This enum may be extended with additional values in API versions.API Clients must gracefully handle unmapped or unexpected entries with fallback or defaulting strategy to ensure safe behavior enum: - HOSTFULLY - AIRBNB - BOOKING_COM - VRBO - HVMB - GOOGLE - FIND_RENTALS - FLATAWAY - GOLIGHTLY - HOMADS - TRIP_ADVISOR - VACAYMYMAY - STAYMENTITY - GETAWAYGOGO - EVERYSTAY - REDAWNING - MISTERBNB - WHIMSTAY - KOPA - OWNERDIRECT - B0ARDING - TRAVELSTAYTION - BNBFINDER - LODGELOVERS - LAKE - MINISTAYS - TRAMONA - NEXTPAX - RENTALS_UNITED - HOUFY - VRASIO - STAYNEARN - BLUEGROUND - ANYSTAY - STAY - CREWDOGS bookedUtcDateTime: type: string example: '2026-04-20T11:52:36' externalBookingId: type: string notes: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information extraNotes: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information assignee: $ref: '#/components/schemas/LeadApiV3AssigneeDto' metadata: $ref: '#/components/schemas/LeadMetadataApiV3Dto' guestInformation: $ref: '#/components/schemas/LeadGuestInformationForCreationApiV3Dto' referrer: type: string mainLeadUid: type: string groupUid: type: string hotelUid: type: string description: Returned in case property is Multi-Unit (Hotel), ignored for master/sub properties subLeads: type: array items: $ref: '#/components/schemas/LeadApiV3GroupBookingSubLeadDto' LeadMetadataApiV3Dto: type: object properties: createdUtcDateTime: type: string example: '2026-04-20T11:52:36' updatedUtcDateTime: type: string example: '2026-04-20T11:52:36' creationCircumstances: type: string description: Optional type defining what process created the lead. enum: - IMPORTED_FROM_CSV - CREATED_WHILE_CHANNEL_ON - IMPORTED_UPON_CHANNEL_CONNECTION LeadApiV3GroupBookingSubLeadDto: type: object properties: uid: type: string description: Identifier generated for each lead. In UID format groupUid: type: string description: Identifier in UID format for indexing the group-booking, uses UID of the main lead propertyUid: type: string description: UID of UNIT when master/sub. UID of the UNIT_TYPE when hotel agencyUid: type: string unitUid: type: string description: Identifier of the chosen Unit (SUB UNIT UID for master/sub properties, and UNIT for hotels). UID format checkInZonedDateTime: type: string description: Check in datetime with the timezone offset format: date-time checkOutZonedDateTime: type: string description: Check out datetime with the timezone offset format: date-time checkInLocalDateTime: type: string example: '2026-04-20T11:52:36' checkOutLocalDateTime: type: string example: '2026-04-20T11:52:36' externalBookingId: type: string notes: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information extraNotes: type: string description: Replaced with 'HIDDEN' if api caller has no access to see lead's personal and confidential information assignee: $ref: '#/components/schemas/LeadApiV3AssigneeDto' guestInformation: $ref: '#/components/schemas/LeadGuestInformationForCreationApiV3Dto' description: Returns the reservation data of the sub-lead, along with its respective groupUid QuoteRentOverridesApi3Dto: type: object properties: rentBaseNetPrice: type: number rentNetPrice: type: number extraGuestsNetPrice: type: number taxationRate: type: number taxAmount: type: number extraGuestsBaseNetPrice: type: number LeadApiV3GroupBookingCreationDto: required: - agencyUid - propertyUid - status - subLeads type: object properties: propertyUid: type: string agencyUid: type: string checkInLocalDateTime: type: string example: '2026-04-20T11:52:36' checkOutLocalDateTime: type: string example: '2026-04-20T11:52:36' checkInLocalDate: type: string description: Check in date. For specifying time, use checkInLocalDateTime. format: date checkOutLocalDate: type: string description: Check out date. For specifying time, use checkOutLocalDateTime. format: date status: type: string enum: - BLOCKED - NEW - ON_HOLD - CLOSED - PENDING - PENDING_APPROVED - DECLINED - BOOKED - CANCELLED - IGNORED - DUPLICATE - SAMPLE guestInformation: $ref: '#/components/schemas/LeadGuestInformationForCreationApiV3Dto' bookedUtcDateTime: type: string example: '2026-04-20T11:52:36' externalBookingId: type: string description: Ignored for BLOCK type of a lead notes: type: string extraNotes: type: string quoteOverrides: $ref: '#/components/schemas/QuoteOverridesApi3Dto' referrer: type: string channel: type: string description: Represents the list of known channels in Lead API V3. This enum may be extended with additional values in API versions.API Clients must gracefully handle unmapped or unexpected entries with fallback or defaulting strategy to ensure safe behavior enum: - HOSTFULLY - AIRBNB - BOOKING_COM - VRBO - HVMB - GOOGLE - FIND_RENTALS - FLATAWAY - GOLIGHTLY - HOMADS - TRIP_ADVISOR - VACAYMYMAY - STAYMENTITY - GETAWAYGOGO - EVERYSTAY - REDAWNING - MISTERBNB - WHIMSTAY - KOPA - OWNERDIRECT - B0ARDING - TRAVELSTAYTION - BNBFINDER - LODGELOVERS - LAKE - MINISTAYS - TRAMONA - NEXTPAX - RENTALS_UNITED - HOUFY - VRASIO - STAYNEARN - BLUEGROUND - ANYSTAY - STAY - CREWDOGS hotelUid: type: string description: In case hotelUid is not supplied, group-booking will assume that request is a master/sub property reservation assigneeUid: type: string description: Identifier of user assigned to lead in UID format subLeads: type: array description: List of sub-leads belonging to the group-booking items: $ref: '#/components/schemas/LeadApiV3SubLeadCreationDto' description: Requires propertyUid and hotelUid for a hotel reservation, send hotelUid null for master/sub reservation QuoteFeesOverridesApi3Dto: type: object properties: cleaningFee: $ref: '#/components/schemas/PriceOverridesApi3Dto' otherFees: type: array items: $ref: '#/components/schemas/QuoteFeeOverridesApi3Dto' securitySchemes: JWT-Authentication: type: apiKey description: OAuth Access Token name: Authorization in: header Agency-API-key: type: apiKey description: API Key name: X-HOSTFULLY-APIKEY in: header externalDocs: description: Hostfully Documentation url: https://dev.hostfully.com/v3.0/reference x-readme: explorer-enabled: true proxy-enabled: true