AI Voice Agent API Doc

TABLE OF CONTENTS

Webhook Call Result Notification Schema

DerbySoft provides a webhook notification that automatically delivers the result of a call request to your system once the call process is completed. Instead of retrieving the result through an API request, your system can configure a webhook endpoint to receive the call outcome as soon as it becomes available. When the call request reaches the COMPLETED status in the DerbySoft system, DerbySoft will send an HTTP POST request to the webhook endpoint configured by your system.

The webhook payload contains the call request identifier, the final call request status, and the detailed call outcome information. Client webhook URL must be provided during the onboarding process.
Clients are required to configure two endpoints:

UAT Endpoint
Used during the certification phase to validate the webhook integration before going live.

Production Endpoint
Used to receive call request results once the integration has been approved and moved to production.

Both endpoints must be accessible by DerbySoft in order to deliver webhook notifications successfully.

HTTP Response

Level	Field Name	Num.Occ.	DataType	Format	Description	Example
1	eventId	1	string		Unique identifier for this notification. Use this field for idempotency.	evt_9f3d2c84-7c1a-4b0e-9c6f-2c1b63987365
1	eventType	1	enum	call.request.completed	Notification type. The value is always call.request.completed	call.request.completed
1	occurredAt	1	date-time	yyyy-dd-mmThh:mm:ss:sssZ	Date-Time when the business event occurred, in ISO 8601 UTC format.	2025-06-03T10:15:00Z
1	sentAt	1	date-time	yyyy-dd-mmThh:mm:ss:sssZ	Date-Time Time when the webhook was sent, in ISO 8601 UTC format.	2025-06-03T10:15:03Z
1	data	1	object		Business payload for the completed call result.	-
2	callRequestId	1	String	16 Char	Unique identifier for a call request provided by Derbysoft when the call request was submitted.	66a1b2c3d4e5f678
2	callRequestStatus	1	Enum	COMPLETED	COMPLETED: Call was completed.	COMPLETED
2	result	0...1	object		Object used to share call result when the status is completed	-
3	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
3	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
3	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
3	statusReason	0..1	string	Max 200 char	Error outcome or unable to complete reason summary	Check out date do not match
3	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.
3	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.
3	actionRequired	0...1	object		When the call status is error_outcome, this field could be used to provide instructions for completing the verification successfully.	-
4	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
4	email	0...1	String	Min 6 Char Max 254 Char	Email associate with the hotel to resend required action.	hotelbarcelona@gmail.com
4	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
3	recipientName	0..1	String	100 Char	Name of the person who attended the call	Sam
3	recipientEmail	0..1	String	Min 6 Char Max 254 Char	Email associate with the hotel	hotelbarcelona@gmail.com
3	hotelConfirmationId	0..1	String	50 Char	Booking confirmation ID provided by the hotel	123456A
3	dialTime	1	date-time	yyyy-dd-mmThh:mm:ss:sssZ	Final dial Date-Time for the completed request, in ISO 8601 UTC format.	2025-06-03T10:15:00Z

Webhook Call Result Notification Example (examples to be update base on folder)

Call request result Success example - Booking verification

{
  "eventId": "evt_9f3d2c84-7c1a-4b0e-9c6f-2c1b0d7e4a11",
  "eventType": "call.request.completed",
  "occurredAt": "2025-06-03T10:15:00Z",
  "sentAt": "2025-06-03T10:15:03Z",
  "data": {
    "callRequestId": "L28VVxL77ZCc3SMi",
    "callRequestStatus": "COMPLETED",
    "result": {
        "callStatus": "SUCCESS",
        "outcomeSummary": "The reservation for Sean Carapela was fully verified, and all details matched with confirmation number ABCP05 provided.",
        "outcomeDetails": "The front desk confirmed Sean Carapela’s booking exists for one night from March 7th to March 8th in a Standard room with breakfast, marked as prepaid, and supplied the hotel confirmation ID ABCP05; the agent’s name Maria was recorded, so all mandatory objectives were met.",
        "dialTime": "2026-03-06T16:52:39.000Z",
        "hotelConfirmationId": "ABCP05",
        "callType": "BOOKING_VERIFICATION"
      },
    }
  }

Call request result error outcome example - Invoice collection

