AI Voice Agent API Doc

TABLE OF CONTENTS

Create Call Request Schema
Create Call Request Example
Create Call Request Response Schema
Create Call Request Response Example
- Call Request result success example
- Call Request result error outcome example

The Booking Verification call type allows clients to initiate an AI-driven phone call to a hotel to confirm that a specific booking exists. The agent validates key reservation details such as the guest name, check-in/check-out dates to ensure they match the expected data. This call can be used for both regular overnight bookings and day-use reservations. It helps automate manual confirmation workflows and improves confidence in booking accuracy before guest arrival.

Create Call Request Schema

Your system will use this endpoint to submit new call requests to DerbySoft. To ensure successful processing:

All mandatory fields must be included in the request payload.
The check-in date must be in the future; requests with past check-in dates will be rejected.
Once a valid request is submitted, DerbySoft will begin initiating calls to the hotel starting five days before the check-in date.

Request (METHOD: POST)

Level	Field Name	Num.Occ.	Datatype	Format	Description	Example
1	purpose	1	object		Object used to share call type data specific	-
2	callType	1	Enum	BOOKING_VERIFICATION	authorizationVerification: type of call to verify booking details as well as authorization form	BOOKING_VERIFICATION
2	bookingVerification	1	object		Object use to share data about specific call ty, in this case AUTHORIZATION_VERIFICATION	-
3	toEmail	0..1	string	min 6 char max 254 char	If reservation was delivered via email, to which email was it sent	barcelonaFrontdesk@gmail.com
3	fromEmail	0..1	string	min 6 char max 254 char	If reservation was delivered via email, from which email was it sent	barcelonatravel@gmail.com
3	checkInTime	0..1	time	hh:mm	Time of check in, only for day use bookings	10:00
3	checkOutTime	0..1	time	hh:mm	Time of check out, only for day use bookings	13:00
3	mealPlan	0..1	string	Max 100 char	Meal plan included in the reservation	Room only
3	roomType	0..1	string	Max 100 char	Room type that is booked in the reservation	Single Room
3	prepaidBooking	0..1	Boolean	True False	When true the agent will validate with the hotel the booking is prepaid When false agent will not validate with the hotel the payment status	TRUE
3	requireHotelConfirmationId	0..1	Boolean	True False	When true the AI agent will ask the hotel to provide the hotel confirmation ID as part of the verification process. When false AI agent will not ask for the hotel confirmation ID.
1	recipient	1	object
2	phoneNumber	1	string	“+” followed by digits Min 6 Max 20	Telephone number associated with the property. Including “+” and country code	+34932952800
1	callData	1	object	-	Object used to group generic call data information	-
2	onBehalfOrg	0..1	string	Max 100 char	When provided it will be used by the AI agent that it is calling on behalf of that company. If not provided it will use your company name	Barcelona Travel
2	property	1	object	-	Object used to share Property information	-
3	name	1	string	Max length 200 char	Hotel name	W Barcelona, MGM Grand, Sun Hotel
3	distributorHotelID	0..1	string	Max length TBD	Unique Derbysoft identifiyer for hotel	ABCDE
3	gdsId	0..1	string	Max lenght 20 char	Unique GDS identifiyer for hotel	WH BCN183 WH 45626 WH 101944 WH 3183
3	address	1	object	-	Object used to share address associated with the hotel.	-
4	addressLine1	1	string	Max lenght 200 char	Free-form address details.	Plaça Rosa Del Vents 1
4	addressLine2	0..1	string	Max lenght 200 char	Free-form address details.	Final, Pg. de Joan de Borbó
4	cityName	1	string	Max lenght 100 char	City or town where the hotel is located	Barcelona
4	stateProv	0..1	string	Max lenght 100 char	State or Province name (e.g., Texas).State, province, or region name needed to identify hotel location.
4	countryISO	1	string	Min 2 Max 2	ISO 3166-1 Listing Country code	ES
2	guest	1	object	-	Object used to share guest details for the reservation.	-
3	firstName	1	string	Max lenght 100 char	Given, or first, name of the guest.	Leo
3	lastName	1	string	Max lenght 100 char	Family, or last, name of the guest.	Messi
3	company	0..1	string	Max lenght 200 char	Company name where guest works	FCB Barcelona
2	reservation	1	object	-	Object used to share all reservation details	-
3	hotelConfirmationId	0..1	string	Max lenght 50 char	Unique identifier for the booking in distributor system	012AC983
3	checkIn	1	date	yyyy-mm-dd	Check in date - ISO 8601. Check in date cannot be in the past.	2026/5/13
	checkOut	1	date	yyyy-mm-dd	Check out date - ISO 8601. Check out date cannot be in the past and should be greater than check in date	2026/5/23

