Refers

Refer records are generated when you are using the <Refer> verb.Those records are hosted with CPaaS and are available for you to retrieve.The Refer records list resource represents a set of account’s Refer records.

The Refers API endpoint supports JSON output only.

Refer Resource URI

/2012-04-24/Accounts/{AccountSid}/Refers/{ReferSid}

Resource Properties

Property Description

Property	Description
api_version	The API version in use during the recording.
sid	A string that uniquely identifies this record.
date_created	The date this record was created.
account_sid	The unique id of the Account that created this record.
org_sid	The unique id of the Organization which belongs to the Account.
call_sid	The unique id of the call during which transferring of the call was made.
from	The phone number or identifier that originated the transfer of the call.
to	The phone number or identifier that will be the recipient of this transferred call.
call_status	The status of the transferring procedure. This provides the application with the status of the new call (based on SIP NOTIFY messages) created in a response to the REFER. If the REFER fails or the endpoint does not send any NOTIFY requests, this parameter will be omitted.
refer_sip_response_code	The SIP response code received in response to the REFER request sent by CPaaS to the SIP endpoint.
notify_sip_response_code	This is the last SIP response code received on the referred leg, as determined by examining the SIP NOTIFY messages. E.g. If the SIP endpoint initiated a new call but received a SIP 404 response due to the target not being found, this parameter will be set to "404". If the REFER fails or the endpoint does not send any NOTIFY requests, this parameter will be omitted.
uri	The URI for this Refer record, relative to `https://$DOMAIN/restcomm`.

api_version

The API version in use during the recording.

sid

A string that uniquely identifies this record.

date_created

The date this record was created.

account_sid

The unique id of the Account that created this record.

org_sid

The unique id of the Organization which belongs to the Account.

call_sid

The unique id of the call during which transferring of the call was made.

from

The phone number or identifier that originated the transfer of the call.

The phone number or identifier that will be the recipient of this transferred call.

call_status

The status of the transferring procedure. This provides the application with the status of the new call (based on SIP NOTIFY messages) created in a response to the REFER. If the REFER fails or the endpoint does not send any NOTIFY requests, this parameter will be omitted.

refer_sip_response_code

The SIP response code received in response to the REFER request sent by CPaaS to the SIP endpoint.

notify_sip_response_code

This is the last SIP response code received on the referred leg, as determined by examining the SIP NOTIFY messages. E.g. If the SIP endpoint initiated a new call but received a SIP 404 response due to the target not being found, this parameter will be set to "404". If the REFER fails or the endpoint does not send any NOTIFY requests, this parameter will be omitted.

uri

The URI for this Refer record, relative to https://$DOMAIN/restcomm.

Supported Operations

HTTP GET

Returns the representation of a Refer resource, including the properties above.

Listing a Single Refer Record

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers/RFc377eb0e657e415383de087ab38797db  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers/RFc377eb0e657e415383de087ab38797db',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers/RFc377eb0e657e415383de087ab38797db',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers/RFc377eb0e657e415383de087ab38797db");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

The response will be similar to the one below.

{
  "sid": "RFc377eb0e657e415383de087ab38797db",
  "date_created": "2021-03-09T12:03:00.787Z",
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "org_sid": "ORfe81fe8a3d5f4d5391e901db0bf5755d",
  "call_sid": "IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49",
  "to": "sip:alice@company.com",
  "from": "sip:bob@company.com",
  "call_status": "in-progress",
  "refer_sip_response_code": "123",
  "notify_sip_response_code": "456"
}

Refers List Resource

Refers List Resource URI

/2012-04-24/Accounts/{AccountSid}/Refers

Supported Operations

HTTP GET

Returns the list representation of all the Refer records resources for a given account, including the properties above.

Getting a List of Refer Records

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

The response will be similar to the one below.

{"page":0,"num_pages":0,"page_size":50,"total":34,"start":"0","end":"34","uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refer","first_page_uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers?Page=0&PageSize=50","previous_page_uri":"null","next_page_uri":"null","last_page_uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers?Page=0&PageSize=50","refers":
    [
        {
          "sid": "RFc377eb0e657e415383de087ab38797db",
          "date_created": "2021-03-09T12:03:00.787Z",
          "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "org_sid": "ORfe81fe8a3d5f4d5391e901db0bf5755d",
          "call_sid": "IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49",
          "to": "sip:alice@company.com",
          "from": "sip:bob@company.com",
          "call_status": "in-progress",
          "refer_sip_response_code": "123",
          "notify_sip_response_code": "456"
        },
        ...

    ]
}

List Filter

HTTP GET

The following GET query string parameters allow you to limit the list returned.

Parameters are case-sensitive.

Request Parameters

Parameter	Description
ReferTo	Only show refer records to this SIP Address (allows full text search).
ReferFrom	Only show refer records from this SIP Address (allows full text search).
ReferCallStatus	Only show refer records with this status. May be in-progress, canceled, failed, busy, or no-answer.
DateCreated	Only show refer records that started on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32). If you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in the UTC timezone. A 400 response will be returned if the syntax is invalid.
CallSid	Only show refer records spawned by the call with this Sid.

Parameter

Description

ReferTo

Only show refer records to this SIP Address (allows full text search).

ReferFrom

Only show refer records from this SIP Address (allows full text search).

ReferCallStatus

Only show refer records with this status. May be in-progress, canceled, failed, busy, or no-answer.

DateCreated

Only show refer records that started on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32). If you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in the UTC timezone. A 400 response will be returned if the syntax is invalid.

CallSid

Only show refer records spawned by the call with this Sid.

Filtering by CallSid Parameter

The example below will return Refer records that have been initiated from this CallSid.

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers?CallSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers?CallSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers?CallSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers?CallSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

The result will be similar to the one below

{"page":0,"num_pages":0,"page_size":50,"total":34,"start":"0","end":"34","uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refer","first_page_uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers?Page=0&PageSize=50","previous_page_uri":"null","next_page_uri":"null","last_page_uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Refers?Page=0&PageSize=50","refers":
    [
        {
          "sid": "RFc377eb0e657e415383de087ab38797db",
          "date_created": "2021-03-09T12:03:00.787Z",
          "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "org_sid": "ORfe81fe8a3d5f4d5391e901db0bf5755d",
          "call_sid": "IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49",
          "to": "sip:alice@company.com",
          "from": "sip:bob@company.com",
          "call_status": "in-progress",
          "refer_sip_response_code": "123",
          "notify_sip_response_code": "456"
        },
        ...

    ]
}

Paging Information

The request supports standard paging information.For more details, please visit the Paging Information documentation.