Refer Complete

This event is sent to the referCompleteUrl of a call's <Refer> verb when the SIP REFER flow completes.

On success, the call has been torn down — the caller's endpoint is now talking directly to the refer destination and your application no longer has access to the call. The BXML returned from this callback (if any) is ignored.

On failure, the call remains active. The BXML returned from this callback is executed on the call, allowing your application to recover (e.g. play an error message, retry the REFER, or hang up).

Request Parameters

Property	Description
eventType	The event type, value is referComplete.
eventTime	The approximate UTC date and time when the event was generated by the Bandwidth server, in ISO 8601 format. This may not be exactly the time of event execution.
accountId	The user account associated with the call.
applicationId	The id of the application associated with the call.
from	The provided identifier string of the caller used in the from field of the original call.
to	The phone number or SIP URI used in the to field of the original call.
direction	The direction of the call. Either inbound or outbound. The direction of a call never changes.
callId	The call id associated with the event.
callUrl	The URL of the call associated with the event.
startTime	Time the call was started, in ISO 8601 format.
answerTime	Time the call was answered, in ISO 8601 format.
tag	(optional) The tag specified earlier in the call. If no tag was specified or it was previously cleared, this field will not be present.
referCallStatus	The outcome of the REFER operation. Either success or failure.
referSipResponseCode	Integer (optional). The SIP response code returned for the REFER request itself (e.g. 202, 405, 603). Present when a SIP response was received for the REFER.
notifySipResponseCode	Integer (optional). The final SIP response code reported via NOTIFY (message/sipfrag body). Present only when the caller's endpoint sent a final NOTIFY (e.g. 200, 404, 486, 503). Not present on NOTIFY timeout or when REFER was rejected before a subscription was established.

caution

The set of possible SIP response codes depends on the behavior of the caller's endpoint and the refer destination. Your application should handle unexpected values gracefully.

Expected Response

HTTP/1.1 200
Content-Type: application/xml; charset=utf-8

<Response>
    <!-- BXML verbs to process in the call (only executed on failure) -->
</Response>

Examples

Successful REFER

{
    "eventType": "referComplete",
    "eventTime": "2026-04-30T13:20:39.810Z",
    "accountId": "55555555",
    "applicationId": "7fc9698a-b04a-468b-9e8f-91238c0d0086",
    "from": "sip:bob@customer.example.com",
    "to": "sip:support@bw.example.com",
    "direction": "inbound",
    "callId": "c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "callUrl": "https://voice.bandwidth.com/api/v2/accounts/55555555/calls/c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "startTime": "2026-04-30T13:13:34.859Z",
    "answerTime": "2026-04-30T13:13:40.644Z",
    "referCallStatus": "success",
    "referSipResponseCode": 202,
    "notifySipResponseCode": 200
}

Failed REFER — Rejected by Remote (e.g. 405 Method Not Allowed)

{
    "eventType": "referComplete",
    "eventTime": "2026-04-30T13:20:39.810Z",
    "accountId": "55555555",
    "applicationId": "7fc9698a-b04a-468b-9e8f-91238c0d0086",
    "from": "sip:bob@customer.example.com",
    "to": "sip:support@bw.example.com",
    "direction": "inbound",
    "callId": "c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "callUrl": "https://voice.bandwidth.com/api/v2/accounts/55555555/calls/c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "startTime": "2026-04-30T13:13:34.859Z",
    "answerTime": "2026-04-30T13:13:40.644Z",
    "referCallStatus": "failure",
    "referSipResponseCode": 405
}

Failed REFER — Target Unreachable (NOTIFY reports 404)

{
    "eventType": "referComplete",
    "eventTime": "2026-04-30T13:20:39.810Z",
    "accountId": "55555555",
    "applicationId": "7fc9698a-b04a-468b-9e8f-91238c0d0086",
    "from": "sip:bob@customer.example.com",
    "to": "sip:support@bw.example.com",
    "direction": "inbound",
    "callId": "c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "callUrl": "https://voice.bandwidth.com/api/v2/accounts/55555555/calls/c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "startTime": "2026-04-30T13:13:34.859Z",
    "answerTime": "2026-04-30T13:13:40.644Z",
    "referCallStatus": "failure",
    "referSipResponseCode": 202,
    "notifySipResponseCode": 404
}

Failed REFER — NOTIFY Timeout

{
    "eventType": "referComplete",
    "eventTime": "2026-04-30T13:20:39.810Z",
    "accountId": "55555555",
    "applicationId": "7fc9698a-b04a-468b-9e8f-91238c0d0086",
    "from": "sip:bob@customer.example.com",
    "to": "sip:support@bw.example.com",
    "direction": "inbound",
    "callId": "c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "callUrl": "https://voice.bandwidth.com/api/v2/accounts/55555555/calls/c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "startTime": "2026-04-30T13:13:34.859Z",
    "answerTime": "2026-04-30T13:13:40.644Z",
    "referCallStatus": "failure",
    "referSipResponseCode": 202
}