{ "openapi": "3.0.3", "info": { "title": "SalesCaptain API Documentation Service", "description": "API Documentation Service for SalesCaptain platform.\nThis service provides endpoints for managing and retrieving company information for API documentation purposes.\n", "version": "0.1.0", "contact": { "name": "SalesCaptain API Team", "email": "support@salescaptain.com" }, "license": { "name": "Proprietary", "url": "https://salescaptain.com/license" } }, "servers": [ { "url": "https://api.salescaptain.com", "description": "Production server" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v1": { "get": { "summary": "Health check endpoint", "description": "Returns basic service information and health status", "operationId": "healthCheck", "tags": ["Health"], "security": [], "responses": { "200": { "description": "Service is running successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "SalesCaptain API [Service version - 0.1]" } } }, "example": { "message": "SalesCaptain API [Service version - 0.1]" } } } } } } }, "/v1/fetch-companies": { "get": { "summary": "Fetch companies for authenticated user", "description": "Retrieves a list of companies associated with the authenticated user's accounts.\nThis endpoint fetches company information from the main SalesCaptain API based on \nthe company IDs associated with the user's accounts.\n", "operationId": "fetchCompanies", "tags": ["Companies"], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Companies fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Companies fetched successfully!" }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } }, "example": { "message": "Companies fetched successfully!", "companies": [ { "company_id": "00000000-0000-0000-0000-000000000000", "name": "salescaptain", "company_type": "single", "status": "active" } ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/fetch-company/{company_id}": { "get": { "summary": "Fetch company by ID", "description": "Retrieves detailed information about a specific company by its unique identifier.\n", "operationId": "fetchCompanyById", "tags": ["Companies"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier for the company", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Company fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Company fetched successfully!" }, "company": { "$ref": "#/components/schemas/Company" } } }, "example": { "message": "Company fetched successfully!", "company": { "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Acme Corporation", "company_type": "parent", "status": "active" } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: company_id" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Problem encountered while fetching company!" } } } }, "403": { "description": "Access forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "You don't have access to view this company!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/fetch-all-accounts/{company_id}": { "get": { "summary": "Fetch all accounts for authenticated user", "description": "Retrieves a list of all accounts associated with the authenticated user for a specific company.\nReturns account details including access level, contact information, and last login time.\n", "operationId": "fetchAllAccounts", "tags": ["Accounts"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier for the company", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Accounts fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Accounts fetched successfully!" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/AccountDetail" } } } }, "example": { "message": "Accounts fetched successfully!", "accounts": [ { "account_id": "acc-1234-5678-90ab-cdef12345678", "access_level": "administrator", "last_login": "2026-03-12T10:30:00.000Z", "email": "john.doe@example.com", "mobile": "+1234567890", "first_name": "John", "last_name": "Doe" }, { "account_id": "acc-abcd-efgh-ijkl-mnop12345678", "access_level": "user", "last_login": "2026-03-10T14:45:00.000Z", "email": "jane.smith@example.com", "mobile": "+0987654321", "first_name": "Jane", "last_name": "Smith" } ] } } } }, "400": { "description": "Bad request - Missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: company_id" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/fetch-account/{account_id}": { "get": { "summary": "Fetch account by ID", "description": "Retrieves detailed information about a specific account by its unique identifier.\nReturns account details including access level, contact information, and last login time.\n", "operationId": "fetchAccountById", "tags": ["Accounts"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Unique identifier for the account", "schema": { "type": "string", "example": "acc-1234-5678-90ab-cdef12345678" } } ], "responses": { "200": { "description": "Account fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Account fetched successfully!" }, "account": { "$ref": "#/components/schemas/AccountDetail" } } }, "example": { "message": "Account fetched successfully!", "account": { "account_id": "acc-1234-5678-90ab-cdef12345678", "access_level": "administrator", "last_login": "2026-03-12T10:30:00.000Z", "email": "john.doe@example.com", "mobile": "+1234567890", "first_name": "John", "last_name": "Doe" } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: account_id" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Problem encountered while fetching account!" } } } }, "403": { "description": "Access forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "You don't have access to view this account!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/list-conversation-profiles/{company_id}": { "get": { "summary": "List conversation profiles for a company", "description": "Retrieves all conversation profiles associated with a specific company.\nConversation profiles represent communication channels like phone lines, email addresses, etc.\n", "operationId": "listConversationProfiles", "tags": ["Conversation Profiles"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier for the company", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Conversation profiles fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation profiles fetched successfully!" }, "account": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationProfile" } } } }, "example": { "message": "Conversation profiles fetched successfully!", "account": [ { "conversation_profile_id": "cp-1111-2222-3333-444455556666", "name": "Main Line", "number": "+14155551234", "email": "support@acme.com", "color": "#4A90D9" }, { "conversation_profile_id": "cp-7777-8888-9999-aaaabbbbcccc", "name": "Sales Line", "number": "+14155555678", "email": "sales@acme.com", "color": "#50C878" }, { "conversation_profile_id": "cp-dddd-eeee-ffff-000011112222", "name": "Email Channel", "number": null, "email": "info@acme.com", "color": "#FF6B6B" } ] } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: company_id" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/list-conversation-profile/{conversation_profile_id}": { "get": { "summary": "Get a specific conversation profile", "description": "Retrieves detailed information about a specific conversation profile by its unique identifier.\n", "operationId": "listConversationProfile", "tags": ["Conversation Profiles"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "conversation_profile_id", "in": "path", "required": true, "description": "Unique identifier for the conversation profile", "schema": { "type": "string", "example": "cp-1111-2222-3333-444455556666" } } ], "responses": { "200": { "description": "Conversation profile fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation profile fetched successfully!" }, "account": { "$ref": "#/components/schemas/ConversationProfile" } } }, "example": { "message": "Conversation profile fetched successfully!", "account": { "conversation_profile_id": "cp-1111-2222-3333-444455556666", "name": "Main Line", "number": "+14155551234", "email": "support@acme.com", "color": "#4A90D9" } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: conversation_profile_id" } } } }, "404": { "description": "Conversation profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Problem encountered while fetching conversation profiles!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/list-conversations/{company_id}": { "get": { "summary": "List conversations for a company (paginated)", "description": "Retrieves a paginated list of conversations associated with a specific company.\nSupports filtering, sorting, and pagination options.\n", "operationId": "listConversations", "tags": ["Conversations"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier for the company", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "page_number", "in": "query", "required": true, "description": "Page number for pagination (must be a positive integer)", "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "items_per_page", "in": "query", "required": false, "description": "Number of items per page (10-100, default 10)", "schema": { "type": "integer", "minimum": 10, "maximum": 100, "default": 10, "example": 10 } }, { "name": "sort_by", "in": "query", "required": false, "description": "Field to sort by", "schema": { "type": "string", "enum": ["last_update"], "example": "last_update" } }, { "name": "sort_dir", "in": "query", "required": false, "description": "Sort direction (default desc)", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc", "example": "desc" } }, { "name": "number", "in": "query", "required": false, "description": "Filter conversations by contact phone number", "schema": { "type": "string", "example": "+1234567890" } }, { "name": "email", "in": "query", "required": false, "description": "Filter conversations by contact email address", "schema": { "type": "string", "format": "email", "example": "john.doe@example.com" } }, { "name": "conversation_profile_id", "in": "query", "required": false, "description": "Filter conversations by conversation profile ID", "schema": { "type": "string", "format": "uuid", "example": "c3d4e5f6-a7b8-9012-cdef-123456789012" } }, { "name": "chat_status", "in": "query", "required": false, "description": "Filter conversations by chat status", "schema": { "type": "string", "enum": ["open", "closed"], "example": "open" } } ], "responses": { "200": { "description": "Conversations fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversations fetched successfully!" }, "conversations": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, "example": { "message": "Conversations fetched successfully!", "conversations": { "data": [ { "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contact_name": "John Doe", "contact_number": "+1234567890", "contact_email": "john.doe@example.com", "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "conversation_profile_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "conversation_profile_number": "+1987654321", "conversation_profile_email": "support@company.com", "last_message": "Hey, I need help with my order", "assigned_to": "d4e5f6a7-b8c9-0123-def1-234567890123", "updated_at": "2026-03-17T10:30:00.000Z", "created_at": "2026-03-15T08:00:00.000Z", "seen_by": "e5f6a7b8-c9d0-1234-ef12-345678901234", "is_chat_opened": true }, { "contact_id": "f6a7b8c9-d0e1-2345-f123-456789012345", "contact_name": "Jane Smith", "contact_number": "+1122334455", "contact_email": "jane.smith@example.com", "conversation_id": "a7b8c9d0-e1f2-3456-1234-567890123456", "conversation_profile_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "conversation_profile_number": "+1987654321", "conversation_profile_email": "support@company.com", "last_message": "Thanks for the update!", "assigned_to": null, "updated_at": "2026-03-16T14:20:00.000Z", "created_at": "2026-03-10T12:00:00.000Z", "seen_by": null, "is_chat_opened": false } ], "pagination": { "page_number": 1, "items_per_page": 10, "total_count": 25, "total_pages": 3 } } } } } }, "400": { "description": "Invalid or missing query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_page_number": { "summary": "Missing page number", "value": { "status": "failure", "error": "Please provide a valid page_number (must be a positive integer)" } }, "invalid_sort_by": { "summary": "Invalid sort_by value", "value": { "status": "failure", "error": "sort_by must be one of: last_update" } }, "invalid_number": { "summary": "Invalid number filter", "value": { "status": "failure", "error": "number must be a valid phone number" } }, "invalid_email": { "summary": "Invalid email filter", "value": { "status": "failure", "error": "email must be a valid email address" } }, "invalid_conversation_profile_id": { "summary": "Invalid conversation_profile_id filter", "value": { "status": "failure", "error": "conversation_profile_id must be a valid UUID" } }, "invalid_chat_status": { "summary": "Invalid chat_status filter", "value": { "status": "failure", "error": "chat_status must be one of: open, closed" } }, "missing_company_id": { "summary": "Missing company_id", "value": { "status": "failure", "error": "Required parameters missing: company_id" } } } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Problem encountered while listing conversations!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/fetch-conversation/{conversation_id}": { "get": { "summary": "Fetch a single conversation by ID", "description": "Retrieves detailed information about a specific conversation by its unique identifier.\n", "operationId": "fetchConversation", "tags": ["Conversations"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Unique identifier for the conversation", "schema": { "type": "string", "format": "uuid", "example": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } } ], "responses": { "200": { "description": "Conversation fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Conversation fetched successfully!" }, "conversation": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } } } }, "example": { "message": "Conversation fetched successfully!", "conversation": { "data": { "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contact_name": "John Doe", "contact_number": "+1234567890", "contact_email": "john.doe@example.com", "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "conversation_profile_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "conversation_profile_number": "+1987654321", "conversation_profile_email": "support@company.com", "last_message": "Hey, I need help with my order", "assigned_to": "d4e5f6a7-b8c9-0123-def1-234567890123", "updated_at": "2026-03-17T10:30:00.000Z", "created_at": "2026-03-15T08:00:00.000Z", "seen_by": "e5f6a7b8-c9d0-1234-ef12-345678901234", "is_chat_opened": true } } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: conversation_id" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Problem encountered while fetching conversation!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/fetch-messages/{company_id}/{conversation_id}": { "get": { "summary": "Fetch messages for a conversation (paginated)", "description": "Retrieves a paginated list of messages for a specific conversation within a company.\nSupports sorting by created_at, pagination options, and optional created_before / created_after filters.\n", "operationId": "fetchMessages", "tags": ["Conversations"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier for the company", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "conversation_id", "in": "path", "required": true, "description": "Unique identifier for the conversation", "schema": { "type": "string", "format": "uuid", "example": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } }, { "name": "page_number", "in": "query", "required": true, "description": "Page number for pagination (must be a positive integer)", "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "items_per_page", "in": "query", "required": false, "description": "Number of items per page (10-100, default 10)", "schema": { "type": "integer", "minimum": 10, "maximum": 100, "default": 10, "example": 10 } }, { "name": "sort_by", "in": "query", "required": false, "description": "Field to sort by", "schema": { "type": "string", "enum": ["created_at"], "example": "created_at" } }, { "name": "sort_dir", "in": "query", "required": false, "description": "Sort direction (default desc)", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc", "example": "desc" } }, { "name": "created_before", "in": "query", "required": false, "description": "Return only messages created before this ISO date-time", "schema": { "type": "string", "format": "date-time", "example": "2026-03-15T23:59:59.000Z" } }, { "name": "created_after", "in": "query", "required": false, "description": "Return only messages created after this ISO date-time", "schema": { "type": "string", "format": "date-time", "example": "2026-03-01T00:00:00.000Z" } } ], "responses": { "200": { "description": "Messages fetched successfully or error response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Messages fetched successfully!" }, "messages": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, { "$ref": "#/components/schemas/FailureResponse" } ] }, "examples": { "success": { "summary": "Successful response", "value": { "message": "Messages fetched successfully!", "messages": { "data": [ { "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contact_id": "f6a7b8c9-d0e1-2345-f123-456789012345", "conversation_profile_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "conversation_profile_email": "support@company.com", "conversation_profile_number": "+1987654321", "type_of_message": "sms_message", "direction": "inbound", "message": "Hi, I'd like to schedule an appointment.", "media": ["https://cdn.example.com/media/image1.jpg"], "call_status": null, "call_duration": null, "assigned_account_id": "d4e5f6a7-b8c9-0123-def1-234567890123", "created_at": "2026-03-15T08:00:00.000Z" }, { "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "message_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "contact_id": "f6a7b8c9-d0e1-2345-f123-456789012345", "conversation_profile_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "conversation_profile_email": "support@company.com", "conversation_profile_number": "+1987654321", "type_of_message": "call", "direction": "inbound", "message": null, "recording_url": "https://cdn.example.com/recordings/call123.mp3", "call_status": "completed", "call_duration": 125, "assigned_account_id": "d4e5f6a7-b8c9-0123-def1-234567890123", "created_at": "2026-03-15T08:05:00.000Z" } ], "pagination": { "page_number": 1, "items_per_page": 10, "total_count": 25, "total_pages": 3 } } } }, "missing_params": { "summary": "Missing company_id or conversation_id", "value": { "status": "failure", "error": "{\"is_error\":true,\"error\":\"company_id and conversation_id must be provided!\",\"message\":\"company_id and conversation_id must be provided!\"}", "message": "{\"is_error\":true,\"error\":\"company_id and conversation_id must be provided!\",\"message\":\"company_id and conversation_id must be provided!\"}" } }, "missing_pagination": { "summary": "Missing page or items_per_page", "value": { "status": "failure", "error": "{\"is_error\":true,\"error\":\"page and items_per_page are required\",\"message\":\"page and items_per_page are required\"}", "message": "{\"is_error\":true,\"error\":\"page and items_per_page are required\",\"message\":\"page and items_per_page are required\"}" } }, "conversation_not_found": { "summary": "Conversation not found", "value": { "status": "failure", "error": "{\"is_error\":true,\"error\":\"Conversation not found\",\"message\":\"Conversation not found\"}", "message": "{\"is_error\":true,\"error\":\"Conversation not found\",\"message\":\"Conversation not found\"}" } }, "company_not_found": { "summary": "Company not found", "value": { "status": "failure", "error": "Problem encountered while fetching messages!", "message": "Company not found" } }, "unexpected_error": { "summary": "Unexpected error (network, DB, etc.)", "value": { "status": "failure", "error": "Problem encountered while fetching messages!", "message": "connect ECONNREFUSED" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/fetch-message/{message_id}": { "get": { "summary": "Fetch a single message by ID", "description": "Retrieves detailed information about a specific message by its unique identifier.\n", "operationId": "fetchMessage", "tags": ["Conversations"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "Unique identifier for the message", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Message fetched successfully or error response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Message fetched successfully!" }, "data": { "$ref": "#/components/schemas/Message" } } }, { "$ref": "#/components/schemas/FailureResponse" } ] }, "examples": { "success": { "summary": "Successful response", "value": { "message": "Message fetched successfully!", "data": { "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contact_id": "f6a7b8c9-d0e1-2345-f123-456789012345", "conversation_profile_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "conversation_profile_email": "support@company.com", "conversation_profile_number": "+1987654321", "type_of_message": "sms_message", "direction": "inbound", "message": "Hi, I'd like to schedule an appointment.", "media": ["https://cdn.example.com/media/image1.jpg"], "call_status": null, "call_duration": null, "assigned_account_id": "d4e5f6a7-b8c9-0123-def1-234567890123", "created_at": "2026-03-15T08:00:00.000Z" } } }, "missing_message_id": { "summary": "Missing message_id", "value": { "status": "failure", "error": "{\"is_error\":true,\"error\":\"message_id must be provided!\",\"message\":\"message_id must be provided!\"}", "message": "{\"is_error\":true,\"error\":\"message_id must be provided!\",\"message\":\"message_id must be provided!\"}" } }, "message_not_found": { "summary": "Message not found", "value": { "status": "failure", "error": "{\"is_error\":true,\"error\":\"Message not found\",\"message\":\"Message not found\"}", "message": "{\"is_error\":true,\"error\":\"Message not found\",\"message\":\"Message not found\"}" } }, "conversation_not_found": { "summary": "Conversation not found", "value": { "status": "failure", "error": "{\"is_error\":true,\"error\":\"Conversation not found\",\"message\":\"Conversation not found\"}", "message": "{\"is_error\":true,\"error\":\"Conversation not found\",\"message\":\"Conversation not found\"}" } }, "company_api_error": { "summary": "Company API error", "value": { "status": "failure", "error": "Problem encountered while fetching message!", "message": "Company not found" } }, "unexpected_error": { "summary": "Unexpected error", "value": { "status": "failure", "error": "Problem encountered while fetching message!", "message": "connect ECONNREFUSED" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/send-message/{company_id}/{conversation_id}": { "post": { "summary": "Send a message in a conversation", "description": "Sends an outbound message in the given conversation for the specified company.\n`company_id` and `conversation_id` are taken from the URL path. `message_body` is required in the JSON body.\n`account_id` is resolved from the authenticated user's account that matches `company_id` (same as other company-scoped routes).\nThe request is forwarded to the chat service as a POST with `company_id` and `conversation_id` in the path.\n", "operationId": "sendMessage", "tags": ["Conversations"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier for the company", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "conversation_id", "in": "path", "required": true, "description": "Unique identifier for the conversation", "schema": { "type": "string", "format": "uuid", "example": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["message_body"], "properties": { "message_body": { "type": "string", "description": "Plain text body of the message to send", "example": "Hi — this is a test message from the api-doc send endpoint." } } }, "example": { "message_body": "Hi — this is a test message from the api-doc send endpoint." } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Message sent successfully!" }, "data": { "$ref": "#/components/schemas/SentMessage" } } }, "example": { "message": "Message sent successfully!", "data": { "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "author": "Jane Doe", "body": "Hi — this is a test message from the api-doc send endpoint.", "date_created": "2025-03-23T18:30:00.000Z", "is_me": true, "message_type": "sms_message", "sent_by_id": "d4e5f6a7-b8c9-0123-def1-234567890123", "sent_by_username": "Jane Doe", "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } }, "400": { "description": "Invalid request (missing fields, invalid IDs, or no account for company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_required": { "summary": "Missing conversation_id, account_id context, or message_body", "value": { "status": "failure", "error": "conversation_id, account_id, and message_body must be provided!" } }, "invalid_company_id": { "summary": "Invalid company UUID", "value": { "status": "failure", "error": "Invalid company ID" } }, "invalid_conversation_id": { "summary": "Invalid conversation UUID", "value": { "status": "failure", "error": "Invalid conversation ID" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/list-contacts/{company_id}": { "get": { "summary": "List contacts for a company (paginated)", "description": "Retrieves a paginated list of contacts associated with a specific company.\nSupports filtering, sorting, and pagination options.\n", "operationId": "listContacts", "tags": ["Contacts"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier for the company", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "page_number", "in": "query", "required": true, "description": "Page number for pagination (must be a positive integer)", "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "items_per_page", "in": "query", "required": false, "description": "Number of items per page (10-100, default 10)", "schema": { "type": "integer", "minimum": 10, "maximum": 100, "default": 10, "example": 10 } }, { "name": "sort_by", "in": "query", "required": false, "description": "Field to sort by", "schema": { "type": "string", "enum": ["name", "number", "email", "created_at"], "example": "created_at" } }, { "name": "sort_dir", "in": "query", "required": false, "description": "Sort direction (default desc)", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc", "example": "desc" } }, { "name": "filter", "in": "query", "required": false, "description": "Filter contacts by channel type", "schema": { "type": "string", "enum": ["phone", "email", "facebook", "instagram", "whatsapp"], "example": "phone" } } ], "responses": { "200": { "description": "Contacts fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Contacts fetched successfully!" }, "contacts": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, "example": { "message": "Contacts fetched successfully!", "contacts": { "data": [ { "contact_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "John Doe", "phone": "+14155551234", "email": "john.doe@example.com", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-02-20T14:45:00.000Z", "tags": ["VIP", "New Lead", "Follow Up"], "custom_fields": [ { "cf_name": "Industry", "cf_value": "Technology" }, { "cf_name": "Budget", "cf_value": "50000" }, { "cf_name": "Source", "cf_value": "Website" } ] }, { "contact_id": "c9d8e7f6-5a4b-3c2d-1e0f-9a8b7c6d5e4f", "name": "Jane Smith", "phone": "+14155559876", "email": "jane.smith@company.com", "created_at": "2024-01-20T08:15:00.000Z", "updated_at": "2024-03-01T09:30:00.000Z", "tags": ["Customer", "Premium"], "custom_fields": [ { "cf_name": "Industry", "cf_value": "Healthcare" }, { "cf_name": "Company Size", "cf_value": "100-500" } ] }, { "contact_id": "b8c7d6e5-4f3a-2b1c-0d9e-8f7a6b5c4d3e", "name": "Mike Johnson", "phone": "+14155554567", "email": null, "created_at": "2024-02-05T16:00:00.000Z", "updated_at": null, "tags": [], "custom_fields": [] } ], "pagination": { "page_number": 1, "items_per_page": 10, "total_count": 156, "total_pages": 16 } } } } } }, "400": { "description": "Invalid or missing query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_page_number": { "summary": "Missing page number", "value": { "status": "failure", "error": "Please provide a valid page_number (must be a positive integer)" } }, "invalid_sort_by": { "summary": "Invalid sort_by value", "value": { "status": "failure", "error": "sort_by must be one of: name, number, email, created_at" } }, "invalid_filter": { "summary": "Invalid filter value", "value": { "status": "failure", "error": "filter must be one of: phone, email, facebook, instagram, whatsapp" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/fetch-contact/{contact_id}": { "get": { "summary": "Fetch a single contact by ID", "description": "Retrieves detailed information about a specific contact by its unique identifier.\n", "operationId": "fetchContact", "tags": ["Contacts"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Unique identifier for the contact", "schema": { "type": "string", "format": "uuid", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } } ], "responses": { "200": { "description": "Contact fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact fetched successfully!" }, "contacts": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } }, "example": { "message": "Contact fetched successfully!", "contacts": { "data": { "contact_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "John Doe", "phone": "+14155551234", "email": "john.doe@example.com", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-02-20T14:45:00.000Z", "tags": ["VIP", "New Lead", "Follow Up"], "custom_fields": [ { "cf_name": "Industry", "cf_value": "Technology" }, { "cf_name": "Budget", "cf_value": "50000" }, { "cf_name": "Source", "cf_value": "Website" } ] } } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: contact_id" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Problem encountered while fetching contact!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/create-contact": { "post": { "summary": "Create a new contact", "description": "Creates a new contact for a specific company.\nAt least one of contact_phone or contact_email must be provided.\nUser must have 'contacts' access role to create contacts.\n", "operationId": "createContact", "tags": ["Contacts"], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the company", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "contact_name": { "type": "string", "description": "Full name of the contact", "example": "John Doe" }, "contact_phone": { "type": "string", "description": "Phone number of the contact (required if no email provided)", "example": "+14155551234" }, "contact_email": { "type": "string", "format": "email", "description": "Email address of the contact (required if no phone provided)", "example": "john.doe@example.com" }, "custom_fields": { "type": "array", "description": "Optional list of custom fields to set for the contact", "items": { "$ref": "#/components/schemas/CustomFieldInput" } } }, "required": ["company_id", "contact_name"] }, "examples": { "with_both": { "summary": "Contact with both phone and email", "value": { "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contact_name": "John Doe", "contact_phone": "+14155551234", "contact_email": "john.doe@example.com" } }, "with_phone_only": { "summary": "Contact with phone only", "value": { "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contact_name": "Jane Smith", "contact_phone": "+14155559876" } }, "with_email_only": { "summary": "Contact with email only", "value": { "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contact_name": "Mike Johnson", "contact_email": "mike.johnson@example.com" } }, "with_custom_fields": { "summary": "Contact with custom fields", "value": { "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "contact_name": "John Doe", "contact_phone": "+14155551234", "contact_email": "john.doe@example.com", "custom_fields": [ { "cf_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a", "cf_value": "Technology" }, { "cf_id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b", "cf_value": "50000" } ] } } } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact created successfully!" }, "contact": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactCreated" } } } } }, "example": { "message": "Contact created successfully!", "contact": { "data": { "contact_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "John Doe", "phone": "+14155551234", "email": "john.doe@example.com", "conversation_id": "c8b7a6d5-e4f3-2c1b-0a9e-8d7c6b5a4f3e", "created_at": "2024-03-13T10:30:00.000Z", "updated_at": "2024-03-13T10:30:00.000Z", "custom_fields": [ { "cf_name": "Industry", "cf_value": "Technology" }, { "cf_name": "Budget", "cf_value": "50000" } ] } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_company_id": { "summary": "Missing company_id", "value": { "status": "failure", "error": "company_id is required" } }, "missing_contact_info": { "summary": "Missing phone and email", "value": { "status": "failure", "error": "At least one of contact_phone or contact_email must be provided" } }, "invalid_custom_field": { "summary": "Invalid or inactive custom field for company", "value": { "status": "failure", "error": "Invalid or inactive custom field for this company: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a" } } } } } }, "403": { "description": "Access forbidden or permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "You don't have permission to create contact!" } } } }, "409": { "description": "Conflict - Contact already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Contact with this phone already exists!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/update-contact/{contact_id}": { "put": { "summary": "Update an existing contact", "description": "Updates an existing contact's information.\nAt least one of name, phone, email, or custom_fields must be provided.\nUser must have 'contacts' access role to update contacts.\n", "operationId": "updateContact", "tags": ["Contacts"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Unique identifier for the contact to update", "schema": { "type": "string", "format": "uuid", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the company (required)", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "description": "Updated name of the contact", "example": "John Smith" }, "phone": { "type": "string", "nullable": true, "description": "Updated phone number (set to empty string to remove)", "example": "+14155559999" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Updated email address (set to empty string to remove)", "example": "john.smith@newcompany.com" }, "custom_fields": { "type": "array", "description": "Custom fields to update", "items": { "$ref": "#/components/schemas/CustomFieldInput" } } }, "required": ["company_id"] }, "examples": { "update_name_only": { "summary": "Update contact name only", "value": { "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "John Smith" } }, "update_contact_info": { "summary": "Update phone and email", "value": { "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "phone": "+14155559999", "email": "john.smith@newcompany.com" } }, "update_custom_fields": { "summary": "Update custom fields", "value": { "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "custom_fields": [ { "cf_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a", "cf_value": "Healthcare" }, { "cf_id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b", "cf_value": "75000" } ] } }, "update_all": { "summary": "Update all fields", "value": { "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "John Smith", "phone": "+14155559999", "email": "john.smith@newcompany.com", "custom_fields": [ { "cf_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a", "cf_value": "Healthcare" }, { "cf_id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b", "cf_value": "75000" } ] } } } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact updated successfully!" }, "contact": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } }, "example": { "message": "Contact updated successfully!", "contact": { "data": { "contact_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "John Smith", "phone": "+14155559999", "email": "john.smith@newcompany.com", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-03-13T14:45:00.000Z", "custom_fields": [ { "cf_name": "Industry", "cf_value": "Healthcare" }, { "cf_name": "Budget", "cf_value": "75000" } ] } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_company_id": { "summary": "Missing company_id", "value": { "status": "failure", "error": "company_id is required" } }, "missing_update_fields": { "summary": "No update fields provided", "value": { "status": "failure", "error": "At least one of name, phone, email, or custom_fields must be provided" } }, "invalid_phone": { "summary": "Invalid phone format", "value": { "status": "failure", "error": "phone must be a valid phone number (e.g., +14155551234)" } }, "invalid_email": { "summary": "Invalid email format", "value": { "status": "failure", "error": "email must be a valid email address" } } } } } }, "403": { "description": "Access forbidden or permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "You don't have permission to update contact!" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Problem encountered while updating contact!" } } } }, "409": { "description": "Conflict - Duplicate contact info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "duplicate_phone": { "summary": "Phone already exists", "value": { "status": "failure", "error": "Contact with this phone already exists!" } }, "duplicate_email": { "summary": "Email already exists", "value": { "status": "failure", "error": "Contact with this email already exists!" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/delete-contact/{company_id}/{contact_id}": { "delete": { "summary": "Delete a contact", "description": "Permanently deletes a contact from the system.\nUser must have 'contacts' access role to delete contacts.\n", "operationId": "deleteContact", "tags": ["Contacts"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier for the company", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, { "name": "contact_id", "in": "path", "required": true, "description": "Unique identifier for the contact to delete", "schema": { "type": "string", "format": "uuid", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } } ], "responses": { "200": { "description": "Contact deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact deleted successfully!" }, "data": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "ID of the deleted contact", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "message": { "type": "string", "example": "Contact deleted successfully" } } } } }, "example": { "message": "Contact deleted successfully!", "data": { "contact_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "message": "Contact deleted successfully" } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: contact_id" } } } }, "403": { "description": "Access forbidden or permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "You don't have permission to delete contact!" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Problem encountered while deleting contact!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/list-custom-fields/{company_id}": { "get": { "summary": "List all custom fields for a company", "description": "Retrieves all custom field definitions associated with a specific company.\nCustom fields allow companies to store additional contact information.\n", "operationId": "listCustomFields", "tags": ["Custom Fields"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier for the company", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Custom fields fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Custom fields fetched successfully!" }, "custom_fields": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldDefinition" } } } } } }, "example": { "message": "Custom fields fetched successfully!", "custom_fields": { "data": [ { "cf_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a", "cf_name": "industry", "cf_label": "Industry", "cf_datatype": "text", "cf_description": "Customer's industry sector", "created_at": "2024-01-10T09:00:00.000Z", "updated_at": "2024-01-15T11:30:00.000Z" }, { "cf_id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b", "cf_name": "budget", "cf_label": "Budget", "cf_datatype": "number", "cf_description": "Customer's budget range", "created_at": "2024-01-12T14:00:00.000Z", "updated_at": null }, { "cf_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c", "cf_name": "company_size", "cf_label": "Company Size", "cf_datatype": "dropdown", "cf_description": "Number of employees", "created_at": "2024-01-20T10:15:00.000Z", "updated_at": "2024-02-01T08:45:00.000Z" } ] } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: company_id" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/list-custom-field/{custom_field_id}": { "get": { "summary": "Get a single custom field by ID", "description": "Retrieves detailed information about a specific custom field definition by its unique identifier.\n", "operationId": "listCustomField", "tags": ["Custom Fields"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "custom_field_id", "in": "path", "required": true, "description": "Unique identifier for the custom field", "schema": { "type": "string", "format": "uuid", "example": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a" } } ], "responses": { "200": { "description": "Custom field fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Custom field fetched successfully!" }, "custom_field": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDefinition" } } } } }, "example": { "message": "Custom field fetched successfully!", "custom_field": { "data": { "cf_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a", "cf_name": "industry", "cf_label": "Industry", "cf_datatype": "text", "cf_description": "Customer's industry sector", "created_at": "2024-01-10T09:00:00.000Z", "updated_at": "2024-01-15T11:30:00.000Z" } } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Required parameters missing: custom_field_id" } } } }, "404": { "description": "Custom field not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "failure", "error": "Problem encountered while fetching custom field!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Authentication token required for accessing protected endpoints.\nThe token should be obtained from the main SalesCaptain authentication service.\n" } }, "schemas": { "Company": { "type": "object", "description": "Company information object", "properties": { "company_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the company", "example": "00000000-0000-0000-0000-000000000000" }, "name": { "type": "string", "description": "Company name", "example": "salescaptain" }, "company_type": { "type": "string", "description": "Type of the company in the hierarchy", "enum": ["parent", "child", "single"], "example": "single" }, "status": { "type": "string", "description": "Current status of the company", "enum": ["active", "paused"], "example": "active" } }, "required": ["company_id", "name", "company_type", "status"] }, "Address": { "type": "object", "description": "Address information", "properties": { "street": { "type": "string", "description": "Street address", "example": "123 Main Street" }, "city": { "type": "string", "description": "City name", "example": "New York" }, "state": { "type": "string", "description": "State or province", "example": "NY" }, "postal_code": { "type": "string", "description": "Postal or ZIP code", "example": "10001" }, "country": { "type": "string", "description": "Country name", "example": "United States" } } }, "Error": { "type": "object", "description": "Error response object", "properties": { "error": { "type": "string", "description": "Error message", "example": "Invalid request parameters" }, "code": { "type": "string", "description": "Error code for programmatic handling", "example": "INVALID_PARAMS" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the error occurred", "example": "2023-12-01T10:30:00Z" }, "path": { "type": "string", "description": "API endpoint path where the error occurred", "example": "/v1/fetch-companies" } }, "required": ["error"] }, "User": { "type": "object", "description": "Authenticated user information", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique user identifier", "example": "987fcdeb-51a2-43d1-9f12-345678901234" }, "email": { "type": "string", "format": "email", "description": "User email address", "example": "user@example.com" }, "accounts": { "type": "array", "description": "List of accounts associated with the user", "items": { "$ref": "#/components/schemas/Account" } } }, "required": ["id", "email", "accounts"] }, "Account": { "type": "object", "description": "User account information", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique account identifier", "example": "456e7890-f12b-34c5-d678-901234567890" }, "company_id": { "type": "string", "format": "uuid", "description": "Associated company identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "role": { "type": "string", "description": "User role within the account", "example": "admin" }, "permissions": { "type": "array", "description": "List of permissions for this account", "items": { "type": "string" }, "example": ["read", "write", "admin"] } }, "required": ["id", "company_id"] }, "AccountDetail": { "type": "object", "description": "Detailed account information", "properties": { "account_id": { "type": "string", "description": "Unique account identifier", "example": "acc-1234-5678-90ab-cdef12345678" }, "access_level": { "type": "string", "description": "User's access level within the account", "enum": ["owner", "administrator", "user"], "example": "administrator" }, "last_login": { "type": "string", "format": "date-time", "description": "Timestamp of the user's last login", "example": "2026-03-12T10:30:00.000Z" }, "email": { "type": "string", "format": "email", "description": "User's email address", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "User's mobile phone number", "example": "+1234567890" }, "first_name": { "type": "string", "description": "User's first name", "example": "John" }, "last_name": { "type": "string", "description": "User's last name", "example": "Doe" } }, "required": ["account_id", "access_level", "email", "first_name", "last_name"] }, "ConversationProfile": { "type": "object", "description": "Conversation profile representing a communication channel", "properties": { "conversation_profile_id": { "type": "string", "description": "Unique identifier for the conversation profile", "example": "cp-1111-2222-3333-444455556666" }, "name": { "type": "string", "description": "Display name for the conversation profile", "example": "Main Line" }, "number": { "type": "string", "nullable": true, "description": "Phone number associated with the profile (null if not applicable)", "example": "+14155551234" }, "email": { "type": "string", "format": "email", "description": "Email address associated with the profile", "example": "support@acme.com" }, "color": { "type": "string", "description": "Hex color code for UI display", "example": "#4A90D9" } }, "required": ["conversation_profile_id", "name"] }, "Contact": { "type": "object", "description": "Contact information object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the contact", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "Contact's full name", "example": "John Doe" }, "phone": { "type": "string", "nullable": true, "description": "Contact's phone number", "example": "+14155551234" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Contact's email address", "example": "john.doe@example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the contact was created", "example": "2024-01-15T10:30:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the contact was last updated", "example": "2024-02-20T14:45:00.000Z" }, "tags": { "type": "array", "description": "List of tags associated with the contact", "items": { "type": "string" }, "example": ["VIP", "New Lead", "Follow Up"] }, "custom_fields": { "type": "array", "description": "List of custom fields for the contact", "items": { "$ref": "#/components/schemas/CustomField" } } }, "required": ["contact_id", "name"] }, "Conversation": { "type": "object", "description": "Conversation information object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the contact", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "contact_name": { "type": "string", "description": "Contact's full name", "example": "John Doe" }, "contact_number": { "type": "string", "nullable": true, "description": "Contact's phone number", "example": "+1234567890" }, "contact_email": { "type": "string", "format": "email", "nullable": true, "description": "Contact's email address", "example": "john.doe@example.com" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the conversation", "example": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, "conversation_profile_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the conversation profile", "example": "c3d4e5f6-a7b8-9012-cdef-123456789012" }, "conversation_profile_number": { "type": "string", "nullable": true, "description": "Phone number of the conversation profile", "example": "+1987654321" }, "conversation_profile_email": { "type": "string", "format": "email", "nullable": true, "description": "Email address of the conversation profile", "example": "support@company.com" }, "last_message": { "type": "string", "nullable": true, "description": "Content of the last message in the conversation", "example": "Hey, I need help with my order" }, "assigned_to": { "type": "string", "format": "uuid", "nullable": true, "description": "Account ID of the assigned agent (null if unassigned)", "example": "d4e5f6a7-b8c9-0123-def1-234567890123" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the conversation was last updated", "example": "2026-03-17T10:30:00.000Z" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the conversation was created", "example": "2026-03-15T08:00:00.000Z" }, "seen_by": { "type": "string", "format": "uuid", "nullable": true, "description": "Account ID of the last agent who viewed the conversation (null if unseen)", "example": "e5f6a7b8-c9d0-1234-ef12-345678901234" }, "is_chat_opened": { "type": "boolean", "description": "Whether the chat is currently open", "example": true } }, "required": ["contact_id", "contact_name", "conversation_id", "conversation_profile_id", "updated_at", "created_at", "is_chat_opened"] }, "Message": { "type": "object", "description": "Message information object.\n`media` and `recording_url` are mutually exclusive by presence based on `type_of_message`:\nfor non-call messages the response includes `media` and omits `recording_url`;\nfor call messages the response includes `recording_url` and omits `media`.\n", "properties": { "conversation_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the conversation", "example": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, "message_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the message", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "contact_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the contact", "example": "f6a7b8c9-d0e1-2345-f123-456789012345" }, "conversation_profile_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the conversation profile", "example": "c3d4e5f6-a7b8-9012-cdef-123456789012" }, "conversation_profile_email": { "type": "string", "format": "email", "nullable": true, "description": "Email address of the conversation profile", "example": "support@company.com" }, "conversation_profile_number": { "type": "string", "nullable": true, "description": "Phone number of the conversation profile", "example": "+1987654321" }, "type_of_message": { "type": "string", "description": "Type of the message", "enum": ["sms_message", "email_message", "ig_message", "fb_message", "web_chat_message", "call"], "example": "sms_message" }, "direction": { "type": "string", "description": "Direction of the message", "enum": ["inbound", "outbound"], "example": "inbound" }, "message": { "type": "string", "nullable": true, "description": "Message body/text content", "example": "Hi, I'd like to schedule an appointment." }, "media": { "type": "array", "description": "Media attachments (e.g. image/file URLs).\nPresent only when type_of_message is not call. Omitted for call messages (replaced by recording_url).\n", "items": { "type": "string" }, "example": ["https://cdn.example.com/media/image1.jpg"] }, "recording_url": { "type": "string", "format": "uri", "description": "Call recording URL.\nPresent only when type_of_message is call. Omitted for non-call messages (replaced by media).\n", "example": "https://cdn.example.com/recordings/call123.mp3" }, "call_status": { "type": "string", "nullable": true, "description": "Status of the call when the message is a call (null for non-call messages)", "example": "completed" }, "call_duration": { "type": "integer", "nullable": true, "description": "Call duration in seconds when the message is a call (null for non-call messages)", "example": 125 }, "assigned_account_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Account ID of the agent assigned at the time of the message", "example": "d4e5f6a7-b8c9-0123-def1-234567890123" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the message was created", "example": "2026-03-15T08:00:00.000Z" } }, "required": ["conversation_id", "message_id", "contact_id", "conversation_profile_id", "type_of_message", "direction", "created_at"] }, "SentMessage": { "type": "object", "description": "Message as returned after a successful send (chat service response)", "properties": { "conversation_id": { "type": "string", "format": "uuid", "example": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, "author": { "type": "string", "description": "Display name of the message author", "example": "Jane Doe" }, "body": { "type": "string", "description": "Message text", "example": "Hi — this is a test message from the api-doc send endpoint." }, "date_created": { "type": "string", "format": "date-time", "example": "2025-03-23T18:30:00.000Z" }, "is_me": { "type": "boolean", "description": "Whether the message was sent by the authenticated account", "example": true }, "message_type": { "type": "string", "description": "Channel/type of the message", "example": "sms_message" }, "sent_by_id": { "type": "string", "description": "Account ID of the sender", "example": "d4e5f6a7-b8c9-0123-def1-234567890123" }, "sent_by_username": { "type": "string", "example": "Jane Doe" }, "message_id": { "type": "string", "description": "Unique message identifier from the chat service", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "required": [ "conversation_id", "author", "body", "date_created", "is_me", "message_type", "sent_by_id", "sent_by_username", "message_id" ] }, "FailureResponse": { "type": "object", "description": "Standard failure response returned with HTTP 200 status", "properties": { "status": { "type": "string", "description": "Always \"failure\" for error responses", "example": "failure" }, "error": { "type": "string", "description": "Error description (may contain stringified JSON)", "example": "Problem encountered while fetching messages!" }, "message": { "type": "string", "description": "Error message (may contain stringified JSON)", "example": "Company not found" }, "trace": { "type": "array", "description": "Stack trace (included in non-production environments)", "items": { "type": "string" } }, "request": { "type": "object", "description": "Original request details", "properties": { "body": { "type": "object" }, "method": { "type": "string" }, "url": { "type": "string" }, "params": { "type": "object" } } } }, "required": ["status", "error", "message"] }, "CustomField": { "type": "object", "description": "Custom field key-value pair (response format)", "properties": { "cf_name": { "type": "string", "description": "Custom field name", "example": "Industry" }, "cf_value": { "type": "string", "description": "Custom field value", "example": "Technology" } }, "required": ["cf_name", "cf_value"] }, "CustomFieldInput": { "type": "object", "description": "Custom field input for create/update operations", "properties": { "cf_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the custom field", "example": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a" }, "cf_value": { "type": "string", "description": "Value to set for the custom field", "example": "Technology" } }, "required": ["cf_id", "cf_value"] }, "Pagination": { "type": "object", "description": "Pagination metadata", "properties": { "page_number": { "type": "integer", "description": "Current page number", "example": 1 }, "items_per_page": { "type": "integer", "description": "Number of items per page", "example": 10 }, "total_count": { "type": "integer", "description": "Total number of items across all pages", "example": 156 }, "total_pages": { "type": "integer", "description": "Total number of pages", "example": 16 } }, "required": ["page_number", "items_per_page", "total_count", "total_pages"] }, "ContactCreated": { "type": "object", "description": "Created contact response object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the contact", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "Contact's full name", "example": "John Doe" }, "phone": { "type": "string", "nullable": true, "description": "Contact's phone number", "example": "+14155551234" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Contact's email address", "example": "john.doe@example.com" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Associated conversation identifier", "example": "c8b7a6d5-e4f3-2c1b-0a9e-8d7c6b5a4f3e" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the contact was created", "example": "2024-03-13T10:30:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the contact was last updated", "example": "2024-03-13T10:30:00.000Z" }, "custom_fields": { "type": "array", "description": "List of custom fields for the contact", "items": { "$ref": "#/components/schemas/CustomField" } } }, "required": ["contact_id", "name", "conversation_id", "created_at"] }, "CustomFieldDefinition": { "type": "object", "description": "Custom field definition object", "properties": { "cf_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the custom field", "example": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a" }, "cf_name": { "type": "string", "description": "Internal name of the custom field (lowercase, no spaces)", "example": "industry" }, "cf_label": { "type": "string", "description": "Display label for the custom field", "example": "Industry" }, "cf_datatype": { "type": "string", "description": "Data type of the custom field", "enum": ["text", "number", "dropdown", "date", "checkbox", "textarea"], "example": "text" }, "cf_description": { "type": "string", "nullable": true, "description": "Description of the custom field's purpose", "example": "Customer's industry sector" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the custom field was created", "example": "2024-01-10T09:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the custom field was last updated", "example": "2024-01-15T11:30:00.000Z" } }, "required": ["cf_id", "cf_name", "cf_label", "cf_datatype"] } }, "responses": { "UnauthorizedError": { "description": "Authentication token is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized access", "code": "UNAUTHORIZED", "timestamp": "2023-12-01T10:30:00Z", "path": "/v1/fetch-companies" } } } }, "ForbiddenError": { "description": "Access forbidden - valid token but insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Forbidden access", "code": "FORBIDDEN", "timestamp": "2023-12-01T10:30:00Z", "path": "/v1/fetch-companies" } } } }, "RateLimitError": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Too many requests, please try again later", "code": "RATE_LIMIT_EXCEEDED", "timestamp": "2023-12-01T10:30:00Z", "path": "/v1/fetch-companies" } } }, "headers": { "X-RateLimit-Limit": { "description": "Request limit per time window", "schema": { "type": "integer", "example": 30 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Time when the rate limit resets", "schema": { "type": "integer", "example": 1701425400 } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Problem encountered while fetching companies!", "code": "INTERNAL_ERROR", "timestamp": "2023-12-01T10:30:00Z", "path": "/v1/fetch-companies" } } } } }, "examples": { "SuccessfulCompanyFetch": { "summary": "Successful company fetch response", "value": { "message": "Companies fetched successfully!", "companies": [ { "company_id": "00000000-0000-0000-0000-000000000000", "name": "salescaptain", "company_type": "single", "status": "active" } ] } } } }, "tags": [ { "name": "Health", "description": "Service health and status endpoints" }, { "name": "Companies", "description": "Company management and retrieval operations" }, { "name": "Accounts", "description": "Account management and retrieval operations" }, { "name": "Conversation Profiles", "description": "Conversation profile management for communication channels" }, { "name": "Conversations", "description": "Conversation management and retrieval operations" }, { "name": "Contacts", "description": "Contact management and retrieval operations" }, { "name": "Custom Fields", "description": "Custom field definition management" } ], "externalDocs": { "description": "SalesCaptain API Documentation", "url": "https://docs.salescaptain.com" } }