API reference - Calls and recordings

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 external calls

GET /v1/calls

Requires calls.read. Workspace returns one call with its complete journey. A single-inbox connection receives only that inbox's interactions, grouped into one call entry with the same parent ID, including transfers to and from other inboxes. Other inboxes' interaction details are excluded. Legacy multi-inbox grants still require every associated inbox to be allowed and current. Internal calls are excluded. The date filters apply to the view's start_time. This endpoint includes ongoing calls. An inbox's end_time can be set while the parent call continues in another inbox; call.completed events and setup samples wait for the entire parent call to end.

Parameters

Name	Location	Required	Description and constraints
`inbox_id`	query	No	Filter to activity involving this accessible inbox. Does not change connection access or the returned resource projection. 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]*$"
`direction`	query	No	Filter by external call or message direction. Type: string enum: ["inbound","outbound"]
`limit`	query	No	Type: integer default: 50 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
`created_after`	query	No	Inclusive lower time bound. Applies to start_time for calls and created_at for contacts/messages. Include a time zone. Type: string format: "date-time"
`created_before`	query	No	Exclusive upper time bound; must be later than created_after. Include a time zone. Type: string format: "date-time"
`order`	query	No	oldest (the default) pages forward by ascending stable ID. newest returns the most recent records first and next_cursor continues with older records. The order is bound to the cursor. Type: string default: "oldest" enum: ["oldest","newest"]
`include_labels`	query	No	true adds display labels to each record: inbox_labels for accessible inboxes, contacts matched to external numbers (requires contacts.read; omitted otherwise) and, for messages, sender_name. The default record shape and webhook payloads are unchanged. Type: string default: "false" enum: ["true","false"]
`external_number`	query	No	Exact external party phone number. Combines with the date filters. Type: string pattern: "^\+[1-9][0-9]{1,14}$"
`outcome`	query	No	Only calls whose reported outcome (the outcome field of each returned call, for this connection's view) equals this value. unknown includes calls still in progress. Type: string enum: ["completed","missed","voicemail","transferred","forwarded","failed","unknown"]
`employee_id`	query	No	Only calls with a visible interaction this employee answered. 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]*$"
`sentiment`	query	No	Only calls with at least one accessible recording carrying this saved sentiment. Calls without saved sentiment never match; null is not neutral. Type: string enum: ["positive","negative","neutral","mixed"]
`unhandled_only`	query	No	true returns calls currently marked unhandled and needing follow-up in an accessible inbox, or in inbox_id when provided. This filter does not expand the connection's access. Type: string enum: ["true","false"]

Responses

200 — Calls in the requested order (ascending stable ID by default).

application/json

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

Models: Page, Call.

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.

Get one accessible external call

GET /v1/calls/{id}

Requires calls.read. The ID is the parent Waveline record ID, not a provider call SID. The response uses the same connection-specific projection as listCalls and call.completed events.

Parameters

Name	Location	Required	Description and constraints
`id`	path	Yes	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]*$"
`include_labels`	query	No	true adds display labels to each record: inbox_labels for accessible inboxes, contacts matched to external numbers (requires contacts.read; omitted otherwise) and, for messages, sender_name. The default record shape and webhook payloads are unchanged. Type: string default: "false" enum: ["true","false"]

Responses

200 — Call metadata and outcome derived from persisted call facts. Recordings, summaries, and transcripts are not included.

application/json

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

Models: Call, RateLimit.

Error format, status codes, and retry guidance.

List recording metadata for a call

GET /v1/calls/{id}/recordings

Requires calls.read. Missing and inaccessible parent resources return 404.

Parameters

Name	Location	Required	Description and constraints
`id`	path	Yes	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]*$"
`limit`	query	No	Type: integer default: 50 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

Responses

200 — Page ordered by ascending ID.

application/json

type: object
required:
  - data
  - next_cursor
properties:
  data:
    type: array
    items:
      $ref: '#/components/schemas/Recording'
  next_cursor:
    type:
      - string
      - 'null'

Models: Recording.

Error format, status codes, and retry guidance.

Get recording metadata

GET /v1/recordings/{id}

Requires calls.read. The parent call must be accessible, and every inbox on the recording must be currently authorized. A partial inbox call view does not grant access to recordings covering other inboxes.

Parameters

Name	Location	Required	Description and constraints
`id`	path	Yes	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 — Authorized result.

application/json

type: object
required:
  - data
properties:
  data:
    $ref: '#/components/schemas/Recording'

Models: Recording.

Error format, status codes, and retry guidance.

Get recording transcript

GET /v1/recordings/{id}/transcript

Requires calls.read. Returns saved text only; does not start or charge for transcription/summary generation. Text may be null while unavailable.

Parameters

Name	Location	Required	Description and constraints
`id`	path	Yes	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 — Authorized result.

application/json

type: object
required:
  - data
properties:
  data:
    $ref: '#/components/schemas/MediaText'

Models: MediaText.

Error format, status codes, and retry guidance.

Get recording summary

GET /v1/recordings/{id}/summary

Requires calls.read. Returns saved text only; does not start or charge for transcription/summary generation. Text may be null while unavailable.

Parameters

Name	Location	Required	Description and constraints
`id`	path	Yes	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 — Authorized result.

application/json

type: object
required:
  - data
properties:
  data:
    $ref: '#/components/schemas/MediaText'

Models: MediaText.

Error format, status codes, and retry guidance.

Get recording download

GET /v1/recordings/{id}/download

Requires calls.read. The private URL expires after five minutes; revocation blocks new URLs but cannot invalidate an already issued URL before expiry.

Parameters

Name	Location	Required	Description and constraints
`id`	path	Yes	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 — Authorized result.

application/json

type: object
required:
  - data
properties:
  data:
    $ref: '#/components/schemas/MediaDownload'

Models: MediaDownload.

Error format, status codes, and retry guidance.