AI Voice Agent API Doc

TABLE OF CONTENTS

Get Call Request Result Schema
Get Call Request Result Example
Get Call Request Result Response Schema
Get Call Request Result Response Example

Get Call Request Result Schema

To access the outcome of a call request, this endpoint allows clients to retrieve the corresponding results. It is recommended to begin retrieving call request results starting five days prior to the guest’s check-in date, ensuring data availability and optimal performance of your integration. As with any standard GET request, the request does not include a body. The CallRequestID to be retrieved must be specified directly in the URL path.

HTTP URL: https://{domainName}/api/v1/call-request/{call-request-id}/result

Get Call Request Result Example

https://{domainName}/api/v1/call-request/{77b2c4d5e6f7g890}/result

Get Call Request Result Response Schema

When you send a GET request to retrieve the call request result, DerbySoft will return a response that includes the current status of the request.

If the call request has been processed, the response will include a result object containing the call outcome details.
If the call request is still pending or not yet processed, the result object will be omitted, and only the status field will be returned.

HTTP Response

Level	Field Name	Num.Occ.	DataType	Format	Description	Example
1	success	1	boolean	True False	True: call request was successfully retrieve False: call request cannot be retrieve	TRUE
1	callRequestId	1	String	16 Char	Unique identifier for a call request provided by Derbysoft when the call request was submitted.	66a1b2c3d4e5f678
1	callRequestStatus	1	Enum	CANCELLED IN_PROGRESS PENDING_TO_CALL COMPLETED	CANCELLED: Call request was cancelled by your system. IN_PROGRESS: AI has started calling but has not yet reached a confirmed outcome. PENDING_TO_CALL: Call has not been initiate and will be schedule once meet expected criteria. COMPLETED: Call was completed.	processed
1	result	0...1	object		Object used to share call result when the status is completed	-
2	callType	1	Enum	AUTHORIZATION_ VERIFICATION BOOKING_VERIFICATION	authorizationVerification: type of call to verify booking details as well as authorization form. bookingVerification: type of call to verify booking details.	AUTHORIZATION_ VERIFICATION
2	callStatus	1	Enum	ERROR_OUTCOME SUCCESS UNABLE_TO_COMPLETE	errorOutcome = the call completed technically, but the conversation with the agent on the other side was determined to not be successful. IE the agent couldn't find the booking, 4 digits are not matching etc. success = the final call attempt was able to verify the call request data. unableToComplete: The agent wasn't able to verify the call data or unable to get an email to resend the the booking or payment instructions if needed	success
2	statusReasonCategory	0...1	Enum	AUTH_FORM_NOT_FOUND DATA_MISMATCH RESERVATION_NOT_FOUND RESERVATION_CANCELLED INCORRECT_TELEPHONE_NUMBER INVALID_TELEPHONE_NUMBER NO_ANSWER	Status reason category will be returned when the result status is error Outcome or unable to complete. Auth form not found: Hotel was not able to verify the payment form. Data missmatch: some of the call data provided is not matching hotel record Reservation not found: hotel does not have a reservation for the guest and or booking reference Reservation cancelled: hotel cannot confirm the authorization verification as the reservation is cancelled. Incorrect telephone number: given telephone number doesn't correspond to the hotel Invalid telephone number: given telephone number is technically invalid No answer: given telephone number is not answer	Data missmatch
2	statusReason	0..1	string	Max 200 char	Error outcome or unable to complete reason summary	Check out date do not match
2	outcomeSummary	1	string	Max 200 char	Success call outcome reason summarize in a sentence	Confirmed Authorization but Not Last Four. Confirmed All Details. Could not find Reservation.
2	outcomeDetails	1	string	Max 500 char	Success call summary	The hotel could not find the reservation for Leo Messi for the May 30 arrival. The hotel confirmed receipt of the credit card authorization for Leo Messi and verified the last four digits as 1234.
2	actionRequired	0...1	object		When the call status is error_outcome, this field will be used to provide instructions for completing the verification successfully.
3	action	1	Enum	RESEND_RESERVATION RESEND_PAYMENT_ AUTHORIZATION	Action needed to provide the information needed by the hotel to complete the verification.	resend_authorization_via_email
3	email	0...1	String	Min 6 Char Max 254 Char	Email associate with the hotel to resend required action.	hotelbarcelona@gmail.com
3	fax	0...1	String	Only digits after the + Min 6 Max 20	Fax number associated with the property to resend required action. Including country code	+34932952800
2	dialTime	0...1	data-time	YYYY-MM-DDTHH:MM:SSZ	Timestamp of when last call to the hotel was done under full ISO 8601 UTC	2025-06-03T10:10:00Z
2	recipientName	0..1	String	100 Char	Name of the person who attended the call	Sam
2	hotelConfirmationId	0..1	String	50 Char	Booking confirmation ID provided by the hotel	123456A

Get Call Request Result Response Example

Call request result Success example - Authorization Verification

{
  "success": true, 
  "callRequestId": "77b2c4d5e6f7g890",
  "callRequetStatus": "COMPLETED",
  "result": {
        "callType": "AUTHORIZATION_VERIFICATION",
        "callStatus": "SUCCESS"
        "outcomeSummary": "Authorization verification successfully",
        "outcomeDetails": "Credit card authorization was verified with the hotel. Guest Iago Aspas's Visa ending in 1234 was confirmed for charges including room, tax, and parking.",
        "actionRequired":  {
                "action": ""
                "email": ""
                "fax": ""
             },
        "dialTime": "2025-06-03T10:10:00Z"
  }
}

Call request result error outcome example - Authorization Verification

{
  "success": true, 
  "callRequestId": "bcpFuj1ipoBKLz5G",
  "callRequetStatus": "COMPLETED",
  "result": {
        "callType": "AUTHORIZATION_VERIFICATION",
        "callStatus": "ERROR_OUTCOME",
        "statusReasonCategory": "RESERVATION_NOT_FOUND",   
        "statusReason": "Front desk agent didnt find a reservation for Leo Messi or with the Booking ID, for that reason payment couldnt be verify", 
         "actionRequired":  {
                "action": ""
                "email": ""
                "fax": ""
             },
        "dialTime": "2025-06-03T10:10:00Z"
  }
}

Call request result pending to call example

{
  "success": true, 
  "callRequestId": "bcpFuj1ipoBKLz5G",
  "callRequetStatus": "PENDING_TO_CALL",
}

Call request result Error example

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Can not found the corresponding call request base on the call request id."
  }
}

Get Call Request Result API