{
  "eventId": "evt_9f3d2c84-7c1a-4b0e-9c6f-2c1b637e4po9",
  "eventType": "call.request.completed",
  "occurredAt": "2025-06-03T10:15:00Z",
  "sentAt": "2025-06-03T10:15:03Z",
  "data": {
   "callRequestId": "fggXrou8SZ8Sigo9",
    "callRequestStatus": "COMPLETED",
    "result": {
        "callStatus": "ERROR_OUTCOME",
        "statusReason": "Front desk asked the agent to send invoice request via email and declined to continue the process over the phone, without confirming the reservation or providing an email address.",
        "statusReasonCategory": "REQUEST_INVOICE_VIA_EMAIL",
        "actionRequired": {
            "action": "REQUEST_INVOICE_VIA_EMAIL ",
            "email": "reception@hotel.com",
            "fax": null
        },
        "dialTime": "2026-02-26T08:24:15.000Z",
        "callType": "INVOICE_COLLECTION"
      },
    }
  }

Call request result error outcome example - Authorization payment

{
  "eventId": "evt_9f3d2c84-7c1a-4b0e-9c6f-2c1b63987365",
  "eventType": "call.request.completed",
  "occurredAt": "2025-06-03T10:15:00Z",
  "sentAt": "2025-06-03T10:15:03Z",
  "data": {
    "callRequestId": "YmS1NL4PSiBjSsbJ",
    "callRequestStatus": "COMPLETED",
    "result": {
        "callStatus": "ERROR_OUTCOME",
        "statusReason": "Front desk was unable to locate a reservation for Iago Aspas on all three calls.",
        "statusReasonCategory": "AUTH_FORM_NOT_FOUND",
        "actionRequired": {
            "action": "RESEND_PAYMENT_AUTHORIZATION",
            "email": "barcelona@hotel.com",
            "fax": null
        },
        "dialTime": "2025-12-11T07:22:32.000Z",
        "callType": "AUTHORIZATION_VERIFICATION"
      },
    }
  }

Call request unable to complete - Invoice collection

{
  "eventId": "evt_9f3d2c84-7c1a-4b0e-9c6f-2c1b63769lo4",
  "eventType": "call.request.completed",
  "occurredAt": "2025-06-03T10:15:00Z",
  "sentAt": "2025-06-03T10:15:03Z",
  "data": {
      "callRequestId": "R22xpusFLn9WGdLM",
    "callRequestStatus": "COMPLETED",
    "result": {
        "callStatus": "UNABLE_TO_COMPLETE",
        "statusReason": "The call reached the hotel’s voicemail system and no live agent was available to proceed with the invoice collection steps.",
        "statusReasonCategory": "NO_ANSWER",
        "actionRequired": {
            "action": null,
            "email": null,
            "fax": null
        },
        "dialTime": "2026-03-06T06:51:08.000Z",
        "callType": "INVOICE_COLLECTION"
      },
    }
  }

Webhook Call Result Notification Response Schema

When DerbySoft sends a webhook notification to the client endpoint, the endpoint must return an HTTP response indicating whether the notification was successfully received.

Successful Response

If the notification is received and accepted for processing, the client should return a 2xx HTTP status code.

DerbySoft interprets any 2xx response as a successful delivery and will not retry the notification.

Examples

Status Code	Description
200 OK	Notification received and processed successfully.
202 Accepted	Notification received and will be processed asynchronously.
204 No Content	Notification received successfully with no response body.

Client Errors

If the client returns a 4xx HTTP status code, it indicates that the request cannot be processed due to an issue with the request.

In this case, DerbySoft treats the delivery as failed and typically will not retry the notification.

Examples

Status Code	Description
400 Bad Request	Invalid payload or missing required fields.
401 Unauthorized	Authentication failed or missing credentials.
403 Forbidden	The request is authenticated but not permitted.
404 Not Found	The webhook endpoint does not exist.

Server Errors

If the client returns a 5xx HTTP status code, it indicates a temporary error on the client system.

In this case, DerbySoft may retry the webhook delivery after a delay.

Examples

Status Code	Description
500 Internal Server Error	Unexpected server error.
502 Bad Gateway	Invalid response from upstream server.
503 Service Unavailable	Service temporarily unavailable.
504 Gateway Timeout	Server timeout while processing the request.

Timeout or No Response

If the client endpoint does not respond within the expected timeout period, DerbySoft will treat the delivery as unsuccessful and may retry the notification according to the retry policy.