{
  "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)"
      }
    ]
  }
}