Create Call Request Example

Call Request success example with all verification parameters

{
    "purpose": {
        "callType": "BOOKING_VERIFICATION",
        "bookingVerification": {
            "deliveryMethod": "email",
            "toEmail": "barcelona@travel.com",
            "fromEmail": "reservations@barcelona.com",
            "checkOutTime": "",
            "checkInTime": ""
            "mealPlan": "Bed & Breakfast"
            "RoomType": "Superior"
            "prepaidBooking": "False"
            "requireHotelConfirmationId": "False"
        }
    },
    "recipient": {
        "phoneNumber": "+34981816978"
    },
    "callData": {
        "onBehalfOrg": "Barcelona Luxury Travel",
        "property": {
            "name": "Hilton Diagonal Mar Barcelona",
            "distributorHotelID": "",
            "gdsId": "",
            "address": {
                "addressLine1": "Pg. del Taulat, 262, 08019",
                "addressLine2": "",
                "cityName": "Barcelona",
                "stateProv": "",
                "countryISO": "ES"
            }
        },
        "guest": {
            "firstName": "Michel",
            "lastName": "Jordan",
            "company": "Chicago Bulls"
        },
        "reservation": {
            "hotelConfirmationId": "1593687456",
            "checkIn": "2026-07-16",
            "checkOut": "2026-07-17"
        }
    }
}

Call Request (day use) success example with all verification parameters

{
    "purpose": {
        "callType": "BOOKING_VERIFICATION",
        "bookingVerification": {
            "deliveryMethod": "email",
            "toEmail": "barcelona@travel.com",
            "fromEmail": "reservations@barcelona.com",
            "checkOutTime": "11:00",
            "checkInTime": "15:00"
            "mealPlan": "Room Only"
            "RoomType": "Standard"
            "prepaidBooking": "False"
            "requireHotelConfirmationId": "False"
        }
    },
    "recipient": {
        "phoneNumber": "+34981816978"
    },
    "callData": {
        "onBehalfOrg": "Barcelona Luxury Travel",
        "property": {
            "name": "Hilton Diagonal Mar Barcelona",
            "distributorHotelID": "",
            "gdsId": "",
            "address": {
                "addressLine1": "Pg. del Taulat, 262, 08019",
                "addressLine2": "",
                "cityName": "Barcelona",
                "stateProv": "",
                "countryISO": "ES"
            }
        },
        "guest": {
            "firstName": "Michel",
            "lastName": "Jordan",
            "company": "Chicago Bulls"
        },
        "reservation": {
            "hotelConfirmationId": "1593687456",
            "checkIn": "2026-07-16",
            "checkOut": "2026-07-16"
        }
    }
}

Call Request success example with only Room

{
    "purpose": {
        "callType": "BOOKING_VERIFICATION",
        "bookingVerification": {
            "deliveryMethod": "",
            "toEmail": "",
            "fromEmail": "",
            "checkOutTime": "",
            "checkInTime": ""
            "mealPlan": ""
            "RoomType": "Suite"
            "prepaidBooking": ""
        }
    },
    "recipient": {
        "phoneNumber": "+34981816978"
    },
    "callData": {
        "onBehalfOrg": "Barcelona Luxury Travel",
        "property": {
            "name": "Hilton Diagonal Mar Barcelona",
            "distributorHotelID": "",
            "gdsId": "",
            "address": {
                "addressLine1": "Pg. del Taulat, 262, 08019",
                "addressLine2": "",
                "cityName": "Barcelona",
                "stateProv": "",
                "countryISO": "ES"
            }
        },
        "guest": {
            "firstName": "Michel",
            "lastName": "Jordan",
            "company": "Chicago Bulls"
        },
        "reservation": {
            "hotelConfirmationId": "1593687456",
            "checkIn": "2026-07-16",
            "checkOut": "2026-07-17"
        }
    }
}

