Developers
OpenAPI 3.0 specification
Machine-readable contract for Integrations & CTI. Import into Postman, Insomnia, Swagger UI, or generate clients.
Try it in Postman
Import URL: /developers/openapi.json on your VoxLink frontend host (same origin as this site). Set X-VoxLink-Api-Key on Integrations routes after connecting a CRM in Admin → Integrations.
Covered paths
/api/integrations/inboundPOST
/api/integrations/lookupGET
/api/integrations/cti/click-to-dialPOST
/api/integrations/cti/screen-popGET
/api/integrations/connectPOST
/api/integrationsGET · PUT
/api/integrations/test-webhookPOST
/api/auth/loginPOST
Raw specification
{
"openapi": "3.0.3",
"info": {
"title": "VoxLink Integrations & CTI API",
"version": "2.0.0",
"description": "CRM-agnostic screen-pop, webhooks, and CTI click-to-dial for Salesforce, HubSpot, Zendesk, Genesys, Avaya, and custom systems. Authenticate with X-VoxLink-Api-Key (company integration key) or a Bearer JWT.",
"contact": {
"name": "ECONX GROUP",
"url": "https://econxgroup.com",
"email": "info@econxgroup.com"
}
},
"servers": [
{
"url": "https://voxlink-econxgroup-production.up.railway.app",
"description": "VoxLink API"
}
],
"tags": [
{
"name": "Integrations",
"description": "CRM push, lookup, webhooks, connect"
},
{
"name": "CTI",
"description": "Click-to-dial and screen-pop for CTI middleware"
},
{
"name": "Auth",
"description": "Agent login for JWT"
}
],
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-VoxLink-Api-Key"
},
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"schemas": {
"ScreenPop": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"phone": {
"type": "string"
},
"email": {
"type": "string"
},
"vip_tier": {
"type": "string",
"nullable": true
},
"crm": {
"type": "object",
"additionalProperties": true
},
"external_system": {
"type": "string"
},
"external_id": {
"type": "string"
}
}
},
"InboundPush": {
"type": "object",
"required": [
"phone_number",
"data"
],
"properties": {
"phone_number": {
"type": "string",
"example": "+15551234567"
},
"external_system": {
"type": "string",
"example": "salesforce"
},
"external_id": {
"type": "string",
"example": "001xx000003DGbE"
},
"tier": {
"type": "string",
"example": "gold"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"account_number": {
"type": "string"
},
"open_tickets": {
"type": "integer"
}
},
"additionalProperties": true
}
}
},
"ClickToDial": {
"type": "object",
"required": [
"phone_number"
],
"properties": {
"phone_number": {
"type": "string"
},
"agent_code": {
"type": "string",
"description": "Optional preferred agent seat"
},
"agent_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"description": "VoxLink contacts.id (UUID). Non-UUID CRM ids are treated as external_id."
},
"campaign_id": {
"type": "string",
"format": "uuid"
},
"external_id": {
"type": "string",
"description": "CRM/CTI record id (Salesforce 001…, HubSpot vid, etc.)",
"example": "001xx000003DGbE"
},
"screen_pop": {
"$ref": "#/components/schemas/ScreenPop"
},
"metadata": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"paths": {
"/api/integrations/inbound": {
"post": {
"tags": [
"Integrations"
],
"summary": "Push customer cache for screen-pop",
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InboundPush"
}
}
}
},
"responses": {
"200": {
"description": "Cache upserted"
},
"401": {
"description": "Invalid API key"
}
}
}
},
"/api/integrations/lookup": {
"get": {
"tags": [
"Integrations"
],
"summary": "Lookup screen-pop by phone (JWT)",
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"name": "phone",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "found + screen_pop"
}
}
}
},
"/api/integrations/cti/click-to-dial": {
"post": {
"tags": [
"CTI"
],
"summary": "Start outbound dial from CRM / CTI softphone button",
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClickToDial"
}
}
}
},
"responses": {
"201": {
"description": "Dial started"
},
"503": {
"description": "No Ready agent"
}
}
}
},
"/api/integrations/cti/screen-pop": {
"get": {
"tags": [
"CTI"
],
"summary": "CTI middleware pulls screen-pop payload",
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
],
"parameters": [
{
"name": "phone",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "found + screen_pop"
}
}
}
},
"/api/integrations/connect": {
"post": {
"tags": [
"Integrations"
],
"summary": "Connect a CRM provider or CTI connector (admin JWT)",
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"crm_provider": {
"type": "string",
"enum": [
"salesforce",
"hubspot",
"zendesk",
"freshdesk",
"dynamics",
"pipedrive",
"zoho",
"intercom",
"servicenow",
"custom"
]
},
"cti_connector": {
"type": "string",
"enum": [
"genesys",
"avaya",
"cisco",
"five9",
"nice",
"talkdesk",
"none"
]
},
"webhook_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Connected; may return one-time api_key"
}
}
}
},
"/api/integrations": {
"get": {
"tags": [
"Integrations"
],
"summary": "Get integration settings + provider catalogs",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "integration, status, providers, cti_connectors, modes"
}
}
},
"put": {
"tags": [
"Integrations"
],
"summary": "Update webhook URL, mode, CRM, CTI, rotate API key",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Saved"
}
}
}
},
"/api/integrations/test-webhook": {
"post": {
"tags": [
"Integrations"
],
"summary": "Ping configured webhook_url",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "success / skipped / fail"
}
}
}
},
"/api/auth/login": {
"post": {
"tags": [
"Auth"
],
"summary": "Login with agent_code + password → JWT",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"password"
],
"properties": {
"agent_code": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string"
},
"company_slug": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "token + agent"
}
}
}
}
},
"x-voxlink": {
"webhook_events": [
"call_started",
"call_answered",
"disposition",
"cti_click_to_dial",
"integration_test"
],
"webhook_headers": [
"X-VoxLink-Event",
"X-VoxLink-Company",
"X-VoxLink-Key-Prefix",
"X-VoxLink-Signature"
],
"crm_providers": [
{
"id": "salesforce",
"name": "Salesforce"
},
{
"id": "hubspot",
"name": "HubSpot"
},
{
"id": "zendesk",
"name": "Zendesk"
},
{
"id": "freshdesk",
"name": "Freshdesk"
},
{
"id": "dynamics",
"name": "Microsoft Dynamics 365"
},
{
"id": "pipedrive",
"name": "Pipedrive"
},
{
"id": "zoho",
"name": "Zoho CRM"
},
{
"id": "intercom",
"name": "Intercom"
},
{
"id": "servicenow",
"name": "ServiceNow"
},
{
"id": "custom",
"name": "Custom / proprietary CRM"
}
],
"cti_connectors": [
{
"id": "genesys",
"name": "Genesys Cloud"
},
{
"id": "avaya",
"name": "Avaya Aura / AES"
},
{
"id": "cisco",
"name": "Cisco Finesse / UCCE"
},
{
"id": "five9",
"name": "Five9"
},
{
"id": "nice",
"name": "NICE CXone"
},
{
"id": "talkdesk",
"name": "Talkdesk"
},
{
"id": "none",
"name": "None (VoxLink softphone only)"
}
]
}
}