Number KPIs

Track telephone number allocation, utilisation, and distribution across your platform. These KPIs provide crucial insights for capacity planning and number type analysis.

Available KPIs

Number Summary

Returns total number counts along with customer allocation statistics.

Endpoint

GET /backend/kpi/numbers/

Example Request

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Example Response

[
  {
    "number_customer_count": 2150,
    "number_count": 5847
  }
]

Numbers by Status

Groups numbers by their current operational status.

Endpoint

GET /backend/kpi/numbers/byStatus/

Example Request

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/byStatus/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Example Response

[
  {
    "number_status": "Active",
    "number_customer_count": 2050,
    "number_count": 5234
  },
  {
    "number_status": "Suspended",
    "number_customer_count": 45,
    "number_count": 85
  },
  {
    "number_status": "Dropped",
    "number_customer_count": 0,
    "number_count": 528
  }
]

Numbers by Dealer

Groups numbers by dealer for inventory tracking.

Endpoint

GET /backend/kpi/numbers/byDealer/

Example Request

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/byDealer/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Example Response

[
  {
    "number_dealer": "DEALER01",
    "number_customer_count": 750,
    "number_count": 1850
  },
  {
    "number_dealer": "DEALER02",
    "number_customer_count": 500,
    "number_count": 1250
  },
  {
    "number_dealer": "DIRECT",
    "number_customer_count": 900,
    "number_count": 2747
  }
]

Numbers by Type

Categorises numbers by their type (geographic, non-geographic, mobile, etc.).

Endpoint

GET /backend/kpi/numbers/byType/

Example Request

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/byType/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Example Response

[
  {
    "number_type": "Geographic",
    "number_customer_count": 1500,
    "number_count": 3500
  },
  {
    "number_type": "Non-Geographic",
    "number_customer_count": 850,
    "number_count": 1847
  },
  {
    "number_type": "Mobile",
    "number_customer_count": 200,
    "number_count": 500
  }
]

Number Growth and Churn

Shows numbers added (createdByPeriod) or dropped (droppedByPeriod) over time. Use the interval parameter to choose the bucket size (day, week, month, quarter, year; defaults to month), and add further dimensions with groupBy if you want the series split by type or dealer.

Endpoint

GET /backend/kpi/numbers/createdByPeriod/
GET /backend/kpi/numbers/droppedByPeriod/

Example Request

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/droppedByPeriod/?interval=month&groupBy=type" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Example Response

[
  {
    "number_period": "2026-05",
    "number_type": "Geographic",
    "number_customer_count": 12,
    "number_count": 31
  },
  {
    "number_period": "2026-06",
    "number_type": "Geographic",
    "number_customer_count": 9,
    "number_count": 24
  }
]

Note

Growth and churn series record each number’s most recent creation or drop. A number that was dropped and later reinstated only appears in the period of its latest change.

Numbers Sold by Period

Groups numbers by their Date Sold, the date recorded against the number rather than the date it was created on the platform. Use it for sales reporting, where the question is when a number was sold rather than when it was set up.

Endpoint

GET /backend/kpi/numbers/soldByPeriod/

Example Request

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/soldByPeriod/?interval=month&groupBy=dealer" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Numbers with no Date Sold are left out of this series entirely, so its total can be lower than createdByPeriod over the same range. Where you want every number, group on createdByPeriod instead.

This is a different question from droppedByPeriod, which uses the activity stamp recorded when the number was dropped rather than an operator-chosen date.

Filtering Options

Refine your results using these filter parameters:

Parameter	Type	Description	Example
active	boolean	Include only active numbers	active=true
excludeDropped	boolean	Exclude dropped numbers (alias for active)	excludeDropped=true
dropped	boolean	Include only dropped numbers	dropped=true
dealerCode	string	Filter by specific dealer code	dealerCode=DEALER01
numberType	string	Filter by number type	numberType=geographic
numberTypeID	integer list	Filter by one or more number type IDs	numberTypeID=3,4
numberTypeGroup	string	Filter by number type group name	numberTypeGroup=Geographic
status	string	Filter by number status name	status=Live
statusID	integer list	Filter by one or more status IDs	statusID=1,2
dealer	string	Filter by dealer name	dealer=Direct
sold	boolean	Include only numbers with a Date Sold	sold=true
minSoldDate	date	Numbers sold on or after this date	minSoldDate=2026-01-01
maxSoldDate	date	Numbers sold on or before this date	maxSoldDate=2026-01-31

Filter Examples

Active Numbers by Type

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/byType/?active=true" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Geographic Numbers Only

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/?numberType=geographic" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Unassigned Numbers

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/?dealerCode=" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Dropped Numbers by Dealer

curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/byDealer/?dropped=true" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Use Cases

Capacity Planning

Monitor number allocation and availability:

# Check overall number availability
curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

# Analyse by number type for specific capacity
curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/byType/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Inventory Management

Track number allocation and availability:

# Overall allocation by type
curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/byType/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

# Active numbers only
curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/?active=true" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Number Type Analysis

Understand distribution and usage patterns:

# All number types
curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/byType/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

# Active non-geographic numbers
curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/?numberType=non_geographic&active=true" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Churn Analysis

Track dropped numbers to identify issues:

# Dropped numbers by type
curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/byType/?dropped=true" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

# All dropped numbers
curl -X GET "https://companyname.callstats.net/backend/kpi/numbers/?dropped=true" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Best Practices

1. Inventory Monitoring - Set alerts for low number availability by type
2. Utilisation Tracking - Monitor the ratio of allocated to available numbers
3. Type Distribution - Ensure balanced inventory across number types based on demand
4. Churn Prevention - Track dropped number patterns to identify and address issues early

Number Types

Common number types in the UK market:

• Geographic - Local area numbers (01/02 ranges)
• Non-Geographic - National rate, freephone, and premium numbers (03/08/09 ranges)
• Mobile - Mobile numbers (07 range)
• Special Services - Short codes and special service numbers

Related KPIs

• Customer KPIs - See customer counts with allocated numbers
• Feature KPIs - Analyse features applied to numbers
• Invoice KPIs - Track revenue from number-related charges