Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Page tools
On this page
Looking for more inspiration?Visit the

Outbound Phone Number Report Resource

Overview

overview page anchor
(information)

Legal notice

Not a HIPAA Eligible Service

Voice Insights Reports API is not a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA.

An Outbound Phone Number Report aggregates Voice Insights metrics for calls placed from a specific phone number handle.

Outbound Phone Number Report Properties

outbound-phone-number-report-properties page anchor
Encoding type:application/json
Schema
Property nameTypeRequiredPIIDescriptionChild properties
handlestring

Optional

PII MTL: 30 days

Outbound phone number handle represented in the report.

totalCallsinteger

Optional

Not PII

Total number of outbound calls made during the report period.

callAnswerScorenumber<float>

Optional

Not PII

Score (0-100) representing how often outbound calls were answered.

callsByDeviceTypeobject

Optional

Not PII

Number of outbound calls placed per device type (voip, mobile, landline, unknown).

Example: {"voip":150,"mobile":300,"landline":100,"unknown":50}
answerRateDeviceTypeobject

Optional

Not PII

Answer rate per device type (voip, mobile, landline, unknown).

Example: {"voip":75,"mobile":80,"landline":70,"unknown":60}
callStatePercentageobject

Optional

Not PII

Percentage of outbound calls by call state (completed, fail, busy, no-answer, canceled).

blockedCallsByCarrierarray[object]

Optional

Not PII

Associated metrics for completed outbound calls which are blocked by respective downstream carriers. Currently only the US carriers such as ATT, T-Mobile and Verizon provide this information.

silentCallsPercentagenumber<float>

Optional

Not PII

Percentage of calls with silence tags over total calls. A silent tag is indicative of a connectivity issue or muted audio.

shortDurationCallsPercentagenumber<float>

Optional

Not PII

Percentage of completed outbound calls under 10 seconds; More than 15% is typically low trust measured.

longDurationCallsPercentagenumber<float>

Optional

Not PII

Percentage of outbound calls lasting 60 seconds or longer.

potentialRobocallsPercentagenumber<float>

Optional

Not PII

Percentage of completed outbound calls to unassigned or unallocated phone numbers.

answeringMachineDetectionobject

Optional

Not PII

Associated answering machine detection enabled calls.

Create Outbound Phone Numbers Report properties

create-outbound-phone-numbers-report-properties page anchor
(information)

Info

A Voice Insights Report will be available for 5 days after it is created.

Property nameTypeRequiredPIIDescriptionChild properties
accountSidSID<AC>

Optional

Not PII

The unique SID identifier of the Account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
reportIdstring

Optional

Not PII

The report identifier as Voice Insights Report TTID.

statusenum<string>

Optional

Not PII

The status of the report.

Possible values:
createdrunningcompleted
requestMetaobject

Optional

Not PII
urlstring<uri>

Optional

Not PII

The URL of this resource.

Create Outbound Phone Number Reports

create-outbound-phone-number-reports page anchor

POST https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound

Request body parameters

request-body-parameters page anchor
Encoding type:application/json
Schema
Property nameTypeRequiredPIIDescriptionChild properties
timeRangeobject

Optional

Not PII
filtersarray[object]

Optional

Not PII
sizeinteger

Optional

Not PII

The number of max available top Phone Numbers to generate.

Default: 1000Minimum: 1Maximum: 6000

The recent 7 days report can be created without any parameters.

Create Outbound Phone Number ReportsLink to code sample: Create Outbound Phone Number Reports
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createOutboundPhoneNumbersReport() {

11
  const outbound = await client.insights.v2.outbound().create();

12


13
  console.log(outbound.accountSid);

14
}

15


16
createOutboundPhoneNumbersReport();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "report_id": "voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av",

4
  "status": "created",

5
  "request_meta": {

6
    "start_time": "2024-11-01T00:00:00Z",

7
    "end_time": "2024-11-07T00:00:00Z",

8
    "filters": []

9
  },

10
  "url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av"

11
}

Generate outbound reports for a specific period by providing the time_range parameter.

Create Outbound Phone Number Reports with Date Time RangeLink to code sample: Create Outbound Phone Number Reports with Date Time Range
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createOutboundPhoneNumbersReport() {

11
  const outbound = await client.insights.v2.outbound().create({

12
    time_range: {

13
      start_datetime: "2024-10-15T00:00:00Z",

14
      end_datetime: "2024-11-07T00:00:00Z",

15
    },

16
  });

17


18
  console.log(outbound.accountSid);

19
}

20


21
createOutboundPhoneNumbersReport();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "report_id": "voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av",

4
  "status": "created",

5
  "request_meta": {

6
    "start_time": "2024-11-01T00:00:00Z",

7
    "end_time": "2024-11-07T00:00:00Z",

8
    "filters": []

9
  },

10
  "url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av"

11
}

Generate a specific number of outbound reports by providing the size parameter.

Create Outbound Phone Number Reports with Specific SizeLink to code sample: Create Outbound Phone Number Reports with Specific Size
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createOutboundPhoneNumbersReport() {

11
  const outbound = await client.insights.v2.outbound().create({

12
    time_range: {

13
      start_datetime: "2024-10-15T00:00:00Z",

14
      end_datetime: "2024-11-07T00:00:00Z",

15
    },

16
    size: 100,

17
  });

18


19
  console.log(outbound.accountSid);

20
}

21


22
createOutboundPhoneNumbersReport();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "report_id": "voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av",

4
  "status": "created",

5
  "request_meta": {

6
    "start_time": "2024-11-01T00:00:00Z",

7
    "end_time": "2024-11-07T00:00:00Z",

8
    "filters": []

9
  },

10
  "url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av"

11
}

Fetch Outbound Phone Number Reports

fetch-outbound-phone-number-reports page anchor

GET https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound/{reportId}

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
reportIdstring
required
Not PII

A unique Report Id.

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
pageSizeinteger<int64>

Optional

Not PII

How many resources to return in each list page.

Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

The page index. This value is simply for client state.

Minimum: 0
pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Fetch Outbound Phone Number ReportsLink to code sample: Fetch Outbound Phone Number Reports
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listOutboundPhoneNumbersReport() {

11
  const outbounds = await client.insights.v2

12
    .outbound("voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av")

13
    .list({ limit: 20 });

14


15
  outbounds.forEach((o) => console.log(o.handle));

16
}

17


18
listOutboundPhoneNumbersReport();

Response

Note about this response
1
{

2
  "meta": {

3
    "page": 0,

4
    "page_size": 50,

5
    "first_page_url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av?PageSize=50&Page=0",

6
    "previous_page_url": null,

7
    "url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Outbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av?PageSize=50&Page=0",

8
    "next_page_url": null,

9
    "key": "reports"

10
  },

11
  "reports": []

12
}