API Endpoints Reference

This section provides a complete list of all available API endpoints organized by category.

Base URL: https://platform-api.convirza.com/v3 (e.g., https://platform-api.convirza.com/v3/users/list)

Authentication Endpoints

Base Path: /oauth (OAuth Service)

Method	Endpoint	Description
POST	`/oauth/token`	Login and obtain access token
POST	`/oauth/refresh-token`	Refresh expired access token
POST	`/oauth/revoke-token`	Revoke a specific token

Users Management

Base Path: /v3/users

Method	Endpoint	Description	Auth Required
GET	`/users/list`	List users with filtering and pagination	Yes
GET	`/users/:id`	Get user details by ID	Yes
POST	`/users`	Create a new user	Yes
PUT	`/users/:id`	Update user (full update)	Yes
PATCH	`/users/:id`	Update user (partial update)	Yes
DELETE	`/users/:id`	Delete user (soft delete)	Yes

Query Parameters (List):

org_unit_id (optional): Filter by organization unit ID

name (optional): Filter by user name (partial match)

email (optional): Filter by email (partial match)

role_id (optional): Filter by role ID

user_status (optional): Filter by status — active, inactive, deleted

sort_by (optional): Field to sort by

sort_order (optional): Sort direction

limit (optional): Max results to return (1–200)

offset (optional): Number of results to skip (min 0)

Groups Management

Base Path: /v3/groups

Method	Endpoint	Description	Auth Required
GET	`/groups/org-list/:ouid`	Get organization hierarchy list	Yes
GET	`/groups/tree`	Get complete organization tree	Yes
GET	`/groups/list`	List all groups with filtering	Yes
GET	`/groups/:id`	Get group details by ID	Yes
POST	`/groups`	Create a new group	Yes
PUT	`/groups/:id`	Update group (full update)	Yes
PATCH	`/groups/:id`	Update group (partial update)	Yes
DELETE	`/groups/:id`	Delete group (soft delete)	Yes

Query Parameters (List):

org_unit_id (optional): Filter by organization unit ID

group_name (optional): Filter by group name

status (optional): Filter by status — active, inactive, deleted

limit (optional): Max results to return

offset (optional): Number of results to skip

Webhooks Management

Base Path: /v3/webhooks

Method	Endpoint	Description	Auth Required
GET	`/webhooks/list`	List webhooks with filtering	Yes
GET	`/webhooks/:id`	Get webhook details by ID	Yes
POST	`/webhooks`	Create a new webhook subscription	Yes
PUT	`/webhooks/:id`	Update webhook (full update)	Yes
PATCH	`/webhooks/:id`	Update webhook (partial update)	Yes
DELETE	`/webhooks/:id`	Delete webhook	Yes

Query Parameters (List):

org_unit_id (optional): Filter by organization unit ID

webhook_name (optional): Filter by webhook name

filter (optional): General filter string

status (optional): Filter by status — active, inactive, deleted

limit (optional): Max results to return (min 0)

offset (optional): Number of results to skip (min 0)

Media Prompts

Base Path: /v3/media-prompts

Method	Endpoint	Description	Auth Required
POST	`/media-prompts`	Upload audio recording file	Yes
GET	`/media-prompts`	List recordings with optional type filter	Yes
DELETE	`/media-prompts/:id`	Delete recording (soft delete)	Yes

Query Parameters (List):

type (optional): Filter by recording type — prompt, whisper, voicemail, survey

name (optional): Filter by recording name

File Requirements:

Maximum size: 50MB

Formats: wav, mp3, mp4, ogg, webm, m4a, aac, flac

AI Voice Agents

Base Path: /v3/ai-voice-agents

Method	Endpoint	Description	Auth Required
GET	`/ai-voice-agents`	List AI voice agents	Yes
GET	`/ai-voice-agents/:id`	Get voice agent details	Yes
POST	`/ai-voice-agents`	Create new voice agent	Yes
PUT	`/ai-voice-agents/:id`	Update voice agent (full update)	Yes
PATCH	`/ai-voice-agents/:id`	Update voice agent (partial update)	Yes
DELETE	`/ai-voice-agents/:id`	Delete voice agent	Yes

Query Parameters (List):

id (optional): Filter by agent ID (min 1)

org_unit_ids (optional): Filter by one or more organization unit IDs (array)

search (optional): Search by name or keyword

status (optional): Filter by status — active, inactive, deleted

sortBy (optional): Field to sort by (default: created_on)

sortOrder (optional): Sort direction — ASC, DESC

limit (optional): Max results to return (default: 10)

offset (optional): Number of results to skip (default: 0)

SMS Broadcasts

Base Path: /v3

Method	Endpoint	Description	Auth Required
POST	`/broadcast`	Create SMS broadcast campaign	Yes
GET	`/broadcast`	List SMS broadcasts with filtering	Yes
GET	`/broadcast/:broadcast_id`	Get broadcast details and status	Yes
PUT	`/broadcast/:broadcast_id`	Update broadcast (full update)	Yes
PATCH	`/broadcast/:broadcast_id`	Update broadcast (partial update)	Yes
DELETE	`/broadcast/:broadcast_id`	Cancel/delete broadcast	Yes

Query Parameters (List):

broadcast_name (optional): Filter by broadcast name

agent_name (optional): Filter by agent name

status (optional): Filter by status — scheduled, pending, cancelled, sent

start (optional): Start datetime (ISO 8601 UTC, e.g., 2026-01-01T00:00:00.000Z)

end (optional): End datetime (ISO 8601 UTC, e.g., 2026-12-31T23:59:59.000Z)

