OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens Telco Data Usage Reports API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Number lookup usage reports
name: Telco Data Usage Reports
paths:
/legacy/reporting/usage_reports/number_lookup:
get:
description: Retrieve a paginated list of telco data usage reports
operationId: getTelcoDataUsageReports
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TelcoDataGetUsageReportsResponse'
description: Successfully retrieved telco data usage reports
'400':
description: Invalid request parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'500':
description: Internal server error
security:
- bearerAuth: []
summary: List telco data usage reports
tags:
- Telco Data Usage Reports
x-latency-category: responsive
post:
description: Submit a new telco data usage report
operationId: submitTelcoDataUsageReport
requestBody:
content:
'*/*':
schema:
$ref: '#/components/schemas/TelcoDataUsageRequest'
description: Telco data usage request data
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TelcoDataPostUsageReportResponse'
description: Successfully submitted telco data usage report
'400':
description: Invalid request parameters
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Unprocessable entity
'500':
description: Internal server error
security:
- bearerAuth: []
summary: Submit telco data usage report
tags:
- Telco Data Usage Reports
x-latency-category: responsive
/legacy/reporting/usage_reports/number_lookup/{id}:
delete:
description: Delete a specific telco data usage report by its ID
operationId: deleteTelcoDataUsageReport
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
description: Successfully deleted telco data usage report
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Report not found
'500':
description: Internal server error
security:
- bearerAuth: []
summary: Delete telco data usage report
tags:
- Telco Data Usage Reports
x-latency-category: responsive
get:
description: Retrieve a specific telco data usage report by its ID
operationId: getTelcoDataUsageReport
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TelcoDataGetUsageReportByIdResponse'
description: Successfully retrieved telco data usage report
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Report not found
'500':
description: Internal server error
security:
- bearerAuth: []
summary: Get telco data usage report by ID
tags:
- Telco Data Usage Reports
x-latency-category: responsive
components:
schemas:
TelcoDataPostUsageReportResponse:
properties:
data:
$ref: '#/components/schemas/TelcoDataUsageReportResponse'
type: object
TelcoDataGetUsageReportByIdResponse:
properties:
data:
$ref: '#/components/schemas/TelcoDataUsageReportResponse'
type: object
TelcoDataUsageRecord:
properties:
aggregations:
description: List of aggregations by lookup type
items:
$ref: '#/components/schemas/TelcoDataAggregation'
type: array
record_type:
description: Record type identifier
example: TelcoDataUsageRecord
type: string
user_id:
description: User ID
example: d37bdd47-f301-42ec-b2ad-5a0465bfb632
format: uuid
type: string
type: object
TelcoDataUsageReportResponse:
description: Telco data usage report response
properties:
aggregation_type:
description: Type of aggregation used in the report
example: ALL
type: string
created_at:
description: Timestamp when the report was created
example: '2025-12-02T20:20:57.196925Z'
format: date-time
type: string
end_date:
description: End date of the report period
example: '2025-12-01'
format: date
type: string
id:
description: Unique identifier for the report
example: 9783f4d7-0bfc-427a-9d6b-bc659ad16e5b
format: uuid
type: string
managed_accounts:
description: List of managed account IDs included in the report
example: []
items:
type: string
type: array
record_type:
description: Record type identifier
example: TelcoDataUsageReport
type: string
report_url:
description: URL to download the complete report
example: https://portal-cdrs-usage.s3.amazonaws.com/telco_data_usage_report_2025-12-02.csv
type: string
result:
description: Array of usage records
items:
$ref: '#/components/schemas/TelcoDataUsageRecord'
type: array
start_date:
description: Start date of the report period
example: '2025-11-01'
format: date
type: string
status:
description: Current status of the report
example: COMPLETE
type: string
updated_at:
description: Timestamp when the report was last updated
example: '2025-12-02T20:21:08.237091Z'
format: date-time
type: string
type: object
TelcoDataGetUsageReportsResponse:
properties:
data:
items:
$ref: '#/components/schemas/TelcoDataUsageReportResponse'
type: array
meta:
$ref: '#/components/schemas/standard_PaginationMeta'
type: object
standard_PaginationMeta:
properties:
page_number:
example: 2
format: int32
type: integer
page_size:
example: 25
format: int32
type: integer
total_pages:
example: 3
format: int32
type: integer
total_results:
example: 55
format: int32
type: integer
type: object
TelcoDataUsageRequest:
properties:
aggregationType:
description: Type of aggregation for the report
enum:
- ALL
- BY_ORGANIZATION_MEMBER
example: ALL
type: string
endDate:
description: End date for the usage report
example: '2025-02-10'
format: date
type: string
managedAccounts:
description: List of managed accounts to include in the report
example:
- f47ac10b-58cc-4372-a567-0e02b2c3d479
- 6ba7b810-9dad-11d1-80b4-00c04fd430c8
items:
type: string
type: array
startDate:
description: Start date for the usage report
example: '2025-02-10'
format: date
type: string
type: object
TelcoDataAggregation:
properties:
currency:
description: Currency code
example: USD
type: string
total_cost:
description: Total cost for this aggregation
example: 0.009
type: number
total_dips:
description: Total number of lookups performed
example: 3
type: integer
type:
description: Type of telco data lookup
example: CNAM
type: string
type: object
securitySchemes:
bearerAuth:
scheme: bearer
type: http
branded-calling_bearerAuth:
description: API key passed as a Bearer token in the Authorization header
scheme: bearer
type: http
oauthClientAuth:
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
flows:
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
clientCredentials:
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
type: oauth2
outbound-voice-profiles_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
pronunciation-dicts_bearerAuth:
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
scheme: bearer
type: http
stored-payment-transactions_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http