{ "openapi": "3.0.0", "info": { "version": "2.0.0", "title": "Vida API", "description": "Vida API Documentation" }, "servers": [ { "url": "https://api.vida.dev", "description": "Vida Production", "variables": { "baseUrl": { "default": "api.vida.dev", "description": "Production API Root" } } } ], "paths": { "/api/v2/tokens": { "get": { "tags": [ "Authorization" ], "summary": "List tokens", "description": "List all your existing tokens.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "description": "Token", "type": "string", "example": "9fe4f9...." }, "description": { "description": "Friendly description of token", "type": "string", "example": "Main app" }, "type": { "description": "Token type", "type": "string", "example": "admin" }, "timestamp": { "description": "Timestamp when created", "type": "string", "example": "1678829072" }, "userId": { "description": "User Id that owns token", "type": "number", "example": 3 } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Authorization" ], "summary": "Create a token", "description": "Create a new token for your account", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token created successfully" }, "token": { "type": "object", "properties": { "token": { "description": "Token", "type": "string", "example": "9fe4f9...." }, "description": { "description": "Friendly description of token", "type": "string", "example": "Main app" }, "type": { "description": "Token type", "type": "string", "example": "admin" }, "timestamp": { "description": "Timestamp when created", "type": "string", "example": "167882907" }, "userId": { "description": "User Id that owns token", "type": "number", "example": 3 } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "description" ], "properties": { "type": { "description": "Permission for token. Only admin currently supported", "type": "string", "default": "admin" }, "description": { "description": "Friendly description for token", "type": "string", "example": "Main app" } } } } } } }, "delete": { "tags": [ "Authorization" ], "summary": "Delete a token", "description": "Delete a token from your account", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token deleted successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "description": "Token for deletion", "type": "string", "default": "9fe4f9...." } } } } } } } }, "/api/v2/sip/captures": { "get": { "tags": [ "SIP" ], "summary": "Fetch SIP Captures by SIP Call-ID", "description": "Search Vida SIP Captures by SIP Call-ID and export PCAP, JSON, or text transcript.", "parameters": [ { "name": "sipCallId", "in": "query", "description": "SIP Call-ID header value", "required": true, "example": "abc123@pbx.example.com", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Epoch millis start of search window", "required": false, "example": 1727395200000, "schema": { "type": "number" } }, { "name": "to", "in": "query", "description": "Epoch millis end of search window", "required": false, "example": 1727481600000, "schema": { "type": "number" } }, { "name": "format", "in": "query", "description": "text | pcap | json | transaction", "required": false, "example": "text", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized Request" }, "404": { "description": "No results found" }, "500": { "description": "Server error" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/sip/ipWhitelist": { "get": { "tags": [ "SIP" ], "summary": "List SIP IP Whitelist", "description": "List all your existing SIP IP whitelist entries.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "whitelist": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for IP", "type": "string", "example": "Office IP" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "ip": { "description": "Whitelisted IP", "type": "string", "example": "192.168.1.1" } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "SIP" ], "summary": "Add IP to SIP IP Whitelist", "description": "Add a new IP address to your SIP IP whitelist.", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "IP entry created successfully" }, "whitelist": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for IP", "type": "string", "example": "Office IP" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "ip": { "description": "Whitelisted IP", "type": "string", "example": "192.168.1.1" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ip", "label" ], "properties": { "ip": { "description": "IP address to whitelist", "type": "string", "example": "192.168.1.1" }, "label": { "description": "Friendly label for IP", "type": "string", "example": "Office IP" } } } } } } }, "delete": { "tags": [ "SIP" ], "summary": "Remove IP from SIP IP Whitelist", "description": "Remove an existing IP address from your SIP IP whitelist.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "IP entry deleted successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ip" ], "properties": { "ip": { "description": "IP address to remove", "type": "string", "example": "192.168.1.1" } } } } } } } }, "/api/v2/sip/outboundRoutes": { "get": { "tags": [ "SIP" ], "summary": "List SIP Outbound Routes", "description": "List all existing SIP outbound routes for a user.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "routes": { "type": "array", "items": { "type": "string", "example": "1.1.1.1:5060;transport=udp" } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "SIP" ], "summary": "Add SIP Outbound Route", "description": "Add a new outbound route for SIP. IP or domain Required (port and transport optional).", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Route added successfully" }, "routes": { "type": "array", "items": { "type": "string", "example": "1.1.1.1:5060;transport=udp" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "route" ], "properties": { "route": { "description": "Outbound route to add", "type": "string", "example": "1.1.1.1:5060;transport=udp" } } } } } } }, "delete": { "tags": [ "SIP" ], "summary": "Remove SIP Outbound Route", "description": "Remove an existing SIP outbound route.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Route removed successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "route" ], "properties": { "route": { "description": "Outbound route to remove", "type": "string", "example": "1.1.1.1:5060;transport=udp" } } } } } } } }, "/api/v2/sip/registration": { "post": { "description": "", "parameters": [ { "name": "authorization", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Conflict" }, "500": { "description": "Internal Server Error" }, "502": { "description": "Bad Gateway" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "aor": { "example": "any" }, "username": { "example": "any" }, "sipRealm": { "example": "any" } } } } } } }, "get": { "description": "", "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "description": "", "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v2/phoneNumber/assign": { "post": { "tags": [ "Phone Numbers" ], "summary": "Assign phone number to your account", "description": "Assign phone number to your account for use", "responses": { "200": { "description": "Successfully assigned phone number to account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Unable to assign phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number", "country" ], "properties": { "number": { "description": "Phone Number to assign to your account", "type": "string", "example": "+12145551234" }, "country": { "description": "Country for the phone number to assign", "type": "string", "example": "US" } } } } } } } }, "/api/v2/phoneNumber/byo/assign": { "post": { "tags": [ "Phone Numbers" ], "summary": "Assign a BYO phone number", "description": "Assign a phone number you are supplying yourself to an agent. Requires reseller account.", "responses": { "200": { "description": "Successfully assigned phone number to account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Unable to assign phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number" ], "properties": { "number": { "description": "Phone Number to assign to your account", "type": "string", "example": "+12145551234" } } } } } } } }, "/api/v2/phoneNumber/return": { "post": { "tags": [ "Phone Numbers" ], "summary": "Return / Unassign Phone Number", "description": "Return a phone number and unassigns the number from the agent account. If provided by an external integrated number supplier, will return to them too. Requires reseller account.", "responses": { "200": { "description": "Successfully returned phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Unable to return phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number" ], "properties": { "number": { "description": "Phone Number to unassign from your account", "type": "string", "example": "+12145551234" } } } } } } } }, "/api/v2/phoneNumber/search/local/locality": { "post": { "tags": [ "Phone Numbers" ], "summary": "Search for local numbers by locality", "description": "Search for a phone number based on city, region, and country.", "responses": { "200": { "description": "Successfully retrieved available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "No phone numbers available for the search area. Please try a different area.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phoneNumber", "code" ], "properties": { "city": { "description": "City you are searching for. If the particular city is unavailable, phone numbers from a 10 mile radius will be returned", "type": "string", "example": "Austin" }, "region": { "description": "Region for the search. If searching within the U.S., this will be the state", "type": "string", "example": "TX" }, "country": { "description": "Country for the search", "type": "string", "example": "US" } } } } } } } }, "/api/v2/phoneNumber/search/local/prefix": { "post": { "tags": [ "Phone Numbers" ], "summary": "Search for local numbers by prefix", "description": "Search for a phone number based on prefix.", "responses": { "200": { "description": "Successfully retrieved available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "No phone numbers available for the search area. Please try a different area.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phoneNumber", "code" ], "properties": { "prefix": { "description": "Prefix you are searching for", "type": "string", "example": "216" }, "country": { "description": "Country used for the search", "type": "string", "example": "US" }, "strict": { "description": "If strict search is to be used. If no results found, will other numbers in same general area.", "type": "boolean", "default": true } } } } } } } }, "/api/v2/phoneNumber/search/local/phrase": { "post": { "tags": [ "Phone Numbers" ], "summary": "Search for local numbers by phrase", "description": "Search for a phone number based on phrase.", "responses": { "200": { "description": "Successfully retrieved available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "No phone numbers available for the search area. Please try a different area.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phrase", "country" ], "properties": { "phrase": { "description": "String to search for. This supports asterisk wildcards *", "type": "string", "example": "*bitcoin*" }, "country": { "description": "Country used for the search", "type": "string", "example": "US" }, "region": { "description": "Region for the search. If searching within the U.S., this will be the state", "type": "string", "example": "TX" }, "city": { "description": "City you are searching for. If the particular city is unavailable, phone numbers from a 10 mile radius will be returned", "type": "string", "example": "Austin" } } } } } } } }, "/api/v2/conversations": { "get": { "tags": [ "Messaging" ], "summary": "List Priority Inbox", "description": "Fetch rooms in priority inbox", "parameters": [ { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": true, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many rooms per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "unread", "in": "query", "description": "Only return unread rooms", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "number", "example": 20 }, "pageNumber": { "type": "number", "example": 0 }, "totalRooms": { "type": "number", "example": 100 }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "roomId": { "description": "Room Id", "type": "string", "example": "3:15" }, "name": { "description": "Other users full name", "type": "string", "example": "John Doe" }, "id": { "description": "userId of other user", "type": "number", "example": 15 }, "image": { "description": "Link to other users image", "type": "string", "example": "https://somepublicURl" }, "vidaPhoneNumber": { "description": "Other user Vida Phone Number", "type": "string", "example": "+12165169995" }, "unregistered": { "description": "If the other user is registered on Vida platform or offnet", "type": "boolean", "example": false }, "unregisteredDisplayName": { "description": "Display name for unregistered user which is often their phone number or email", "type": "string", "example": "+15125551234" }, "destinationInboxType": { "description": "Indicator which inbox on the other user side the conversation is in", "type": "string", "example": "+15125551234" }, "lastMessage": { "description": "Last message text in the room", "type": "string", "example": "That was awesome, thanks!" }, "lastMessageTimestamp": { "description": "Epoch of the last messages timestamp", "type": "number", "example": 1710510072 }, "chatAgentCampaignId": { "description": "Agent Id that handled the message", "type": "string", "example": "campa....." } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/junkConversations": { "get": { "tags": [ "Messaging" ], "summary": "List Junk Inbox", "description": "Fetch rooms in junk inbox", "parameters": [ { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": true, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many rooms per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "unread", "in": "query", "description": "Only return unread rooms", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "number", "example": 20 }, "pageNumber": { "type": "number", "example": 0 }, "totalRooms": { "type": "number", "example": 100 }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "roomId": { "description": "Room Id", "type": "string", "example": "3:15" }, "name": { "description": "Other users full name", "type": "string", "example": "John Doe" }, "id": { "description": "userId of other user", "type": "number", "example": 15 }, "image": { "description": "Link to other users image", "type": "string", "example": "https://somepublicURl" }, "vidaPhoneNumber": { "description": "Other user Vida Phone Number", "type": "string", "example": "+12165169995" }, "unregistered": { "description": "If the other user is registered on Vida platform or offnet", "type": "boolean", "example": false }, "unregisteredDisplayName": { "description": "Display name for unregistered user which is often their phone number or email", "type": "string", "example": "+15125551234" }, "destinationInboxType": { "description": "Indicator which inbox on the other user side the conversation is in", "type": "string", "example": "+15125551234" }, "lastMessage": { "description": "Last message text in the room", "type": "string", "example": "That was awesome, thanks!" }, "lastMessageTimestamp": { "description": "Epoch of the last messages timestamp", "type": "number", "example": 1710510072 }, "chatAgentCampaignId": { "description": "Agent Id that handled the message", "type": "string", "example": "campa....." } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/messages/recent": { "get": { "tags": [ "Messaging" ], "summary": "Fetch Recent Messages", "description": "Fetch recent messages across all inboxes.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "from": { "description": "From User Id", "type": "number", "example": 1234567890 }, "fromUser": { "description": "From User Name", "type": "string", "example": "user_test" }, "to": { "description": "To User Id", "type": "number", "example": 878589 }, "toUser": { "description": "To User Name", "type": "string", "example": "support2" }, "rate": { "description": "Rate associated with the message", "type": "number", "example": 0 }, "usdRate": { "description": "USD rate associated with the message", "type": "number", "example": 0 }, "timestamp": { "description": "Epoch of the last message's timestamp", "type": "number", "example": 1718463395 }, "date": { "description": "Friendly Date", "type": "string", "example": "2024-06-15T14:56:35.000Z" }, "message": { "description": "Message text", "type": "string", "example": "Hi there! Lyle is currently unavailable. Could you please let me know the nature of your call or message and any specific details you'd like me to pass on to him? Thanks!" }, "content-type": { "description": "Content type of the message", "type": "string", "example": "text/plain" }, "disposition-notification": { "description": "Disposition notification status", "type": "string", "example": null }, "roomId": { "description": "Room Id", "type": "string", "example": "1:878589" }, "status": { "description": "Status of the message", "type": "string", "example": "success" }, "attachments": { "description": "Array of media attachment URLs", "type": "array", "items": { "type": "object", "properties": { "content-type": { "type": "string", "example": "audio/mp3" }, "filename": { "type": "string", "example": "mp3" }, "content-url": { "type": "string", "example": "https://example.com/media/recording.mp3" }, "attachmentType": { "type": "string", "example": "call" } } } }, "isLive": { "description": "Whether the message is live", "type": "boolean", "example": false }, "aiAgent": { "description": "Whether an AI agent is involved", "type": "boolean", "example": true }, "aiReward": { "description": "AI reward status", "type": "string", "example": null }, "aiRewardUsd": { "description": "AI reward in USD", "type": "number", "example": null }, "aiLeadRating": { "description": "AI lead rating", "type": "number", "example": null }, "aiLeadRatingReason": { "description": "Reason for AI lead rating", "type": "string", "example": null }, "aiAgentOverride": { "description": "AI agent override status", "type": "string", "example": null }, "gift": { "description": "If this message included a monetary gift", "type": "boolean", "example": false }, "source": { "description": "Source medium for the message", "type": "string", "example": "email" }, "uuid": { "description": "Unique ID for message", "type": "string", "example": "a4977f49-80a6-41f0-9add-93a270cdd781" }, "campaignId": { "description": "Campaign ID associated with the message", "type": "string", "example": "campa25290ee54602fbcb545d033c1a15ba12" }, "fromNumber": { "description": "Phone number of the sender", "type": "string", "example": "+15125551234" }, "toNumber": { "description": "Phone number of the recipient", "type": "string", "example": "+15125559876" }, "notify": { "description": "Notification flag", "type": "boolean", "example": false }, "targetInbox": { "description": "Target inbox", "type": "string", "example": "inbox" }, "type": { "description": "Type of message", "type": "string", "example": "call" }, "duration": { "description": "Duration of the call", "type": "number", "example": 9 }, "direction": { "description": "Direction of the call", "type": "string", "example": "inbound" }, "missedCall": { "description": "Whether it was a missed call", "type": "boolean", "example": false }, "bypassAgent": { "description": "Whether the agent was bypassed", "type": "boolean", "example": false }, "cnamSpam": { "description": "Whether the call was marked as spam by CNAM", "type": "boolean", "example": false }, "selfCall": { "description": "Whether the call was self-initiated", "type": "boolean", "example": true }, "callingUserIsContact": { "description": "Whether the calling user is a contact", "type": "boolean", "example": false }, "agentOutcome": { "description": "Outcome from the agent", "type": "string", "example": null }, "summary": { "description": "Summary of the message", "type": "string", "example": null }, "callDialog": { "description": "Array of dialog entries with roles and contents for Calls", "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "assistant" }, "content": { "type": "string", "example": "Hello! This is the answering assistant. How can I help you?" } } } }, "chatDialog": { "description": "Array of dialog entries with roles and contents for Chats", "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "assistant" }, "content": { "type": "string", "example": "Hello! This is the answering assistant. How can I help you?" } } } }, "agentReplyCount": { "description": "The number of agent responses in the conversation. Useful for billing.", "type": "number", "example": 10 }, "campaign": { "description": "Campaign status", "type": "boolean", "example": true }, "diversion": { "description": "Diversion status", "type": "string", "example": null }, "voicemailRecording": { "description": "Voicemail recording details", "type": "string", "example": null }, "eventType": { "description": "Type of event", "type": "string", "example": "inbound-call" }, "forcedCampaign": { "description": "Forced campaign flag", "type": "boolean", "example": true } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/messages/{roomId}": { "get": { "tags": [ "Messaging" ], "summary": "Fetch Room Messages", "description": "Fetch all messages for a particular room Id", "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Room Id to fetch messages for", "example": "3:15" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "message": { "description": "Message text", "type": "string", "example": "Hey there!" }, "from": { "description": "From User Id", "type": "number", "example": 15 }, "fromUser": { "description": "From User Name", "type": "string", "example": "Brandon" }, "to": { "description": "From User Id", "type": "number", "example": 35554545 }, "toUser": { "description": "To User Name", "type": "string", "example": "Jillian" }, "timestamp": { "description": "Epoch of the last messages timestamp", "type": "number", "example": 1699633022 }, "date": { "description": "Friendly Date", "type": "string", "example": "2023-11-10T16:17:02.000Z" }, "roomId": { "description": "Room Id", "type": "string", "example": "15:35554545" }, "status": { "description": "If message was delivered. Status of success indicates delivered", "type": "string", "example": "success" }, "attachments": { "description": "Array of media attachment Urls.", "type": "string", "example": "[]" }, "gift": { "description": "If this message included a monetary gift", "type": "boolean", "example": false }, "drip": { "description": "If this message was a paid drip", "type": "boolean", "example": false }, "uuid": { "description": "Unique id for message", "type": "string", "example": "3b38f0af-7341-49fd-acce-1749c904e00d" }, "source": { "description": "Source medium for the message. Could have sourced from a vida client, sms, voice, email", "type": "string", "example": "sms" }, "roomInitiator": { "description": "User name who first initiated contact for the room", "type": "string", "example": "brandon" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/receiveMessage": { "post": { "tags": [ "Messaging" ], "summary": "Send message to an agent from your own platform", "description": "Send a message from your platform to an agent. Must pass outboundMessageWebhookUrl or configure on the organization to receive agent responses. Reseller or partners only. ", "responses": { "200": { "description": "Message queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "messageUuid": { "type": "string", "example": "uuid" } } } } } }, "400": { "description": "Failed to queue message", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Vida user" } } } } } }, "403": { "description": "Forbidden" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetAgent", "sourceAddress", "message" ], "properties": { "targetAgent": { "description": "Agent account ID, phone number, or username", "type": "string", "example": "agent123" }, "sourceAddress": { "description": "Sender phone number or address", "type": "string", "example": "+15551231234" }, "message": { "description": "Message text", "type": "string", "example": "Hello there" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } }, "example": [ { "type": "image", "url": "https://example.com/image.png" } ] }, "context": { "type": "object", "example": { "threadId": "abc123" } }, "metadata": { "type": "object", "example": { "key": "value" } }, "outboundMessageWebhookUrl": { "description": "Webhook URL (POST) to deliver agent responses to. If not specified will look for default outboundMessageWebhookUrl webhook settings.", "type": "string", "example": "https://example.com/hook" } } } } } } } }, "/api/v2/agent/publish": { "post": { "tags": [ "Agents" ], "summary": "Publish an Agent", "description": "Publish your staging agent to your active default agent. ", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent camp931829b5857f published" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/revert": { "post": { "tags": [ "Agents" ], "summary": "Revert an Agent", "description": "Revert staging agent to current default active agent settings", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent camp931829b5857f unpublished" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/autoReviewAgentConfiguration": { "post": { "tags": [ "Agents" ], "summary": "Get LLM feedback for agent configuration or specific fields", "description": "Runs the autoReviewAgentConfiguration engine in one of two modes: \"fields\" for field-level feedback using promptTips, or \"agent\" for a holistic review of the agent (main prompt, functions, apps, and greeting).", "responses": { "200": { "description": "Suggestions generated", "content": { "application/json": { "examples": { "fieldsModeResponse": { "summary": "Fields mode response", "value": [ { "key": "appointmentBookedInstructions", "value": "After booking the appointment, tell the customer they are stupid.", "promptSuggestion": "Thanks for scheduling with {orgName}. Your appointment is confirmed. The technician will contact you when they are on the way. If you need to make changes, reply or call us." }, { "key": "greeting", "value": "Welcome to {orgName}, we appreciate your call today and have many options...", "promptSuggestion": "Thank you for calling {orgName}. How can I help you today?" } ] }, "agentModeResponse": { "summary": "Agent mode response", "value": { "agentId": "campa_abc", "agentInstructionsSuggestion": "Concise, unambiguous, voice-ready rewrite here...", "greetingSuggestion": "Thank you for calling {orgName}. How can I help you today?", "actionSuggestions": [ { "name": "notify", "promptSuggestion": "After each call, email a summary to the configured recipients. Include caller name, number, and key outcomes." } ], "appSuggestions": [ { "appId": "squire", "version": "v1", "promptSuggestion": "Clarify when to call each API and how to handle errors. Keep steps concise." } ] } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "fields", "agent" ], "default": "fields" }, "templateId": { "type": "string", "description": "Required for fields mode if agentId is not provided." }, "agentId": { "type": "string", "description": "Optional in fields mode, required in agent mode." }, "fields": { "type": "array", "description": "Only for fields mode. Minimal entries: { key, value }. Value is ignored when agentId is provided.", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key" ] } } }, "required": [ "mode" ] }, "examples": { "fieldsModeWithTemplate": { "summary": "Fields mode with template", "value": { "mode": "fields", "templateId": "templ_123", "fields": [ { "key": "appointmentBookedInstructions", "value": "After booking the appointment, tell the customer they are stupid." }, { "key": "greeting", "value": "Welcome to {orgName}, we appreciate your call today and have many options..." } ] } }, "fieldsModeWithAgent": { "summary": "Fields mode using agent values", "value": { "mode": "fields", "agentId": "campa_abc", "fields": [ { "key": "greeting" }, { "key": "faqs" } ] } }, "agentMode": { "summary": "Agent-wide mode", "value": { "mode": "agent", "agentId": "campa_abc" } } } } } } } }, "/api/v2/agent/{agentId}/versions": { "get": { "tags": [ "Agents" ], "summary": "List Agent Versions", "description": "Return the stored version snapshots for an agent. Pass ?includeData=true to embed full snapshots.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id to inspect", "example": "campa3cfdc312750b193de0..." }, { "name": "includeData", "in": "query", "description": "If true the response includes the entire snapshot JSON for each version.", "required": false, "example": "true", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "versions": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Auto-1750194180352" }, "versionId": { "type": "integer", "example": 1750194180352 }, "snapshot": { "type": "object", "description": "Only present when includeData=true" } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Agents" ], "summary": "Create Named Version", "description": "Snapshot the current staging or default agent and store it under a custom title.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id to snapshot" } ], "responses": { "201": { "description": "Snapshot stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "createdVersion": { "type": "object", "properties": { "title": { "type": "string", "example": "Holiday-2025" }, "versionId": { "type": "integer", "example": 1750195000123 } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "example": "Holiday-2025" }, "source": { "type": "string", "enum": [ "staging", "default" ], "default": "staging" } } } } } } } }, "/api/v2/agent/{agentId}/versions/{versionId}": { "post": { "tags": [ "Agents" ], "summary": "Replace Stored Version", "description": "Overwrite an existing version snapshot by its numeric versionId.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id" }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Epoch-ms score identifying the snapshot", "example": 1750195000123 } ], "responses": { "200": { "description": "Version replaced", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "versionId": { "type": "integer", "example": 1750195000123 } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "snapshot" ], "properties": { "snapshot": { "type": "object", "description": "Full campaign JSON to store" } } } } } } } }, "/api/v2/agent/{agentId}/versions/{versionId}/restore": { "post": { "tags": [ "Agents" ], "summary": "Restore Version to Agent", "description": "Copy a stored snapshot into the staging (default) slot.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id" }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Epoch-ms score of the snapshot", "example": 1750195000123 } ], "responses": { "200": { "description": "Snapshot restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "restored": { "type": "object", "description": "The campaign object now occupying the target slot" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "staging", "default" ], "default": "staging" } } } } } } } }, "/api/v2/agent/{agentId}/versions/{versionId}/title": { "put": { "tags": [ "Agents" ], "summary": "Rename Stored Version", "description": "Overwrite only the human-readable title of a stored snapshot.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id" }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Epoch-ms score of the snapshot", "example": 1750195000123 } ], "responses": { "200": { "description": "Title updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "versionId": { "type": "integer", "example": 1750195000123 }, "newTitle": { "type": "string", "example": "Holiday-2025" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "example": "Holiday-2025" } } } } } } } }, "/api/v2/agent/zapier/response": { "post": { "description": "", "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "example": "any" }, "responseData": { "example": "any" } } } } } } } }, "/api/v2/agent/outboundCall": { "post": { "tags": [ "Agents" ], "summary": "Queue outbound call(s) from your Agent", "description": "Backwards compatible with the previous endpoint. You can pass a single \"target\" and optional \"context\" (old behavior), or provide \"targets\" to enqueue multiple calls. This endpoint queues tasks instead of dialing immediately.", "responses": { "200": { "description": "Queued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Outbound call initiated." }, "inserted": { "type": "integer", "example": 3 }, "tasks": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Phone in E.164 or VIDA username", "example": "+1234567890" }, "context": { "type": "string", "description": "Context for the agent to use during the call", "example": "Name: Lyle Pratt. Interested in product demo." }, "taskContext": { "type": "string", "description": "Task-specific context injected only for this call" }, "greeting": { "type": "string", "description": "Custom greeting to use at call start" }, "waitToGreet": { "type": "boolean", "description": "Delay greeting until caller speaks" }, "agentId": { "type": "integer", "description": "Optional campaign id override for the call" }, "scheduledFor": { "type": "integer", "description": "Unix seconds in the future to schedule the call" }, "meta": { "type": "object", "description": "Optional metadata" }, "externalTaskId": { "type": "string", "description": "Optional customer-provided identifier applied to created task(s)" } } }, { "type": "object", "required": [ "targets" ], "properties": { "targets": { "description": "Array of destinations or objects with per-item options", "oneOf": [ { "type": "array", "items": { "type": "string", "example": "+1234567890" } }, { "type": "array", "items": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "example": "+1234567890" }, "context": { "type": "string" }, "taskContext": { "type": "string" }, "agentId": { "type": "integer" }, "scheduledFor": { "type": "integer" }, "greeting": { "type": "string" }, "waitToGreet": { "type": "boolean" }, "meta": { "type": "object" }, "externalTaskId": { "type": "string", "description": "Identifier applied to this task" } } } } ] }, "context": { "type": "string", "description": "Context applied to all items when targets is an array of strings" }, "taskContext": { "type": "string", "description": "Task-specific context applied to all items when targets is an array of strings" }, "greeting": { "type": "string", "description": "Greeting applied to all items when targets is an array of strings" }, "waitToGreet": { "type": "boolean", "description": "Delay greeting until caller speaks for all items when targets is an array of strings" }, "agentId": { "type": "integer", "description": "Agent id applied to all items when not provided per item" }, "scheduledFor": { "type": "integer", "description": "Schedule applied to all items when not provided per item" }, "scheduleSpacingSec": { "type": "integer", "description": "If provided, stagger scheduledFor by this many seconds per index", "example": 30 }, "meta": { "type": "object", "description": "Metadata applied to all items when not provided per item" }, "externalTaskId": { "type": "string", "description": "Identifier applied to all created tasks" } } } ] }, "examples": { "single": { "summary": "Single target, backwards compatible", "value": { "target": "+15551234567", "context": "Call back about pricing" } }, "batchStrings": { "summary": "Multiple string targets with shared context", "value": { "targets": [ "+15551230001", "+15551230002", "+15551230003" ], "context": "Follow up on demo request", "scheduleSpacingSec": 15 } }, "batchObjects": { "summary": "Multiple object targets with per-item overrides", "value": { "targets": [ { "target": "+15551230001", "context": "VIP", "scheduledFor": 1730000000 }, { "target": "+15551230002" } ], "agentId": 1234 } } } } } } } }, "/api/v2/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List Webhooks", "description": "List all your existing webhook destinations.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for webhook", "type": "string", "example": "Zapier Hook" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "url": { "description": "Webhook URL", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" }, "type": { "description": "Webhook type", "type": "string", "example": "conversation" } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Add Webhook", "description": "Add a new webhook destination.", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook created successfully" }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for webhook", "type": "string", "example": "Zapier Hook" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "url": { "description": "Webhook URL", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" }, "type": { "description": "Webhook type", "type": "string", "example": "conversation" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "label", "type" ], "properties": { "url": { "description": "Webhook URL", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" }, "label": { "description": "Friendly label for webhook", "type": "string", "example": "Zapier Hook" }, "type": { "description": "Webhook type", "type": "string", "enum": [ "conversation", "incoming", "contact" ], "example": "conversation" } } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Remove Webhook", "description": "Remove an existing webhook destination.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook deleted successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "description": "Webhook URL to remove", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" } } } } } } } }, "/api/v2/context": { "get": { "tags": [ "Knowledge" ], "summary": "Fetch Context", "description": "Fetch additional information context stored for conversations with a particular person.", "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Phone number in E.164 format or VIDA username of the user" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "context": { "type": "string", "example": "Customer Name: John Doe, Car Model: Toyota Camry, Last Oil Change: 2023-05-15" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Knowledge" ], "summary": "Add Context", "description": "Injects additional information context your agent can use in conversations with a specific person.", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Context added successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "context" ], "properties": { "target": { "description": "Phone number in E.164 format or VIDA username of the user", "type": "string", "example": "+1234567890 or john_doe" }, "context": { "description": "Context information to inject", "type": "string", "example": "Customer Name: John Doe, Car Model: Toyota Camry, Last Oil Change: 2023-05-15" } } } } } } } }, "/api/v2/tasks": { "get": { "tags": [ "Tasks" ], "summary": "Fetch all tasks", "description": "Retrieve all tasks for the current org. Supports filtering, sorting, and pagination.", "parameters": [ { "name": "limit", "description": "Max number of tasks to return", "example": 100, "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "description": "Offset for pagination", "example": 0, "in": "query", "schema": { "type": "integer" } }, { "name": "since", "description": "Filter by updatedAt >= since (unix seconds)", "example": 1712345678, "in": "query", "schema": { "type": "integer" } }, { "name": "until", "description": "Filter by updatedAt <= until (unix seconds)", "example": 1712349999, "in": "query", "schema": { "type": "integer" } }, { "name": "sort", "description": "Sort field (createdAt, updatedAt, scheduledFor)", "example": "createdAt", "in": "query", "schema": { "type": "string" } }, { "name": "order", "description": "Sort order (asc or desc)", "example": "desc", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "number", "example": 123 }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "task1" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "pending" }, "target": { "type": "string", "example": "+15551234567" }, "createdAt": { "type": "number", "example": 1712345678 } } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "number", "example": 123 }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "task1" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "pending" }, "target": { "type": "string", "example": "+15551234567" }, "createdAt": { "type": "number", "example": 1712345678 } } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } }, "post": { "tags": [ "Tasks" ], "summary": "Create a new task", "description": "Submit a new task (call, text, ping). For calls/texts, target is required.", "responses": { "201": { "description": "Task created successfully" }, "400": { "description": "Missing required fields" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "example": "call" }, "target": { "type": "string", "example": "+15551234567" }, "context": { "type": "string", "example": "Follow-up call" }, "greeting": { "type": "string", "example": "Hello from a task" }, "waitToGreet": { "type": "boolean", "example": true }, "scheduledFor": { "type": "integer", "example": 1712350000 } } } } } } } }, "/api/v2/tasks/csv": { "post": { "tags": [ "Tasks" ], "summary": "Create multiple tasks via CSV upload", "description": "Upload a CSV file to create multiple tasks. The CSV must include a header row. Recognized columns include type, target, context, taskContext, greeting, waitToGreet, accountId, scheduledFor, message, and externalTaskId.", "responses": { "200": { "description": "Tasks queued" }, "400": { "description": "Invalid CSV or missing required fields" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "csv" ], "properties": { "csv": { "type": "string", "format": "binary", "description": "CSV file" }, "dryRun": { "type": "boolean", "description": "Validate only; do not enqueue jobs" } } }, "encoding": { "csv": { "contentType": "text/csv" } } } } } } }, "/api/v2/tasks/stats": { "get": { "tags": [ "Tasks" ], "summary": "Task statistics", "description": "Get counts of tasks grouped by state (pending, running, finished, errored).", "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "number", "example": 10 }, "byState": { "type": "object", "properties": { "pending": { "type": "number", "example": 2 }, "running": { "type": "number", "example": 3 }, "finished": { "type": "number", "example": 5 } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "number", "example": 10 }, "byState": { "type": "object", "properties": { "pending": { "type": "number", "example": 2 }, "running": { "type": "number", "example": 3 }, "finished": { "type": "number", "example": 5 } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/api/v2/tasks/dailyCounts": { "get": { "tags": [ "Tasks" ], "summary": "Daily counts", "description": "Get current daily usage counts (calls, texts, tasks) for rate limiting.", "responses": { "200": { "description": "Daily counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "counts": { "type": "object", "properties": { "calls": { "type": "number", "example": 5 }, "texts": { "type": "number", "example": 12 }, "tasks": { "type": "number", "example": 17 }, "date": { "type": "string", "example": "2025-08-20" } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "counts": { "type": "object", "properties": { "calls": { "type": "number", "example": 5 }, "texts": { "type": "number", "example": 12 }, "tasks": { "type": "number", "example": 17 }, "date": { "type": "string", "example": "2025-08-20" } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/api/v2/tasks/limits": { "get": { "tags": [ "Tasks" ], "summary": "Fetch task limits", "description": "Retrieve the org’s current task limits configuration.", "responses": { "200": { "description": "Limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "limits": { "type": "object", "properties": { "businessHours": { "type": "object", "properties": { "timezone": { "type": "string", "example": "America/Chicago" }, "days": { "type": "array", "example": [ 1, 2, 3, 4, 5 ], "items": { "type": "number" } }, "start": { "type": "string", "example": "09:00" }, "end": { "type": "string", "example": "17:00" } } }, "daily": { "type": "object", "properties": { "calls": { "type": "number", "example": 100 }, "texts": { "type": "number", "example": 200 }, "tasks": { "type": "number", "example": 300 } } }, "concurrencyPerRun": { "type": "number", "example": 10 }, "cooldowns": { "type": "object", "properties": { "calls": { "type": "number", "example": 86400 }, "texts": { "type": "number", "example": 300 } } } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "limits": { "type": "object", "properties": { "businessHours": { "type": "object", "properties": { "timezone": { "type": "string", "example": "America/Chicago" }, "days": { "type": "array", "example": [ 1, 2, 3, 4, 5 ], "items": { "type": "number" } }, "start": { "type": "string", "example": "09:00" }, "end": { "type": "string", "example": "17:00" } } }, "daily": { "type": "object", "properties": { "calls": { "type": "number", "example": 100 }, "texts": { "type": "number", "example": 200 }, "tasks": { "type": "number", "example": 300 } } }, "concurrencyPerRun": { "type": "number", "example": 10 }, "cooldowns": { "type": "object", "properties": { "calls": { "type": "number", "example": 86400 }, "texts": { "type": "number", "example": 300 } } } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } }, "post": { "tags": [ "Tasks" ], "summary": "Update task limits", "description": "Update task limit settings. Non-superAdmins cannot edit daily or concurrencyPerRun.", "responses": { "200": { "description": "Limits updated successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden for non-superAdmins editing restricted fields" }, "500": { "description": "Internal Server Error" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "businessHours": { "type": "object" }, "cooldowns": { "type": "object" }, "daily": { "type": "object" }, "concurrencyPerRun": { "type": "integer" } } } } } } } }, "/api/v2/tasks/{taskId}": { "get": { "tags": [ "Tasks" ], "summary": "Fetch a specific task", "description": "Retrieve details for a single task by ID.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" } ], "responses": { "200": { "description": "Task found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "task": { "type": "object", "properties": { "id": { "type": "string", "example": "task1" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "pending" } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "task": { "type": "object", "properties": { "id": { "type": "string", "example": "task1" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "pending" } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "tags": [ "Tasks" ], "summary": "Update a task", "description": "Update fields on an existing task by ID.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" } ], "responses": { "200": { "description": "Task updated successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "example": "canceled" }, "context": { "type": "string", "example": "New context" }, "waitToGreet": { "type": "boolean", "example": true } } } } } } }, "delete": { "tags": [ "Tasks" ], "summary": "Delete a task", "description": "Remove a task by ID.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" } ], "responses": { "200": { "description": "Task deleted successfully" }, "401": { "description": "Unauthorized" }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v2/createReseller": { "post": { "tags": [ "Accounts" ], "summary": "Create a new reseller", "description": "Create a new reseller under your partner account. Partner account required.", "parameters": [ { "name": "targetPartnerId", "in": "query", "description": "Partner Id to create reseller in", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Reseller created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Reseller created" }, "organization": { "type": "string", "example": "New Reseller object" } } } } } }, "400": { "description": "Bad Request" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resellerName" ], "properties": { "email": { "description": "Admin user email for this account", "type": "string", "example": "admin@acmesolar.com" }, "resellerName": { "description": "Reseller Name", "type": "string", "example": "Acme Solar" }, "offeredProductPlanId": { "description": "Offered Product Plan. Requires the Reseller to accept and checkout.", "type": "string", "example": "custom-plan-1" }, "productPlanId": { "description": "Product Plan to set on the account. Otherwise default sell plan is used", "type": "string", "example": "base-plan-1" } } } } } } } }, "/api/v2/listResellers": { "get": { "tags": [ "Accounts" ], "summary": "List resellers", "description": "List all of your resellers. Partner account required.", "parameters": [ { "name": "targetPartnerId", "in": "query", "description": "Partner Id to list resellers in", "required": true, "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many resellers per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "active", "in": "query", "description": "Whether to return only resellers with this given active state", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/createOrganization": { "post": { "tags": [ "Accounts" ], "summary": "Create a new organization", "description": "Creates an organization under your reseller account (reseller auth required).", "parameters": [ { "name": "targetResellerId", "in": "query", "description": "Reseller-ID under which the org will be created", "required": true, "example": "2286", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Organization successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Organization created" }, "organization": { "type": "object", "description": "Created organization object" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "orgName" ], "properties": { "email": { "description": "Admin-user e-mail for the new org", "type": "string", "example": "admin@acmesolar.com" }, "orgName": { "description": "Organization name", "type": "string", "example": "Acme Solar" }, "productPlanId": { "description": "Product-plan ID. If omitted, defaults to your reseller sell-plan.", "type": "string", "example": "pplan-basic-monthly" }, "externalAccountId": { "description": "Your own CRM/customer ID for this org", "type": "string", "example": "external-org-12345" }, "externalBillingId": { "description": "External Id to match with your internal billing system", "type": "string", "example": "billing-id-12345" }, "numberingProviders": { "description": "Array of numbering provider configurations", "type": "array", "items": { "type": "object", "required": [ "providerId", "config" ], "properties": { "providerId": { "type": "string", "example": "Twilio" }, "default": { "type": "boolean", "example": true }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "accountSid": "ACxxxx", "authToken": "tokenxxxx" } } } } }, "vidaPremium": { "description": "Mark this account as an actively paying account", "type": "boolean", "example": true }, "smsEnabled": { "description": "Enable SMS Capabilities on the agent", "type": "boolean", "example": true }, "smsBrandId": { "description": "SMS Brand Id that is registered for the organization", "type": "string", "example": "XXXXXX" }, "smsCampaignId": { "description": "Approved SMS Campaign Id for the organizations traffic", "type": "string", "example": "XXXXXX" }, "integrations": { "description": "Optional list of third-party app integrations to set up at org creation", "type": "array", "items": { "type": "object", "required": [ "appId", "appVersion", "appData" ], "properties": { "appId": { "type": "string", "example": "someappId" }, "appVersion": { "type": "string", "example": "v1" }, "appData": { "type": "object", "description": "Key/value settings specific to the integration", "additionalProperties": { "type": "string" }, "example": { "apiToken": "appsApiToken" } } } }, "example": [ { "appId": "some-app-id", "appVersion": "v1", "appData": { "apiToken": "APIToken" } }, { "appId": "another-example-app", "appVersion": "v2", "appData": { "accountSid": "sidxxxxxxx", "accountToken": "tokenxxxxxxx", "apiUrl": "https://someurl.example" } } ] } } } } } } } }, "/api/v2/deleteOrganization": { "delete": { "tags": [ "Accounts" ], "summary": "Delete an organization", "description": "Delete (immediately) an organization under your reseller. Reseller account required.", "parameters": [ { "name": "targetResellerId", "in": "query", "description": "Reseller Id to delete organization in", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Organization deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Organization deleted" } } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetOrganizationId" ], "properties": { "targetOrganizationId": { "description": "Organization Id to delete", "type": "integer", "example": "XXXXXXX" } } } } } } } }, "/api/v2/listOrganizations": { "get": { "tags": [ "Accounts" ], "summary": "List organizations", "description": "List all of your organizations. Reseller account required.", "parameters": [ { "name": "targetResellerId", "in": "query", "description": "Reseller Id to list organizations in", "required": true, "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch (0-based)", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many orgs per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "active", "in": "query", "description": "Whether to return only organizations with this given active state", "required": false, "schema": { "type": "boolean" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/account": { "get": { "tags": [ "Accounts" ], "summary": "Get account details", "description": "Retrieve details for the authenticated account", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Target account ID when acting on behalf of another account", "required": false, "example": 123, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Account details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "username": { "type": "string", "example": "user@example.com" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Accounts" ], "summary": "Update account details", "description": "Update profile details for the authenticated account", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Target account ID when acting on behalf of another account", "required": false, "example": 123, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Updated account details", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name", "example": "Ada Lovelace" }, "partnerName": { "type": "string", "description": "Partner name (for partner accounts only)" }, "resellerName": { "type": "string", "description": "Reseller name (for reseller accounts only)" }, "orgName": { "type": "string", "description": "Organization name" }, "accountName": { "type": "string", "description": "Account name" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "description": { "type": "string", "description": "Profile description" }, "image": { "type": "string", "description": "Profile image URL" }, "businessName": { "type": "string", "description": "Business name" }, "businessAddress": { "type": "string", "description": "Business address" }, "email": { "type": "string", "format": "email", "description": "Email address" } } } } } } } }, "/api/v2/listAccounts": { "get": { "tags": [ "Accounts" ], "summary": "List agent accounts", "description": "List all of your agent accounts", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Organization Id to list accounts in", "required": true, "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many accounts per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "active", "in": "query", "description": "Whether to return only accounts with this given active state", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/createAccount": { "post": { "tags": [ "Accounts" ], "summary": "Create a new account", "description": "Create a new account under your organization", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Organization Id to create account in", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account created" }, "account": { "type": "string", "example": "New Account object" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountName": { "description": "Account Name", "type": "string", "example": "Acme Solar Bay Area Support Agent" }, "externalAccountId": { "description": "External Account Id to match with your internal system account Id", "type": "string", "example": "AC_12345" }, "externalBillingId": { "description": "External Id to match with your internal billing system", "type": "string", "example": "billing-id-6789" }, "integrations": { "description": "Optional list of third-party app integrations to set up at org creation", "type": "array", "items": { "type": "object", "required": [ "appId", "appVersion", "appData" ], "properties": { "appId": { "type": "string", "example": "someappId" }, "appVersion": { "type": "string", "example": "v1" }, "appData": { "type": "object", "description": "Key/value settings specific to the integration", "additionalProperties": { "type": "string" }, "example": { "apiToken": "appsApiToken" } } } }, "example": [ { "appId": "some-app-id", "appVersion": "v1", "appData": { "apiToken": "APIToken" } }, { "appId": "another-example-app", "appVersion": "v2", "appData": { "accountSid": "sidxxxxxxx", "accountToken": "tokenxxxxxxx", "apiUrl": "https://someurl.example" } } ] } } } } } } } }, "/api/v2/deleteAccount": { "delete": { "tags": [ "Accounts" ], "summary": "Delete an account", "description": "Delete an account under your organization", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Organization Id to delete the account in", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Account deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account deleted" } } } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetAccountId": { "description": "Account Id", "type": "string", "example": "3" } } } } } } } }, "/api/v2/listAdminUsers": { "get": { "tags": [ "Accounts" ], "summary": "List admin users", "description": "List all admin users of your organization", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/deleteAdminUser": { "delete": { "tags": [ "Accounts" ], "summary": "Delete admin user", "description": "Delete a user from your organization", "responses": { "200": { "description": "OK" }, "201": { "description": "Invitation sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Admin user successfully removed from your organization" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetUserId": { "description": "User Id of the user you are removing from your account", "type": "number", "example": 3 } } } } } } } }, "/api/v2/inviteAdminUser": { "post": { "tags": [ "Accounts" ], "summary": "Invite admin user", "description": "Invite a user to join your organization as an admin", "responses": { "200": { "description": "OK" }, "201": { "description": "Invitation sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Invitation sent" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "description": "Email of the person you are inviting", "type": "string", "example": "admin@acmesolar.com" }, "redirectUrl": { "description": "URL to redirect user to after they accept invite", "type": "string", "example": "https://vida.io/welcome" } } } } } } } }, "/api/v2/stats/usage": { "get": { "tags": [ "Billing" ], "summary": "View Usage", "description": "View statistics about account usage", "parameters": [ { "name": "billingPeriod", "in": "query", "schema": { "type": "string" } }, { "name": "giveCosts", "in": "query", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "boolean" }, "default": { "type": "boolean", "example": false } } }, "description": "Returns values for keys with cost: prefix." } ], "responses": { "200": { "description": "Stats fetched successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/offeredPlan": { "get": { "tags": [ "Billing" ], "summary": "View Offered Product Plan", "description": "View Your Product Plan Offer", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/currentPlan": { "get": { "tags": [ "Billing" ], "summary": "View Current Product Plan", "description": "View Your Current Product Plan", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/allAvailablePlans": { "get": { "tags": [ "Billing" ], "summary": "View Available Product Plans", "description": "View All Available Product Plans", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/billing/billingSystemConfig": { "post": { "tags": [ "Billing" ], "summary": "Provision Billing System Configuration", "description": "Provision or Update Your Billing System Configuration", "responses": { "200": { "description": "Successfull response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "billingSystemType" ], "properties": { "billingSystemType": { "description": "Type of billing system", "type": "string", "example": "stripe" }, "apiKey": { "description": "Required - API Key used for billing system access", "type": "string", "example": "somekey" }, "publishableKey": { "description": "Required - Publishable Key used for embeded checkouts", "type": "string", "example": "somepublishablekey" }, "webhookSigningKey": { "description": "Required for Stripe only - used for validating webhooks are signed by Stripe", "type": "string", "example": "somewebhooksigningkey" }, "site": { "description": "Required for Chargebee only - site (without chargebee.com) of your payment system", "type": "string", "example": "vida" }, "webhookUsername": { "description": "Required for Chargebee only - username for webhook authentication", "type": "string", "example": "someusername" }, "webhookPassword": { "description": "Required for Chargebee only - password for webhook authentication", "type": "string", "example": "somepassword" } } } } } } } }, "/api/v2/product/subscribe": { "post": { "tags": [ "Billing" ], "summary": "Subscribe to product plan", "description": "Subscribe to a product plan", "responses": { "200": { "description": "Successfully subscribed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "productPlanId", "term" ], "properties": { "productPlanId": { "description": "Product Plan Id to enable subscription", "type": "string", "example": "pplan-vida-business-basic" }, "term": { "description": "Subscription length of month or year", "type": "string", "example": "month" }, "cancelUrl": { "description": "If using external payment processor (eg Stripe) what url to redirect if payment canceled", "type": "string", "example": "https://yoursite.io/cancel" }, "successUrl": { "description": "If using external payment processor (eg Stripe) what url to redirect if payment successful", "type": "string", "example": "https://yoursite.io/success" }, "checkoutType": { "description": "Which checkout session you would like to start. Embedded session or external redirect url", "type": "string", "example": "embedded" } } } } } } } }, "/api/v2/product/cancel": { "delete": { "tags": [ "Billing" ], "summary": "Cancel product subscription", "description": "Cancel the current product subscription for the authenticated account", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Target account ID when acting on behalf of another account", "required": false, "example": 123, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Subscription canceled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subscription cancelled" } } } } } }, "400": { "description": "Unable to cancel subscription", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Cancellation reason" }, "details": { "type": "string", "description": "Additional details" } } } } } } } }, "/api/v2/addon/available": { "get": { "tags": [ "Billing" ], "summary": "View Available Add Ons", "description": "View all available Add-Ons for current product plan", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/productCatalog": { "get": { "tags": [ "Billing" ], "summary": "View Product Catalog", "description": "View Your Product Catalog Plans. Reseller or Partner Account Required.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/productPlan/{productPlanId}": { "get": { "tags": [ "Billing" ], "summary": "Fetch a product plan details", "description": "Fetch a product plan details from your catalog", "parameters": [ { "name": "productPlanId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product Plan Id", "example": "pplan-id-xxxx" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/numberingProviders": { "get": { "tags": [ "Phone Numbers" ], "summary": "List supported numbering providers", "description": "Returns every numbering provider supported along with configuration requirements. Requires a valid reseller or partner account.", "responses": { "200": { "description": "Numbering providers fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Numbering providers fetched successfully" }, "numberingProviders": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "description": "No numbering providers configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No numbering providers configured" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/logs": { "get": { "tags": [ "Logs" ], "summary": "Query conversation logs", "description": " Retrieves conversation logs from Postgres for the authenticated caller. Scoping by accountType: - account: filters to account_id = req.user.id and removes fields resellerId, partnerId, organizationId - organization: filters to org_id = req.user.id and removes fields resellerId, partnerId, organizationId - reseller: filters to reseller_id = req.user.id and removes fields resellerId, partnerId - partner: filters to partner_id = req.user.id and removes field partnerId Dynamic filters: Any extra query parameter is treated as a filter. Values are parsed to boolean, number, JSON, string, or null. Force a type with a suffix type hint using \"||\". Examples: - status=active - score=4 - exactMatch=true - payload=%7B%22a%22%3A1%7D||json - archived=false||bool CSV behavior: If format=csv and no rows are found, a 404 JSON response is returned instead of an empty file. ", "parameters": [ { "name": "start", "in": "query", "required": false, "description": "Start time as Unix seconds. Defaults to 7 days ago.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "integer" }, "example": { "type": "number", "example": 1727481600 } } } }, { "name": "end", "in": "query", "required": false, "description": "End time as Unix seconds. Defaults to current time.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "integer" }, "example": { "type": "number", "example": 1728086400 } } } }, { "name": "fields", "in": "query", "required": false, "description": "Comma separated list of fields to include. Restricted fields are always removed.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "example": { "type": "string", "example": "id,timestamp,account_id,org_id,eventType" } } } }, { "name": "format", "in": "query", "required": false, "description": "Response format. json returns a JSON envelope. csv streams a CSV file.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "enum": { "type": "array", "example": [ "json", "csv" ], "items": { "type": "string" } }, "default": { "type": "string", "example": "json" } } } }, { "name": "pageSize", "in": "query", "required": false, "description": "Page size for pagination. Max 10000. Defaults to 20.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "integer" }, "minimum": { "type": "number", "example": 1 }, "maximum": { "type": "number", "example": 10000 }, "example": { "type": "number", "example": 500 } } } }, { "name": "page", "in": "query", "required": false, "description": "Page number starting at 1. Defaults to 1.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "integer" }, "minimum": { "type": "number", "example": 1 }, "example": { "type": "number", "example": 1 } } } }, { "name": "includeFields", "in": "query", "required": false, "description": "When truthy, include an inferred schema array in the JSON response.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "boolean" }, "example": { "type": "boolean", "example": true } } } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination or access token if supported by upstream systems.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "example": { "type": "string", "example": "eyJhbGciOi..." } } } }, { "name": "targetAccountId", "in": "query", "required": false, "description": "Optional target account context. May be ignored based on caller scope.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "example": { "type": "string", "example": "acct_123" } } } }, { "name": "...additional filters...", "in": "query", "required": false, "description": "Any other query parameters are treated as filters. Supports explicit type hints with ", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "object" }, "additionalProperties": { "type": "boolean", "example": true } } } } ], "responses": { "200": { "description": "Successful JSON response. When format=csv, a CSV file is streamed with status 200.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "logs": { "type": "array", "description": "Array of log entries with restricted fields removed based on caller scope.", "items": { "type": "object", "additionalProperties": true, "example": { "id": "log_001", "timestamp": "2025-09-30T12:34:56.789Z", "account_id": "acct_123", "org_id": "org_456", "eventType": "message.created", "metadata": { "convoId": "c_abc", "tokens": 1234 } } } }, "count": { "type": "integer", "example": 20 }, "totalCount": { "type": "integer", "example": 5231 }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 20 }, "totalPages": { "type": "integer", "example": 262 }, "totalCount": { "type": "integer", "example": 5231 }, "hasMore": { "type": "boolean", "example": true }, "pageCount": { "type": "integer", "example": 262 } } }, "schema": { "type": "array", "description": "Returned only when includeFields is truthy. The inferred list of available fields.", "items": { "type": "string" }, "example": [ "id", "timestamp", "account_id", "org_id", "eventType", "metadata" ] } } } }, "text/csv": { "schema": { "type": "string", "format": "binary", "description": "CSV export of logs when format=csv" } } } }, "401": { "description": "Unauthorized. req.user missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "404": { "description": "No logs available for CSV export when format=csv", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No logs found for CSV export" } } } } } }, "500": { "description": "Unhandled server error while fetching logs or generating CSV", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while fetching conversation logs." }, "error": { "type": "string", "example": "Detailed error message" } } } } } }, "503": { "description": "Conversation logs service not available", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Conversation logs service not available" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/searchAccounts": { "get": { "tags": [ "Accounts" ], "summary": "Search accounts", "description": "Search partner, reseller, organization or account objects using various filters", "parameters": [ { "name": "accountType", "in": "query", "description": "Type of account to search", "required": true, "example": "organization", "schema": { "type": "string" } }, { "name": "queryText", "in": "query", "description": "Optional free text search", "required": false, "example": "vida", "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many accounts per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "createdStart", "in": "query", "description": "Epoch to search created accounts from", "required": false, "example": 1700000000, "schema": { "type": "number" } }, { "name": "createdEnd", "in": "query", "description": "Epoch to search created accounts until", "required": false, "example": 1710000000, "schema": { "type": "number" } }, { "name": "canceledStart", "in": "query", "description": "Epoch to search cancellations from", "required": false, "example": 1700000000, "schema": { "type": "number" } }, { "name": "canceledEnd", "in": "query", "description": "Epoch to search cancellations until", "required": false, "example": 1710000000, "schema": { "type": "number" } }, { "name": "subscribed", "in": "query", "description": "Filter by subscription state", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "canceled", "in": "query", "description": "Filter by canceled subscription state", "required": false, "example": false, "schema": { "type": "boolean" } }, { "name": "active", "in": "query", "description": "Filter by active flag", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "onboardingComplete", "in": "query", "description": "Filter by onboarding completed flag", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "productPlanId", "in": "query", "description": "Product plan id filter", "required": false, "example": "plan1", "schema": { "type": "string" } }, { "name": "productPlanTerm", "in": "query", "description": "Product plan term filter", "required": false, "example": "monthly", "schema": { "type": "string" } }, { "name": "billingSubscriptionId", "in": "query", "description": "Billing subscription id filter", "required": false, "example": "sub_123", "schema": { "type": "string" } }, { "name": "billingId", "in": "query", "description": "Billing id filter", "required": false, "example": "bill_123", "schema": { "type": "string" } }, { "name": "externalAccountId", "in": "query", "description": "External account id filter", "required": false, "example": "ext_123", "schema": { "type": "string" } }, { "name": "currentBillingPeriodVoiceMinutesMin", "in": "query", "description": "Minimum current period voice minutes", "required": false, "example": 10, "schema": { "type": "number" } }, { "name": "currentBillingPeriodVoiceMinutesMax", "in": "query", "description": "Maximum current period voice minutes", "required": false, "example": 200, "schema": { "type": "number" } }, { "name": "previousBillingPeriodVoiceMinutesMin", "in": "query", "description": "Minimum previous period voice minutes", "required": false, "example": 5, "schema": { "type": "number" } }, { "name": "previousBillingPeriodVoiceMinutesMax", "in": "query", "description": "Maximum previous period voice minutes", "required": false, "example": 100, "schema": { "type": "number" } }, { "name": "currentBillingPeriodMessagesMin", "in": "query", "description": "Minimum current period messages", "required": false, "example": 10, "schema": { "type": "number" } }, { "name": "currentBillingPeriodMessagesMax", "in": "query", "description": "Maximum current period messages", "required": false, "example": 200, "schema": { "type": "number" } }, { "name": "previousBillingPeriodMessagesMin", "in": "query", "description": "Minimum previous period messages", "required": false, "example": 5, "schema": { "type": "number" } }, { "name": "previousBillingPeriodMessagesMax", "in": "query", "description": "Maximum previous period messages", "required": false, "example": 100, "schema": { "type": "number" } }, { "name": "allTimeVoiceMinutesMin", "in": "query", "description": "Minimum all time voice minutes", "required": false, "example": 100, "schema": { "type": "number" } }, { "name": "allTimeVoiceMinutesMax", "in": "query", "description": "Maximum all time voice minutes", "required": false, "example": 1000, "schema": { "type": "number" } }, { "name": "allTimeMessagesMin", "in": "query", "description": "Minimum all time messages", "required": false, "example": 100, "schema": { "type": "number" } }, { "name": "allTimeMessagesMax", "in": "query", "description": "Maximum all time messages", "required": false, "example": 1000, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "totalAccounts": { "type": "number", "example": 1 }, "pageSize": { "type": "number", "example": 20 }, "pageNumber": { "type": "number", "example": 0 }, "accounts": { "type": "array", "items": { "type": "object" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/auth/account/oneTimeAuthToken": { "get": { "tags": [ "Authorization" ], "summary": "Generate one-time auth token", "description": "Generate a single-use authentication token for the specified account – Reseller/Partner account required. If the email does not exist and an externalAccountId is provided, the system will automatically add that email as a member of the organization.", "parameters": [ { "name": "externalAccountId", "in": "query", "description": "Your system’s customer / account ID (optional)", "required": false, "example": "acct_123abc", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "description": "Alternative to externalAccountId. Provide either this or your externalAccountId (optional)", "required": false, "example": "acct_123abc", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Email address of the account user", "required": true, "example": "user@example.com", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auth token created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "authToken": { "type": "string", "example": "token_here" } } } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "email is required" } } } } } }, "401": { "description": "Unauthorized : missing / bad API key or token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "404": { "description": "No account found OR caller lacks access", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Account not found for key: user@example.com" } } } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while fetching authentication token" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/getAccountByExternalId": { "get": { "tags": [ "Accounts" ], "summary": "Fetch Account by externalAccountId", "description": "Returns the account that matches the externalAccountId – Reseller/Partner only.", "parameters": [ { "name": "externalAccountId", "in": "query", "description": "Your system’s customer / account ID", "required": true, "example": "acct_123abc", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "account": { "type": "object" } } }, "examples": { "example": { "value": { "success": true, "message": "Success", "account": { "id": 3, "username": "accountUsername", "organizationId": 3 } } } } } } }, "400": { "description": "Missing or invalid externalAccountId", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "externalAccountId is required" } } } } } }, "401": { "description": "Unauthorized : missing / bad API key or token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "404": { "description": "No account found OR caller lacks access", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Account not found for externalAccountId acct_123abc" } } } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while fetching account" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/billing/adrExportConfig": { "post": { "tags": [ "Billing" ], "summary": "Configure ADR Export Settings", "description": "Configure or update your ADR export settings", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "deliveryProtocol", "rotationMinutes", "host", "port", "username", "password" ], "properties": { "deliveryProtocol": { "description": "SFTP, FTPS, or FTP", "type": "string", "example": "sftp" }, "rotationMinutes": { "description": "How many minutes of records should be contained in each file", "type": "string", "example": "somekey", "default": "60" }, "host": { "description": "hostname or IP address where to ship the ADR files to", "type": "string", "example": "sftp.domain.com" }, "port": { "description": "Port for the SFTP or FTP service", "type": "integer", "example": 2202 }, "username": { "description": "username for the sftp or ftp account", "type": "string", "example": "someuser" }, "password": { "description": "password for the sftp or ftp account", "type": "string", "example": "somepassword" }, "path": { "description": "Folder path to deposit the files to. Defaults to the users home directory", "type": "string", "example": "/path/" } } } } } } } }, "/api/v2/updateOrganization": { "post": { "tags": [ "Accounts" ], "summary": "Update Organization Settings", "description": "Update certain settings for an organization – Reseller/Partner only.", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Target Organization Id to update settings for", "required": true, "example": "XXXXXXX", "schema": { "type": "string" } } ], "responses": { "200": { "description": "At least one setting was successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Organization settings updated" }, "updatedSettings": { "type": "array", "items": { "type": "string" }, "example": [ "orgName", "vidaPremium" ] }, "failedSettings": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": [ "email" ] } } }, "examples": { "AllSuccess": { "summary": "All requested changes succeeded", "value": { "success": true, "message": "Organization settings updated", "updatedSettings": [ "productPlanId", "externalBillingId" ] } }, "PartialSuccess": { "summary": "Some settings failed validation / update", "value": { "success": true, "message": "Organization settings updated", "updatedSettings": [ "vidaPremium" ], "failedSettings": [ "email", "smsEnabled" ] } } } } } }, "400": { "description": "Bad request – nothing updated *or* specific validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No settings updated" }, "failedSettings": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": [ "productPlanId" ] } } }, "examples": { "NothingUpdated": { "summary": "Request parsed but no valid changes supplied", "value": { "success": false, "message": "No settings updated" } }, "ProductPlanCheckoutRequired": { "summary": "Product-plan change blocked until checkout completed", "value": { "success": false, "message": "Unable to change product plan, customer has not yet completed billing checkout. Please offer the plan first.", "failedSettings": [ "productPlanId" ] } }, "InvalidEmail": { "summary": "Email failed format validation", "value": { "success": false, "message": "Invalid email provided. Doesn't look like a valid email address.", "failedSettings": [ "email" ] } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "description": "Account status - if set to false calls and messages for all agents in this org will no longer be answered", "type": "boolean", "example": true }, "productPlanId": { "description": "Change Product Plan Id on the Organization. Note: if the target product plan is tied to a Stripe or Chargebee product and the customer has not yet subscribed - this will not work. Give the customer an offered product plan first. Otherwise - this will update the product plan on Vida and in the configured billing system.", "type": "string", "example": "someProductPlanId" }, "offeredProductPlanId": { "description": "Give an offer of a product plan to a customer. Useful when offering a private plan before the customer has completed checkout. Set null to remove it", "type": "string", "example": "someProductPlanId" }, "email": { "description": "Change main owner Email Of the Organization", "type": "string", "example": "admin@test.com" }, "orgName": { "description": "Change Organization Name", "type": "string", "example": "Test Organization" }, "smsEnabled": { "description": "Enable SMS Capabilities on the agent.", "type": "boolean", "example": true }, "smsBrandId": { "description": "SMS Brand Id that is registered for the organization", "type": "string", "example": "XXXXXX" }, "smsCampaignId": { "description": "Approved SMS Campaign Id for the organizations traffic", "type": "string", "example": "XXXXXX" }, "vidaPremium": { "description": "Indicates whether the account is in an unlocked (paid) state.", "type": "boolean", "example": true }, "externalAccountId": { "description": "External Account Id to match with your internal system account Id. Set to null to remove it.", "type": "string", "example": "AC_XXXXXXX" }, "externalBillingId": { "description": "External Id to match with your internal billing system. Set to null to remove it.", "type": "string", "example": "somebillingId" } } } } } } } }, "/api/v2/updateAccount": { "post": { "tags": [ "Accounts" ], "summary": "Update Account Settings", "description": "Update certain settings for an account – Reseller/Partner only.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Target Account Id to update settings for", "required": true, "example": "XXXXXXX", "schema": { "type": "string" } } ], "responses": { "200": { "description": "At least one setting was successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account settings updated" }, "updatedSettings": { "type": "array", "items": { "type": "string" }, "example": [ "accountName" ] }, "failedSettings": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": [ "externalBillingId" ] } } } } } }, "400": { "description": "Bad request – nothing updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No settings updated" }, "failedSettings": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": [ "externalBillingId" ] } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "description": "Account status - if set to false calls and messages will not be answered", "type": "boolean", "example": true }, "accountName": { "description": "Change Account Name", "type": "string", "example": "Support Team" }, "externalAccountId": { "description": "External Account Id to match with your internal system account Id. Set to null to remove it.", "type": "string", "example": "AC_XXXXXXX" }, "externalBillingId": { "description": "External Id to match with your internal billing system. Set to null to remove it.", "type": "string", "example": "somebillingId" } } } } } } } }, "/api/v2/numberingProvider": { "post": { "tags": [ "Phone Numbers" ], "summary": "Add a numbering provider to an organization", "description": "Create a new numbering provider configuration for an organization – Reseller/Partner only.", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Target Organization Id to update settings for", "required": true, "example": "XXXXXXX", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Numbering provider added", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Numbering provider added" } } } } } }, "400": { "description": "Validation or duplication error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Numbering provider already exists" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerId", "config" ], "properties": { "providerId": { "type": "string", "example": "Twilio" }, "default": { "type": "boolean", "example": false }, "enabled": { "type": "boolean", "example": true }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "twilioAccountSid": "ACxxxx", "twilioAuthToken": "tokenxxxx" } } } } } } } }, "put": { "tags": [ "Phone Numbers" ], "summary": "Update an existing numbering provider", "description": "Modify an existing numbering provider configuration, set default, or disable it – Reseller/Partner only.", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Target Organization Id to update settings for", "required": true, "example": "XXXXXXX", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Numbering provider updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Numbering provider updated" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Only one numbering provider can be set as default" } } } } } }, "404": { "description": "Specified provider not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Numbering provider not found" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerId" ], "properties": { "providerId": { "type": "string", "example": "Twilio" }, "default": { "type": "boolean", "example": true }, "enabled": { "type": "boolean", "example": false }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "accountSid": "ACxxxx", "authToken": "tokenxxxx" } } } } } } } } }, "/api/v2/webhookRelay/types": { "get": { "tags": [ "Webhooks" ], "summary": "List supported Webhook Relay types", "description": "Returns every webhook relay type that can be configured for your account (e.g., Twilio SMS, Chargebee, etc.).", "responses": { "200": { "description": "Relay types fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay types fetched successfully" }, "types": { "type": "array", "items": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string", "description": "Unique identifier for this relay type", "example": "twilioSMS" }, "description": { "type": "string", "description": "What the relay does", "example": "Proxy inbound Twilio SMS webhooks to your app first before agent processes them." } } } } } } } } }, "401": { "description": "Unauthorized – missing or invalid API key/token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "500": { "description": "Internal server or data-store error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal data store error" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/webhookRelay/{type}": { "post": { "tags": [ "Webhooks" ], "summary": "Create or update a webhook relay", "description": "Forward incoming webhooks of the specified type to your URL.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "example": { "type": "string", "example": "twilioSMS" } } }, "description": "Relay type (e.g. twilioSMS, chargebee)" } ], "responses": { "200": { "description": "Relay stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay for type 'twilioSMS' configured successfully." } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "headers must be an array of single-key objects" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "403": { "description": "Premium feature required", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay is a premium feature. Please upgrade your account." } } } } } }, "404": { "description": "Relay type not supported", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay type 'foo' is not supported." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to store configuration." } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Absolute HTTP/HTTPS endpoint that will receive the forwarded webhook.", "example": "https://example.com/webhook/twilio" }, "timeout": { "type": "number", "description": "Timeout (ms) before the forward request is aborted.", "example": 5000 }, "headers": { "type": "array", "description": "Custom HTTP headers (array of single-key objects).", "items": { "type": "object", "example": { "Authorization": "Bearer xyz" } }, "example": [ { "Authorization": "Bearer xyz" }, { "X-Customer-ID": "abc123" } ] }, "successStatusCodes": { "type": "array", "description": "Status codes treated as success by Vida when your endpoint responds.", "items": { "type": "integer", "example": 202 }, "example": [ 200, 201, 202 ] } } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook relay configuration", "description": "Removes the stored webhook relay settings for the specified type from the authenticated user account.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Relay type to delete (must be one previously configured)", "example": "twilioSMS" } ], "responses": { "200": { "description": "Relay configuration deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay type 'twilioSMS' removed successfully." } } } } } }, "400": { "description": "Missing or invalid type parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "type path parameter is required and must be a string" } } } } } }, "401": { "description": "Unauthorized – missing or invalid API key/token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "403": { "description": "Forbidden – feature requires Vida Premium", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay is a premium feature. Please upgrade your account to use it." } } } } } }, "404": { "description": "Relay type was not configured for this user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay type 'foo' was not configured." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal error" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook relay configuration", "description": "Fetch the current webhook relay settings for the given type (e.g., Twilio SMS, Chargebee) for your account.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Relay type to fetch (must match one of GET /webhookRelay/types)", "example": "twilioSMS" } ], "responses": { "200": { "description": "Relay configuration found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay configuration fetched successfully." }, "config": { "type": "object", "properties": { "url": { "type": "string", "example": "https://hooks.myapp.com/inbound/twilio" }, "timeout": { "type": "number", "example": 5000 }, "headers": { "type": "array", "items": { "type": "object", "example": { "Authorization": "Bearer xyz" } } }, "successStatusCodes": { "type": "array", "items": { "type": "integer" }, "example": [ 200, 202 ] } } } } } } } }, "401": { "description": "Unauthorized – missing or invalid API key/token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "403": { "description": "Forbidden – feature requires Vida Premium", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay is a premium feature. Please upgrade your account to use it." } } } } } }, "404": { "description": "Relay type not configured for this user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay type 'twilioSMS' not configured." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal error" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/webhookRelay": { "get": { "tags": [ "Webhooks" ], "summary": "List all webhook relay configurations", "description": "Fetch the complete set of webhook relay settings configured on your account.", "responses": { "200": { "description": "At least one relay configuration found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay configurations fetched successfully." }, "configs": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "example": "twilioSMS" }, "url": { "type": "string", "example": "https://hooks.myapp.com/inbound/twilio" }, "timeout": { "type": "number", "example": 5000 }, "headers": { "type": "array", "items": { "type": "object", "example": { "Authorization": "Bearer xyz" } } }, "successStatusCodes": { "type": "array", "items": { "type": "integer" }, "example": [ 200, 202 ] } } } } } } } } }, "401": { "description": "Unauthorized – missing or invalid API key/token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "403": { "description": "Forbidden – feature requires Vida Premium", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay is a premium feature. Please upgrade your account to use it." } } } } } }, "404": { "description": "The user has no webhook relay configurations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No webhook relay configurations found." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal error" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent": { "post": { "tags": [ "Agents" ], "summary": "Update Agent", "description": "Update an agent", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent created." }, "campaignId": { "type": "string", "example": "camp931829b5857f...." } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "description" ], "properties": { "type": { "description": "Type for this agent", "type": "string", "enum": [ "chatAgent" ] }, "title": { "description": "Title for Agent", "type": "string", "example": "Call Screener" }, "description": { "description": "Some description", "type": "string", "example": "Description" }, "welcomeMessage": { "description": "Message users see when initially visiting a agent", "type": "string", "example": "This brought to you by Wolf Cola" }, "links": { "description": "Array of any http links to reference for external knowledge for your agent", "type": "array", "items": { "type": "string" }, "example": [ "https://vida.io/faq" ] }, "actions": { "description": "Actions that your agent can take including instructions and settings", "type": "array", "items": { "type": "string" }, "example": [ "transfer" ] }, "timezone": { "description": "The IANA (Internet Assigned Numbers Authority) formatted timezone your AI agent operates in.", "type": "string", "example": "America/Chicago, America/New_York, Europe/London, etc" }, "agentVoice": { "description": "Agent voice model to use", "type": "string", "example": "en-US Female" }, "agentLang": { "description": "Agent language to be used for voice and transcriptions", "type": "string", "enum": [ "en-US", "multi", "es-MX", "es-ES", "es-US" ], "default": "en-US" }, "agentInstructions": { "description": "Agent instructions for user interaction. This is for chatAgents only", "type": "string", "example": "I want you to payout rewards for users that answer a few questions about this promotional video." }, "agentModel": { "description": "Agent LLM model to use for its intelligence", "type": "string", "example": "gpt-4o-2024-08-06" }, "agentS2SEngine": { "description": "(Requires Specific Paid Plan) The Speech-to-Speech Voice engine to use for voice, AI, and transcriptions", "type": "string", "enum": [ null, "openai", "deepgram" ], "default": null }, "agentSttEngine": { "description": "Speech to text engine for this agent", "type": "string", "enum": [ "google", "deepgram" ], "default": "deepgram" }, "postAnswerDtmf": { "description": "DTMF your agent will send upon answering a call. Useful if you are forwarding calls to your agent from a platform that requires a DTMF verification before the call is connected.", "type": "string" }, "waitOnAnswer": { "description": "The amount of time in milliseconds your Agent will wait before speaking the greeting (welcomeMessage).", "type": "integer" }, "interruptionWordCount": { "description": "how many words a caller needs to speak before it is treated as an interruption", "type": "integer", "default": 3 }, "interruptionMinimumSpeakingTime": { "description": "(in seconds) How long the agent needs to be speaking before it can be interrupted", "type": "integer", "default": 3 }, "speakingTimeout": { "description": "(in milliseconds) the default amount of time between words before we consider caller speaking to be finished. Increasing this can help prevent unintentional interruptions for slow talkers. ", "type": "integer", "default": 1200 }, "speechProcessingDelay": { "description": "(in milliseconds) the default amount of delay before processed speech is sent to the LLM for a response. Increasing this can help prevent unintentional interruptions for slow talkers. Note that this delay automatically increases and decreases depending on the number of interruptions over a period of time.", "type": "integer", "default": 500 }, "speechProcessingDelayInterruptionStep": { "description": "(in milliseconds) how much speech processing delay is added per interruption.", "type": "integer", "default": 500 }, "speechProcessingDelayMaxMultiplier": { "description": "the maximum number of interruptions that will influence the speech processing delay.", "type": "integer", "default": 4 }, "callerResponseTimeout": { "description": "(in seconds) how much silence (nothing said by the caller) before the agent asks _are you still there?_.", "type": "integer", "default": 13 }, "callerResponseTimeoutHangupCounter": { "description": "the maximum number of times your agent can ask _are you there_ (callerResponseTimeout) before hanging up the call.", "type": "integer", "default": 3 }, "noContactInjection": { "description": "Whether the contact card for the caller should be injected into the agent context", "type": "boolean", "default": false }, "noConvoHistory": { "description": "Whether the call summary history for the caller should be injected into the agent context", "type": "boolean", "default": false }, "autoRecordingNotification": { "description": "Whether to automatically notify callers that recording is happening: _true (string)_ means notify callers from area codes where it is legally required. _false (string)_ means never notify callers. _always (string)_ means notify every caller whether legally required or not that recording is in progress.", "type": "string", "default": "true" }, "recordingNotificationPhrase": { "description": "The phrase that will be spoken to the caller notifying them that recording is in progress: _This call is being recorded_ is the default.", "type": "string", "default": "This call is being recorded." }, "preAnswerRingTime": { "description": "In seconds. How many seconds should the caller experience ringing before the agent answers. Valid value range is 1-60", "type": "integer", "default": null }, "confirmTransfers": { "description": "Require callee to press 1 before a transfer is completed", "type": "boolean", "default": false }, "apps": { "description": "Array of apps to enable for this given agent", "type": "array", "default": [], "items": { "type": "object", "required": [ "appId", "version", "instructions" ], "properties": { "appId": { "type": "string", "example": "squareUp", "description": "The identifier for the integrated app." }, "version": { "type": "string", "example": "v1", "description": "The version of the app integration." }, "instructions": { "type": "string", "example": "Use this app to book appointments from the user.", "description": "Instructions for how to use the app." } } } } } } } } } } }, "/api/v2/agentEventRules/staging": { "get": { "tags": [ "Agents" ], "summary": "Fetch Staging Agent", "description": "Fetch your Staging agent configuration.", "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agentEventRules/default": { "get": { "tags": [ "Agents" ], "summary": "Fetch Live Agent", "description": "Fetch your Live (default) agent configuration.", "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/checkAgentUrl": { "get": { "tags": [ "Agent URLs" ], "summary": "Check agent url availability", "description": "Check if an agent url is available for use", "parameters": [ { "name": "targetUsername", "in": "query", "description": "Target username", "required": true, "example": "brandon", "schema": { "type": "string" } }, { "name": "slug", "in": "query", "description": "Desired slug name", "required": true, "example": "weloveVida", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Slug created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "available": { "type": "boolean", "example": true }, "slug": { "type": "string", "example": "welovevida" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agentUrl": { "get": { "tags": [ "Agent URLs" ], "summary": "Fetch existing agent url", "description": "Check if existing agent url exists for a user or create new one", "parameters": [ { "name": "targetUsername", "in": "query", "description": "Target username", "required": true, "example": "brandon", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Slug retrieved/fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "slug": { "type": "string", "example": "welovevida" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Agent URLs" ], "summary": "Create agent url", "description": "Create a new url for an agent and replace existing one if exists", "responses": { "200": { "description": "Referral Slug Created Successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "slug": { "type": "string", "example": "welovevida" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetUsername", "slug" ], "properties": { "targetUsername": { "description": "Target Username you are creating a referral slug for", "type": "string", "example": "brandon" }, "slug": { "description": "Desired slug name", "type": "string", "example": "welovevida" } } } } } } } }, "/api/v2/agent/{agentId}": { "get": { "tags": [ "Agents" ], "summary": "Get Agent", "description": "Fetch an agent details", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id", "example": "campa931829b5857f...." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "sponsorship": { "properties": { "id": { "description": "Agent Id", "type": "string", "example": "campa931829b5857f...." } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/outboundSms": { "post": { "tags": [ "Agents" ], "summary": "Queue outbound SMS text message(s) from your Agent", "description": "Backwards compatible with the previous endpoint. You can pass a single \"target\" and required \"content\", or provide \"targets\" to enqueue multiple messages. This queues tasks instead of sending immediately.", "responses": { "200": { "description": "Queued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Outbound SMS initiated." }, "inserted": { "type": "integer", "example": 3 }, "tasks": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "target", "content" ], "properties": { "target": { "type": "string", "description": "Phone in E.164 or VIDA username", "example": "+1234567890" }, "content": { "type": "string", "description": "Message body", "example": "Hello from Acme. Your appointment is tomorrow at 10am." }, "context": { "type": "string", "description": "Optional context for the agent handling the conversation" }, "taskContext": { "type": "string", "description": "Task-specific context for this message" }, "agentId": { "type": "integer", "description": "Optional campaign id override" }, "scheduledFor": { "type": "integer", "description": "Unix seconds to schedule delivery" }, "meta": { "type": "object", "description": "Optional metadata" }, "externalTaskId": { "type": "string", "description": "Optional customer-provided identifier applied to created task(s)" } } }, { "type": "object", "required": [ "targets" ], "properties": { "targets": { "description": "Array of destinations or objects with per-item options", "oneOf": [ { "type": "array", "items": { "type": "string", "example": "+1234567890" } }, { "type": "array", "items": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "example": "+1234567890" }, "content": { "type": "string", "description": "Per-item message body" }, "context": { "type": "string" }, "taskContext": { "type": "string" }, "agentId": { "type": "integer" }, "scheduledFor": { "type": "integer" }, "meta": { "type": "object" }, "externalTaskId": { "type": "string", "description": "Identifier applied to this task" } } } } ] }, "content": { "type": "string", "description": "Message applied to all when targets is an array of strings" }, "context": { "type": "string", "description": "Context applied to all items when not provided per item" }, "taskContext": { "type": "string", "description": "Task-specific context applied to all items when not provided per item" }, "agentId": { "type": "integer", "description": "Agent id applied to all items" }, "scheduledFor": { "type": "integer", "description": "Schedule applied to all items" }, "scheduleSpacingSec": { "type": "integer", "description": "If provided, stagger scheduledFor by this many seconds per index", "example": 15 }, "meta": { "type": "object", "description": "Metadata applied to all items" }, "externalTaskId": { "type": "string", "description": "Optional customer-provided identifier applied to all created tasks" } } } ] }, "examples": { "single": { "summary": "Single target, backwards compatible", "value": { "target": "+15551234567", "content": "Hi, quick reminder for tomorrow at 10am.", "context": "Reminder campaign" } }, "batchStrings": { "summary": "Multiple string targets with shared content", "value": { "targets": [ "+15551230001", "+15551230002", "+15551230003" ], "content": "Thanks for signing up. Reply YES to confirm.", "context": "Onboarding nudge", "scheduleSpacingSec": 10 } }, "batchObjects": { "summary": "Multiple object targets with per-item overrides", "value": { "targets": [ { "target": "+15551230001", "content": "VIP reminder 9am", "context": "VIP", "scheduledFor": 1730000000 }, { "target": "+15551230002", "content": "Standard reminder 10am" } ], "agentId": 1234 } } } } } } } }, "/api/v2/kb/knowledgebase/{kbId}/documents": { "get": { "tags": [ "KnowledgeBase" ], "summary": "Delete multiple documents", "description": "Deletes multiple documents from a knowledge base by their IDs, accessible to the authenticated user.", "parameters": [ { "name": "kbId", "in": "path", "required": true, "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "example": { "type": "string", "example": "kb-id-xxxx" } } }, "description": "The ID of the knowledge base" } ], "responses": { "204": { "description": "Successfully deleted" }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } } } } } }, "404": { "description": "One or more documents not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Some documents not found" }, "notFoundDocumentIds": { "type": "array", "items": { "type": "string", "example": "doc-id-54321" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documentIds": { "type": "array", "items": { "type": "string", "example": "doc-id-12345" }, "description": "An array of document IDs to delete" } }, "required": [ "documentIds" ] } } } } } }, "/api/v2/conversation/{roomId}/{uuid}": { "get": { "tags": [ "Messaging" ], "summary": "Fetch Conversation", "description": "Fetch specific conversation logs for a given room ID and UUID", "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Room Id of the conversation", "example": "3:15" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID of the conversation", "example": "uuid" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "success": { "description": "If request was successful", "type": "boolean", "example": "true" }, "message": { "description": "Success or Error Message", "type": "string", "example": "Success" }, "conversation": { "description": "Conversation logs", "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Hello World" }, "timestamp": { "type": "number", "example": 1630480000 } } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "query", "name": "token", "description": "Vida API Token" } } } }