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 Authorization Payment Verification call type extends the booking confirmation process by additionally validating payment authorization. The AI agent contacts the hotel to confirm the reservation and verify that the Virtual Credit Card (VCC) associated with the payment authorization form is correctly attached to the booking. This reduces the risk of payment issues at checking as well improves the guest experience.

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	AUTHORIZATION_VERIFICATION	authorizationVerification: type of call to verify booking details as well as authorization form	AUTHORIZATION_VERIFICATION
2	authorizationVerification	1	object		Object use to share data about specific call ty, in this case AUTHORIZATION_VERIFICATION	-
3	deliveryMethod	0..1	Enum	EMAIL FAX	How the Authentication form was shared with the hotel
3	cardType	0..1	string	Max lenght 50 char	Card type used in the Authentication form.	Visa Mastercard Amex
3	lastFourDigits	0..1	intenger	Min 4 Max 4	Last four digits of the credit card use in the Authentication form	1234
3	allowedCharges	0..1	string	Max lenght 200 char	Which type of charges are covered for the authentication form	Room and taxes only; Room taxes and Parking etc.
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
2	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": "AUTHORIZATION_VERIFICATION",
        "authorizationVerification": {
            "deliveryMethod": "email",
            "cardType": "Visa",
            "lastFourDigits": 1234,
            "allowedCharges": "room,tax,parking"
        }
    },
    "recipient": "+34981811552",
    "callData": {
        "property": {
            "name": "Galicia Paradise",
            "address": {
                "addressLine1": "123 Main Street",
                "addressLine2": "",
                "cityName": "Vigo",
                "stateProv": "",
                "countryISO": "SP"
            }
        },
        "guest": {
            "firstName": "Iago",
            "lastName": "Aspas",
            "company": "Celta de Vigo"
        },
        "reservation": {
            "hotelConfirmationId": "123456",
            "checkIn": "2026-10-05",
            "checkOut": "2026-10-07"
        }
    }
}

Call Request success example with only VCC

{
    "purpose": {
        "callType": "AUTHORIZATION_VERIFICATION",
        "authorizationVerification": {
            "deliveryMethod": "",
            "cardType": "",
            "lastFourDigits": 9468,
            "allowedCharges": ""
        }
    },
    "recipient": "+34981811552",
    "callData": {
        "property": {
            "name": "Barcelona House",
            "address": {
                "addressLine1": "Las ramblas 26",
                "addressLine2": "",
                "cityName": "Barcelona",
                "stateProv": "",
                "countryISO": "SP"
            }
        },
        "guest": {
            "firstName": "Leo",
            "lastName": "Messi",
            "company": ""
        },
        "reservation": {
            "hotelConfirmationId": "987zdf47",
            "checkIn": "2026-05-05",
            "checkOut": "2026-05-07"
        }
    }
}

Call Request success example without payment details

{
    "purpose": {
        "callType": "AUTHORIZATION_VERIFICATION",
        "authorizationVerification": {
            "deliveryMethod": "",
            "cardType": "",
            "lastFourDigits": ,
            "allowedCharges": ""
        }
    },
    "recipient": "+34981811552",
    "callData": {
        "property": {
            "name": "Barcelona House",
            "address": {
                "addressLine1": "Las ramblas 26",
                "addressLine2": "",
                "cityName": "Barcelona",
                "stateProv": "",
                "countryISO": "SP"
            }
        },
        "guest": {
            "firstName": "Lamine",
            "lastName": "Yamal",
            "company": ""
        },
        "reservation": {
            "hotelConfirmationId": "987zdf47",
            "checkIn": "2026-05-05",
            "checkOut": "2026-05-07"
        }
    }
}

Call Request error example missing mandatory field firstName

{
    "purpose": {
        "callType": "AUTHORIZATION_VERIFICATION",
        "authorizationVerification": {
            "deliveryMethod": "email",
            "cardType": "Visa",
            "lastFourDigits": 1234,
            "allowedCharges": "room,tax,parking"
        }
    },
    "recipient": "+34981811552",
    "callData": {
        "property": {
            "name": "Galicia Paradise",
            "address": {
                "addressLine1": "123 Main Street",
                "addressLine2": "",
                "cityName": "Vigo",
                "stateProv": "",
                "countryISO": "SP"
            }
        },
        "guest": {
            "firstName": "",
            "lastName": "Aspas",
            "company": "Celta de Vigo"
        },
        "reservation": {
            "hotelConfirmationId": "123456",
            "checkIn": "2026-10-05",
            "checkOut": "2026-10-07"
        }
    }
}

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"
  }
}