API reference - Phone numbers and analytics

API reference · OpenAPI specification

Endpoint definitions below are generated from the API contract. Request and response blocks describe schemas, not example payloads. required lists mandatory fields; $ref refers to a linked model. Send JSON bodies with Content-Type: application/json unless the endpoint specifies binary content.

List accessible Waveline phone numbers

GET /v1/phone-numbers

Requires phone_numbers.read. Lists the tenant's own inventory within the granted inboxes. Explicit Workspace grants also include unassigned numbers and personal inbox numbers. Deleted numbers and numbers assigned to deleted inboxes are excluded. Reading numbers does not grant sending or number-management permissions. Missing and inaccessible inbox filters return 404.

Parameters

Name	Location	Required	Description and constraints
`limit`	query	No	Number of phone numbers per page; defaults to 20. Type: integer default: 20 minimum: 1 maximum: 100
`cursor`	query	No	Opaque cursor from next_cursor. Reuse the same credentials, endpoint, filters, ordering, and limit. Results may change between requests; pagination does not freeze the dataset. Type: string
`inbox_id`	query	No	Narrow to one inbox within this connection's current access. Stable existing Waveline record ID. Keep it as a string; it may exceed JavaScript's safe integer range. Type: string maxLength: 19 pattern: "^[1-9][0-9]*$"

Responses

200 — Numbers ordered by ascending stable ID. Page size defaults to 20, maximum 100.

application/json

allOf:
  - $ref: '#/components/schemas/Page'
  - properties:
      data:
        type: array
        items:
          $ref: '#/components/schemas/PhoneNumber'

Models: Page, PhoneNumber.

Errors — 400 invalid input, 401 expired/revoked/missing key, 403 scope or access denied, 404 missing/inaccessible, 409 request/state conflict, 413 oversized request or response, 415 wrong content type, 429 rate limited, or 503 unavailable. 429 includes Retry-After. All responses include X-Request-Id.

Error format, status codes, and retry guidance.

Read scoped external call analytics

GET /v1/analytics/calls

Requires analytics.read. Returns external-call metrics for the connection's currently authorized inboxes. unique_calls counts distinct calls within the filtered interval; interaction_count and all *_interactions fields count inbox interactions. A transferred call can have multiple interactions and appear in multiple groups, so do not add group unique-call counts to calculate the report total. Day and hour buckets use UTC; empty buckets are omitted. Ranges are limited to 93 elapsed days, or 31 days for hourly reports. More than 1000 groups returns 413 RESPONSE_TOO_LARGE; narrow the period or inbox. The response contains aggregate metrics, not raw call content or external participant phone numbers.

Parameters

Name	Location	Required	Description and constraints
`start_date`	query	Yes	Inclusive start timestamp with an explicit time zone. Type: string format: "date-time"
`end_date`	query	Yes	Exclusive end timestamp with an explicit time zone; must follow start_date. Type: string format: "date-time"
`inbox_id`	query	No	Narrow to one authorized inbox. Missing and inaccessible inboxes both return 404. Stable existing Waveline record ID. Keep it as a string; it may exceed JavaScript's safe integer range. Type: string maxLength: 19 pattern: "^[1-9][0-9]*$"
`group_by`	query	No	Type: string default: "day" enum: ["day","hour","inbox","phone_number","employee"]
`compare_to`	query	No	previous_period adds a comparison for the equal-length window ending at start_date, with its summary, groups and precomputed summary changes. Type: string enum: ["previous_period"]

Responses

200 — Complete summary and groups for the filtered period. Recent activity may take time to appear.

application/json

type: object
required:
  - data
properties:
  data:
    $ref: '#/components/schemas/CallAnalytics'
  rate_limit:
    $ref: '#/components/schemas/RateLimit'

Models: CallAnalytics, RateLimit.

Error format, status codes, and retry guidance.