Call Request (day use) success example with only Time

{
    "purpose": {
        "callType": "BOOKING_VERIFICATION",
        "bookingVerification": {
            "deliveryMethod": "",
            "toEmail": "",
            "fromEmail": "",
            "checkOutTime": "15:00",
            "checkInTime": "18:30"
            "mealPlan": ""
            "RoomType": ""
            "prepaidBooking": ""
        }
    },
    "recipient": {
        "phoneNumber": "+34981816978"
    },
    "callData": {
        "onBehalfOrg": "Barcelona Luxury Travel",
        "property": {
            "name": "Hilton Diagonal Mar Barcelona",
            "distributorHotelID": "",
            "gdsId": "",
            "address": {
                "addressLine1": "Pg. del Taulat, 262, 08019",
                "addressLine2": "",
                "cityName": "Barcelona",
                "stateProv": "",
                "countryISO": "ES"
            }
        },
        "guest": {
            "firstName": "Michel",
            "lastName": "Jordan",
            "company": "Chicago Bulls"
        },
        "reservation": {
            "hotelConfirmationId": "1593687456",
            "checkIn": "2026-07-16",
            "checkOut": "2026-07-17"
        }
    }
}

Call Request error example missing mandatory field firstName

{
    "purpose": {
        "callType": "BOOKING_VERIFICATION",
        "bookingVerification": {
            "deliveryMethod": "email",
            "toEmail": "barcelona@travel.com",
            "fromEmail": "reservations@barcelona.com",
            "checkOutTime": "11:00",
            "checkInTime": "15:00"
            "mealPlan": "Room Only"
            "RoomType": "Standard"
        }
    },
    "recipient": {
        "phoneNumber": "+34981816978"
    },
    "callData": {
        "onBehalfOrg": "Barcelona Luxury Travel",
        "property": {
            "name": "Hilton Diagonal Mar Barcelona",
            "distributorHotelID": "",
            "gdsId": "",
            "address": {
                "addressLine1": "Pg. del Taulat, 262, 08019",
                "addressLine2": "",
                "cityName": "Barcelona",
                "stateProv": "",
                "countryISO": "ES"
            }
        },
        "guest": {
            "firstName": "",
            "lastName": "Jordan",
            "company": "Chicago Bulls"
        },
        "reservation": {
            "hotelConfirmationId": "1593687456",
            "checkIn": "2026-07-16",
            "checkOut": "2026-07-16"
        }
    }
}

Create Call Request Response Schema

Once a call request is submitted, DerbySoft's system will initiate a response to your system indicating whether the request was successfully parsed or if an error occurred.

If the request is successful, the response will include a Call Request ID.
This ID is essential and must be securely stored on your side.
You will need this ID for any future operations related to the request, such as checking the call status or canceling the call request.

HTTP Response

Level	Field Name	Num.Occ.	Datatype	Format	Description	Example
1	success	1	boolean	True False	True: call request was created successfully in our system False: call request was not created in our system	TRUE
1	callRequestId	0..1	String	16 Char	Unique identifier for a call request, it must be stored to be able to request call status or cancel the call request	66a1b2c3d4e5f678
1	error	0..1	object	-	Object used for error description.	-
2	code	1	String	100	Short error description	BAD_REQUEST
2	message	1	String	500	Long error description	"Invalid request: call type cannot be empty"

Create Call Request Response Example

Call Request creation success example

{
  "success": true, 
  "callRequestId": "66a1b2c3d4e5f678" 
}

Call Request creation error example

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST", 
    "message": "Invalid request: call type cannot be empty"
  }
}