limit (optional): Max results to return (1–200, default: 100)

offset (optional): Number of results to skip (min 0, default: 0)

Phone Numbers

Base Path: /v3/phone-numbers

Method	Endpoint	Description	Auth Required
GET	`/phone-numbers/search`	Search available phone numbers	Yes
GET	`/phone-numbers/assigned`	Get assigned phone numbers	Yes
GET	`/phone-numbers/provisioned`	Get provisioned phone numbers	Yes
POST	`/phone-numbers/order`	Order new phone number	Yes
DELETE	`/phone-numbers/number`	Release phone number	Yes

Query Parameters (Search):

npa (optional): Area code — 3 digits (e.g., 800)

nxx (optional): Exchange code — 3 digits

ocn (optional): Operating company number — 4 digits

match (optional): Number pattern using _, *, % wildcards (max 20 chars)

rc (optional): Rate center

state (optional): 2-letter state code (e.g., CA)

limit (optional): Max results to return (1–100)

Query Parameters (Assigned / Provisioned):

npa (optional): Area code — 3 digits

nxx (optional): Exchange code — 3 digits

ocn (optional): Operating company number — 4 digits

match (optional): Number pattern using _, *, % wildcards (max 20 chars)

limit (optional): Max results to return (min 1)

Conversations

Calls

Base Path: /v3/conversations/calls

Method	Endpoint	Description	Auth Required
GET	`/conversations/calls`	Get call conversation history	Yes

Query Parameters:

start (optional): Start datetime (ISO 8601 UTC, e.g., 2026-01-01T00:00:00.000Z)

end (optional): End datetime (ISO 8601 UTC, e.g., 2026-12-31T23:59:59.000Z)

org_unit_id (optional): Filter by organization unit ID (min 1)

call_id (optional): Filter by specific call ID (min 1)

campaign_id (optional): Filter by campaign ID (min 1)

provisioned_route_id (optional): Filter by provisioned route ID (min 1)

caller_id (optional): Filter by caller phone number (e.g., +18005551234)

phone_number (optional): Filter by tracking phone number

ring_to (optional): Filter by ring-to number

disposition (optional): Filter by call disposition (array) — ANSWERED, NO ANSWER, BUSY, FAILED, VOICEMAIL, ABANDONED, TRANSFERRED

include (optional): Include related data (array) — tags, comments, custom_sources, call_flow, recordings, transcription

limit (optional): Max results to return (1–200, default: 50)

offset (optional): Number of results to skip (min 0, default: 0)

SMS

Base Path: /v3/conversations/sms

Method	Endpoint	Description	Auth Required
GET	`/conversations/sms`	Get SMS conversation threads	Yes

Query Parameters:

type (optional): Conversation type — close, unassigned, allOpen, assignedToYou

search (optional): Search keyword (max 255 chars)

order (optional): Sort direction — asc, desc

start (optional): Start datetime (ISO 8601 UTC)

end (optional): End datetime (ISO 8601 UTC)

limit (optional): Max results to return (1–200, default: 7)

offset (optional): Number of results to skip (min 0)

Provisioned Routes

Base Path: /v3/provisioned-routes

Method	Endpoint	Description	Auth Required
GET	`/provisioned-routes`	List provisioned routes	Yes
GET	`/provisioned-routes/:provisioned_route_id`	Get route details	Yes
POST	`/provisioned-routes`	Create new route	Yes
PUT	`/provisioned-routes/:id`	Update route (full update)	Yes
PATCH	`/provisioned-routes/:id`	Update route (partial update)	Yes
DELETE	`/provisioned-routes/:provisioned_route_id`	Delete route	Yes

Query Parameters (List):

org_unit_id (optional): Filter by organization unit ID

provisioned_route_name (optional): Filter by route name

provisioned_route_status (optional): Filter by status — active, inactive, referral, deleted, suspended

phone_number (optional): Filter by phone number (digits only)

orderBy (optional): Field to sort by — provisioned_route_name, provisioned_route_status, phone_number

order (optional): Sort direction — ASC, DESC

limit (optional): Max results to return (max 500, default: 100)

offset (optional): Number of results to skip (min 0)

Miscellaneous

Base Path: /v3

Method	Endpoint	Description	Auth Required
GET	`/industry`	Get industry list	Yes
GET	`/ad-source`	Get ad source list	Yes
GET	`/tag/:org_unit_id`	List tags for organization	Yes
POST	`/tag`	Create new tag	Yes
PUT	`/tag`	Update tag	Yes
DELETE	`/tag`	Delete tag(s)	Yes

Query Parameters (Industry):

industry_name (optional): Filter by industry name (partial match)

industry_group (optional): Filter by industry group/category

industry_id (optional): Filter by exact industry ID

Query Parameters (Tag List):

search (optional): Search by tag name (partial match)

tag_type (optional): Filter by type — user, system, all

status (optional): Filter by status — active, inactive (default: active)

sort (optional): Field to sort by — tag_name, call_count

direction (optional): Sort direction — ASC, DESC

limit (optional): Max results to return

offset (optional): Number of results to skip

API Endpoints Reference

Authentication Endpoints#

Users Management#

Groups Management#

Webhooks Management#

Media Prompts#

AI Voice Agents#

SMS Broadcasts#

Phone Numbers#

Conversations#

Calls#

SMS#

Provisioned Routes#

Miscellaneous#

Authentication Endpoints

Users Management

Groups Management

Webhooks Management

Media Prompts

AI Voice Agents

SMS Broadcasts

Phone Numbers

Conversations

Calls

SMS

Provisioned Routes

Miscellaneous