Best regards,
John Doe
Hi {{contact.firstName}},
Thank you for your interest in {{company.name}}. We're excited to help you grow your business!
Best regards,
{{emailAccount.fullName}}
Hi {{contact.firstName}},
Thank you for joining {{company.name}}! We've updated our welcome message.
", "subjectTemplate": "Updated: Welcome to {{company.name}}!", "fromTemplate": "{{emailAccount.fullName}} <{{emailAccount.email}}>", "sendingPeriod": 0, "type": "initial", "sequence": 1 } } } }, "responses": { "200": { "description": "Email template updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "bodyTemplate": { "type": "string" }, "subjectTemplate": { "type": "string" }, "fromTemplate": { "type": "string" }, "sendingPeriod": { "type": "integer" }, "type": { "type": "string" }, "sequence": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "example": { "_id": "507f1f77bcf86cd799439012", "name": "Updated Welcome Email", "bodyTemplate": "Hi {{contact.firstName}},
Thank you for joining {{company.name}}!
", "subjectTemplate": "Updated: Welcome to {{company.name}}!", "fromTemplate": "{{emailAccount.fullName}} <{{emailAccount.email}}>", "sendingPeriod": 0, "type": "initial", "sequence": 1, "updatedAt": "2024-01-02T00:00:00.000Z" } } } }, "400": { "description": "Template rendering error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "Invalid template syntax in bodyTemplate" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Template validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "errors": { "type": "object" } } }, "example": { "status": "Template validation failed", "errors": { "bodyTemplate": "Unexpected token 'contact'" } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "update_campaign_step" } }, "/admin/email-templates": { "get": { "summary": "Get templates for email campaign", "description": "Retrieves all email templates associated with a specific email campaign", "tags": [ "Email Templates" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "query", "name": "emailCampaignId", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Email campaign ID to get templates for", "example": "507f1f77bcf86cd799439011" } ], "responses": { "200": { "description": "Successfully retrieved email templates", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "sequence", "followup", "initial" ] }, "subjectTemplate": { "type": "string" }, "bodyTemplate": { "type": "string" }, "fromTemplate": { "type": "string" }, "sendingPeriod": { "type": "integer", "description": "Days to wait before sending this template" }, "sequence": { "type": "integer", "description": "Order of template in campaign" }, "emailCampaignId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "example": [ { "_id": "507f1f77bcf86cd799439012", "name": "Welcome Email", "type": "initial", "subjectTemplate": "Welcome to {{company.name}}, {{contact.firstName}}!", "bodyTemplate": "Hi {{contact.firstName}},
Welcome to our platform!
", "fromTemplate": "{{emailAccount.fullName}} <{{emailAccount.email}}>", "sendingPeriod": 0, "sequence": 1, "emailCampaignId": "507f1f77bcf86cd799439011", "createdAt": "2024-01-01T00:00:00.000Z" }, { "_id": "507f1f77bcf86cd799439013", "name": "Follow Up", "type": "followup", "subjectTemplate": "Following up on our previous conversation", "bodyTemplate": "Hi {{contact.firstName}},
Just following up...
", "fromTemplate": "{{emailAccount.fullName}} <{{emailAccount.email}}>", "sendingPeriod": 3, "sequence": 2, "emailCampaignId": "507f1f77bcf86cd799439011", "createdAt": "2024-01-01T00:00:00.000Z" } ] } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error" }, "500": { "description": "Server error" } }, "x-mcp-tool": "get_campaign" }, "post": { "summary": "Create email template", "description": "Creates a new email template with body, subject, and sending period configuration. Templates support Twig templating variables.", "tags": [ "Email Templates" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bodyTemplate", "fromTemplate", "subjectTemplate", "type", "name", "websiteId", "emailCampaignId", "sendingPeriod" ], "properties": { "name": { "type": "string", "description": "Template name for identification", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "initial", "followup", "sequence" ], "description": "Type of email template" }, "bodyTemplate": { "type": "string", "description": "HTML email body with Twig variables (e.g., {{contact.firstName}}, {{company.name}})" }, "subjectTemplate": { "type": "string", "description": "Email subject line with Twig variables", "maxLength": 200 }, "fromTemplate": { "type": "string", "description": "From field template with variables", "maxLength": 100 }, "sendingPeriod": { "type": "integer", "description": "Number of days to wait before sending this template", "minimum": 0, "maximum": 365 }, "websiteId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Website ID to associate template with" }, "emailCampaignId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Email campaign ID to add template to" }, "sequence": { "type": "integer", "description": "Order of template in campaign sequence", "minimum": 1 } } }, "example": { "name": "Welcome Email", "type": "initial", "bodyTemplate": "Hi {{contact.firstName}},
Welcome to {{company.name}}! We're excited to help you grow your business.
Best regards,
{{emailAccount.fullName}}
Hi {{contact.firstName}},
Welcome to {{company.name}}!
", "subjectTemplate": "Welcome to {{company.name}}, {{contact.firstName}}!", "fromTemplate": "{{emailAccount.fullName}} <{{emailAccount.email}}>", "sendingPeriod": 0, "sequence": 1, "emailCampaignId": "507f1f77bcf86cd799439011", "createdAt": "2024-01-01T00:00:00.000Z" } } } } }, "400": { "description": "Template rendering error - invalid Twig syntax", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "Template validation failed" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error or template validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] }, "errors": { "type": "object", "description": "Template-specific validation errors" } } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "add_campaign_step" } }, "/admin/email-templates-reorder": { "put": { "summary": "Reorder template sequence", "description": "Changes the order of email templates within a campaign to control sending sequence", "tags": [ "Email Templates" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "campaignId", "emailTemplates" ], "properties": { "campaignId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Email campaign ID containing the templates" }, "emailTemplates": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Template ID" }, "sequence": { "type": "integer", "description": "New sequence number" } } }, "description": "Array of templates with new sequence order", "minItems": 1 } } }, "example": { "campaignId": "507f1f77bcf86cd799439011", "emailTemplates": [ { "_id": "507f1f77bcf86cd799439012", "sequence": 2 }, { "_id": "507f1f77bcf86cd799439013", "sequence": 1 }, { "_id": "507f1f77bcf86cd799439014", "sequence": 3 } ] } } } }, "responses": { "200": { "description": "Template sequence reordered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "Templates sequence reoredered successfully" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error - missing campaignId or emailTemplates array", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "object" } } } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "reorder_campaign_steps" } }, "/admin/filters/{id}": { "delete": { "summary": "Delete filter", "description": "Permanently deletes a saved filter", "tags": [ "Filters" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Filter ID to delete", "example": "507f1f77bcf86cd799439030" } ], "responses": { "200": { "description": "Filter deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "successful" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Filter not found or couldn't be deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "We couldn't delete the filter" } } } }, "405": { "description": "Validation error - missing filter ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "object" } } } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "delete_filter" }, "patch": { "summary": "Update a saved filter (e.g. toggle favorite)", "description": "Updates an existing saved filter. Currently supports toggling the\n`isFavorite` flag. When `isFavorite` is set to true, all other filters\nbelonging to the same website are atomically cleared so only one\nfavorite segment exists per website.\n", "tags": [ "Filters" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isFavorite": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated filter" } }, "x-mcp-tool": "update_filter" } }, "/admin/filters": { "get": { "summary": "Get saved filters for website", "description": "Retrieves all saved filters for a specific website to quickly access common lead queries", "tags": [ "Filters" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "query", "name": "websiteId", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Website ID to get filters for", "example": "601733dbcedff50114a599f6" } ], "responses": { "200": { "description": "Successfully retrieved filters", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string", "description": "Display name for the filter" }, "url": { "type": "string", "description": "URL with query parameters for the filter" }, "website": { "type": "string", "description": "Associated website ID" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "example": [ { "_id": "507f1f77bcf86cd799439030", "name": "High-Value Prospects", "url": "/admin/leads?score=high&industry=technology", "website": "601733dbcedff50114a599f6", "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" }, { "_id": "507f1f77bcf86cd799439031", "name": "Recent Visitors", "url": "/admin/leads?days=7&status=new", "website": "601733dbcedff50114a599f6", "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" } ] } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error - invalid or missing websiteId", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "object" } } } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "list_filters" }, "post": { "summary": "Create new filter with name and URL", "description": "Creates a saved filter to quickly access specific lead queries and views", "tags": [ "Filters" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "websiteId", "name", "url" ], "properties": { "websiteId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Website ID to associate the filter with" }, "name": { "type": "string", "description": "Display name for the filter", "minLength": 1, "maxLength": 100, "example": "High-Value Prospects" }, "url": { "type": "string", "description": "URL with query parameters defining the filter criteria", "example": "/admin/leads?score=high&industry=technology&dateFrom=2024-01-01" } } }, "example": { "websiteId": "601733dbcedff50114a599f6", "name": "Enterprise Technology Leads", "url": "/admin/leads?industry=technology&company_size=large&score=high" } } } }, "responses": { "200": { "description": "Filter created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "description": "URL with dateFrom and dateTo parameters removed for reusability" }, "website": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "example": { "_id": "507f1f77bcf86cd799439032", "name": "Enterprise Technology Leads", "url": "/admin/leads?industry=technology&company_size=large&score=high", "website": "601733dbcedff50114a599f6", "createdAt": "2024-01-02T00:00:00.000Z", "updatedAt": "2024-01-02T00:00:00.000Z" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error - missing required fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "object" } } } } } } }, "500": { "description": "Server error during filter creation" } }, "x-mcp-tool": "create_filter" } }, "/admin/intent-topics": { "delete": { "summary": "Unsubscribe from an intent topic", "description": "Permanently removes a website's subscription to an intent topic. No further leads will be\ndelivered for this topic after deletion.\n\n**Important:** existing leads that already carry this topic in their `intentTopics` array\nare **not** deleted — they remain in your dashboard for historical reference.\n\nIf you only want to temporarily stop delivery, use `PATCH /admin/intent-topics` with\n`paused: true` instead — this preserves counters and can be reversed.\n\nParameters may be passed as query params or in the request body.\n", "tags": [ "Intent Topics" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "websiteId", "schema": { "type": "string" }, "description": "ID of the website (can also be sent in the request body)" }, { "in": "query", "name": "topicSlug", "schema": { "type": "string" }, "description": "Slug of the topic to unsubscribe from (can also be sent in the request body)" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "websiteId": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "topicSlug": { "type": "string", "example": "crm-software-buyers" } } } } } }, "responses": { "200": { "description": "Subscription deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "topicSlug": { "type": "string", "example": "crm-software-buyers" } } } } } } } }, "400": { "description": "Invalid websiteId" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Intent Signals feature not enabled for this website" }, "404": { "description": "Subscription not found" }, "500": { "description": "Server error" } }, "x-mcp-tool": "delete_intent_topic" }, "get": { "summary": "List intent topic subscriptions", "description": "Returns all 3rd-party intent topic subscriptions for the given website, each enriched with\na 7-day surge count so the UI can display \"↑↑ N\" activity badges.\n\n**What are intent topics?**\nIntent topics deliver leads that are actively researching a subject (e.g. \"CRM Software Buyers\")\nbased on 3rd-party data — even if those companies have never visited your website.\nEach subscription has a daily limit that controls how many matching leads are delivered per day.\n\nThis endpoint returns a 200 with `featureEnabled: false` (and an empty result array) if\nthe feature has not been enabled for the website — no error is surfaced to the UI.\n", "tags": [ "Intent Topics" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "websiteId", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "ID of the website" } ], "responses": { "200": { "description": "Subscriptions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/IntentTopicSubscription" } }, "totalActive": { "type": "integer", "description": "Count of subscriptions that are not paused" }, "featureEnabled": { "type": "boolean", "description": "Present and `false` when the feature is not enabled for this website" } } } } } }, "400": { "description": "Invalid websiteId" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Server error" } }, "x-mcp-tool": "list_intent_topics" }, "patch": { "summary": "Update an intent topic subscription", "description": "Mutates an existing subscription. Supports pausing/resuming delivery and changing the daily limit\n— both can be sent in the same request.\n\n- **Pause** (`paused: true`) — stops new leads being delivered for this topic. Existing leads\n and counters are preserved. Use this instead of DELETE when you want to temporarily disable.\n- **Resume** (`paused: false`) — resumes delivery from the next daily delivery.\n- **Change limit** (`userDailyLimit: N`) — updates the cap on leads delivered per day (1–5000).\n\nAt least one of `paused` or `userDailyLimit` must be provided.\n", "tags": [ "Intent Topics" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "websiteId", "topicSlug" ], "properties": { "websiteId": { "type": "string", "description": "ID of the website", "example": "507f1f77bcf86cd799439011" }, "topicSlug": { "type": "string", "description": "Slug of the topic subscription to update", "example": "crm-software-buyers" }, "paused": { "type": "boolean", "description": "`true` to pause delivery, `false` to resume" }, "userDailyLimit": { "type": "integer", "minimum": 1, "maximum": 5000, "description": "New daily delivery cap for this topic" } } } } } }, "responses": { "200": { "description": "Subscription updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/IntentTopicSubscription" } } } } } }, "400": { "description": "Invalid websiteId or no updatable fields provided" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Intent Signals feature not enabled for this website" }, "404": { "description": "Subscription not found (topic not subscribed)" }, "500": { "description": "Server error" } }, "x-mcp-tool": "update_intent_topic" }, "post": { "summary": "Subscribe to an intent topic", "description": "Subscribes a website to a 3rd-party intent topic so that matching leads are delivered daily.\n\n**Idempotent** — calling this again for an already-subscribed topic will unpause it and\nupdate the daily limit if provided, rather than creating a duplicate.\n\nThe `topicSlug` must exist in the global catalog (`GET /admin/intent-topics/catalog`).\nOn subscribe, the system snapshots the topic's audience profile (role keywords, industry\nconstraints) and `availabilityPerDay` so your subscription is not affected by future\ncatalog changes.\n\n`userDailyLimit` controls the maximum leads delivered per day. It defaults to 20 and is\ncapped at 5000. Set it lower if you want to control credit consumption.\n", "tags": [ "Intent Topics" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "websiteId", "topicSlug" ], "properties": { "websiteId": { "type": "string", "description": "ID of the website", "example": "507f1f77bcf86cd799439011" }, "topicSlug": { "type": "string", "description": "Slug of the topic to subscribe to (from the catalog)", "example": "crm-software-buyers" }, "userDailyLimit": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 20, "description": "Maximum leads to deliver per day for this topic. Exceeding availability is allowed — actual delivery is bounded by what's available." } } } } } }, "responses": { "200": { "description": "Subscription created or unpaused successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/IntentTopicSubscription" } } } } } }, "400": { "description": "Invalid websiteId" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Intent Signals feature not enabled for this website" }, "404": { "description": "Topic slug not found in the catalog" }, "500": { "description": "Server error" } }, "x-mcp-tool": "subscribe_to_intent_topic" } }, "/admin/intent-topics/catalog": { "get": { "summary": "Get available intent topics catalog", "description": "Returns the full list of 3rd-party intent topics available for subscription.\nEach entry describes the topic's audience profile (target role keywords and optional\nindustry constraints) and the estimated number of matching leads per day.\n\n**How to use:**\n1. Call this endpoint to browse available topics.\n2. Pick the `topicSlug` values you want and subscribe via `POST /admin/intent-topics`.\n3. The subscribed topics will begin delivering matching leads daily.\n", "tags": [ "Intent Topics" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Catalog retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/IntentTopicCatalogEntry" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Server error" } }, "x-mcp-tool": "get_intent_topics_catalog" } }, "/admin/lead-scoring/{id}": { "delete": { "summary": "Delete scoring model", "description": "Deletes a lead scoring model if it's not the last one for the website (at least one model must remain)", "tags": [ "Lead Scoring" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Lead scoring model ID to delete", "example": "507f1f77bcf86cd799439040" } ], "responses": { "200": { "description": "Lead scoring model deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "Successful" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Model not found, invalid ID, or cannot delete last model", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] } } }, "examples": { "modelNotFound": { "value": { "status": "Lead scoring model was not found" } }, "invalidId": { "value": { "status": "Invalid Id" } }, "validation": { "value": { "status": [ { "msg": "id Is Required" } ] } } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "delete_lead_scoring_model" }, "get": { "summary": "Get single model with scoring criteria", "description": "Retrieves a specific lead scoring model with all its configuration and criteria", "tags": [ "Lead Scoring" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Lead scoring model ID", "example": "507f1f77bcf86cd799439040" } ], "responses": { "200": { "description": "Successfully retrieved lead scoring model", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "website": { "type": "object", "properties": { "_id": { "type": "string" }, "domain": { "type": "string" }, "name": { "type": "string" } } }, "user": { "type": "string" }, "criteria": { "type": "object", "properties": { "revenue": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "min": { "type": "number" }, "max": { "type": "number" }, "score": { "type": "number" } } }, "employees": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "min": { "type": "number" }, "max": { "type": "number" }, "score": { "type": "number" } } }, "industry": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "values": { "type": "array", "items": { "type": "string" } }, "score": { "type": "number" } } }, "jobTitle": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "values": { "type": "array", "items": { "type": "string" } }, "score": { "type": "number" } } }, "location": { "type": "object", "description": "Geographic location criteria" }, "visitBehavior": { "type": "object", "description": "Website visit behavior criteria" } } }, "aiMatching": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "values": { "type": "string", "description": "AI matching criteria with domain replacement" } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "response": { "_id": "507f1f77bcf86cd799439040", "name": "Enterprise Prospects", "active": true, "website": { "_id": "601733dbcedff50114a599f6", "domain": "example.com", "name": "Example Corp" }, "criteria": { "revenue": { "enabled": true, "min": 1000000, "max": null, "score": 25 }, "employees": { "enabled": true, "min": 100, "max": null, "score": 20 }, "industry": { "enabled": true, "values": [ "Technology", "Software" ], "score": 30 } }, "aiMatching": { "enabled": true, "values": "Companies interested in example.com's technology solutions" }, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Invalid model ID or model not found" }, "500": { "description": "Server error" } }, "x-mcp-tool": "get_lead_scoring_model" } }, "/admin/lead-scoring": { "get": { "summary": "Get all scoring models for website", "description": "Retrieves all lead scoring models configured for a specific website with pagination", "tags": [ "Lead Scoring" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "query", "name": "websiteId", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Website ID to get scoring models for", "example": "601733dbcedff50114a599f6" }, { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number for pagination" }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Number of models per page" } ], "responses": { "200": { "description": "Successfully retrieved lead scoring models", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "object", "properties": { "scores": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string", "description": "Name of the scoring model" }, "active": { "type": "boolean", "description": "Whether the model is active" }, "website": { "type": "string", "description": "Associated website ID" }, "user": { "type": "string", "description": "User who created the model" }, "criteria": { "type": "object", "description": "Scoring criteria configuration" }, "aiMatching": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "values": { "type": "string", "description": "AI matching criteria" } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "totalPages": { "type": "integer" }, "currentPage": { "type": "integer" }, "totalScores": { "type": "integer" } } } } }, "example": { "results": { "scores": [ { "_id": "507f1f77bcf86cd799439040", "name": "Enterprise Prospects", "active": true, "website": "601733dbcedff50114a599f6", "user": "507f1f77bcf86cd799439011", "aiMatching": { "enabled": true, "values": "Technology companies with 100+ employees" }, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" } ], "totalPages": 1, "currentPage": 1, "totalScores": 1 } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error - invalid websiteId format" }, "500": { "description": "Server error" } }, "x-mcp-tool": "list_lead_scoring_models" }, "post": { "summary": "Create scoring model", "description": "Creates a new lead scoring model with default criteria and initializes scoring for existing leads", "tags": [ "Lead Scoring" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "websiteId" ], "properties": { "name": { "type": "string", "description": "Name of the scoring model (must be unique per website)", "minLength": 1, "maxLength": 100, "example": "Enterprise Technology Prospects" }, "websiteId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Website ID to associate the model with", "example": "601733dbcedff50114a599f6" } } }, "example": { "name": "High-Value SaaS Prospects", "websiteId": "601733dbcedff50114a599f6" } } } }, "responses": { "201": { "description": "Lead scoring model created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean", "default": true }, "website": { "type": "string" }, "user": { "type": "string" }, "criteria": { "type": "object", "description": "Default empty criteria object" }, "aiMatching": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "values": { "type": "string", "default": "" } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "result": { "_id": "507f1f77bcf86cd799439041", "name": "High-Value SaaS Prospects", "active": true, "website": "601733dbcedff50114a599f6", "user": "507f1f77bcf86cd799439011", "criteria": {}, "aiMatching": { "enabled": false, "values": "" }, "createdAt": "2024-01-02T00:00:00.000Z", "updatedAt": "2024-01-02T00:00:00.000Z" } } } } }, "400": { "description": "Duplicate model name for website", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "You cannot have two score models with the same name!" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error - missing required fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "object" } } } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "create_lead_scoring_model" } }, "/admin/leads-table": { "get": { "summary": "Get paginated leads table with advanced filtering", "description": "Retrieves a paginated list of leads with comprehensive filtering options including location, industry, company size, and engagement metrics", "tags": [ "Leads" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "query", "name": "websiteId", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "ID of the website" }, { "in": "query", "name": "dateFrom", "required": true, "schema": { "type": "string" }, "description": "Start date for filtering leads (MM/DD/YYYY)", "example": "11/08/2025" }, { "in": "query", "name": "dateTo", "required": true, "schema": { "type": "string" }, "description": "End date for filtering leads (MM/DD/YYYY)", "example": "12/08/2025" }, { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination (defaults to 1)" }, { "in": "query", "name": "visitorLocation", "schema": { "type": "string" }, "description": "Filter by visitor country location" }, { "in": "query", "name": "visitorLocationState", "schema": { "type": "string" }, "description": "Filter by visitor state/region" }, { "in": "query", "name": "visitorCity", "schema": { "type": "string" }, "description": "Filter by visitor city" }, { "in": "query", "name": "industries", "schema": { "type": "string" }, "description": "Filter by industries (comma-separated)" }, { "in": "query", "name": "sectors", "schema": { "type": "string" }, "description": "Filter by sectors" }, { "in": "query", "name": "tag", "schema": { "type": "string" }, "description": "Filter by tag" }, { "in": "query", "name": "visits_lower_bound", "schema": { "type": "integer" }, "description": "Minimum number of visits" }, { "in": "query", "name": "visits_upper_bound", "schema": { "type": "integer" }, "description": "Maximum number of visits" }, { "in": "query", "name": "domain", "schema": { "type": "string" }, "description": "Filter by company domain" }, { "in": "query", "name": "sort", "schema": { "type": "string", "enum": [ "lastVisit", "visits", "employees", "revenue", "leadScore" ] }, "description": "Field to sort by" }, { "in": "query", "name": "order", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort order" }, { "in": "query", "name": "employees_lower_bound", "schema": { "type": "integer" }, "description": "Minimum number of employees" }, { "in": "query", "name": "employees_upper_bound", "schema": { "type": "integer" }, "description": "Maximum number of employees" }, { "in": "query", "name": "revenue_lower_bound", "schema": { "type": "number" }, "description": "Minimum annual revenue" }, { "in": "query", "name": "revenue_upper_bound", "schema": { "type": "number" }, "description": "Maximum annual revenue" }, { "in": "query", "name": "pageVisited", "schema": { "type": "string" }, "description": "Filter by specific page visited" }, { "in": "query", "name": "utmMedium", "schema": { "type": "string" }, "description": "UTM medium parameter" }, { "in": "query", "name": "utmTerm", "schema": { "type": "string" }, "description": "UTM term parameter" }, { "in": "query", "name": "utmName", "schema": { "type": "string" }, "description": "UTM campaign name" }, { "in": "query", "name": "utmSource", "schema": { "type": "string" }, "description": "UTM source parameter" }, { "in": "query", "name": "exactVisitor", "schema": { "type": "boolean" }, "description": "Filter for exact/identified visitors only" }, { "in": "query", "name": "tech", "schema": { "type": "string" }, "description": "Filter by technology stack" }, { "in": "query", "name": "leadscore_lower", "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "description": "Minimum lead score" }, { "in": "query", "name": "leadscore_upper", "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "description": "Maximum lead score" }, { "in": "query", "name": "hasPhoneNumber", "schema": { "type": "boolean" }, "description": "Filter for leads with phone numbers" }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "public", "private", "education", "government", "nonprofit", "personal" ] }, "description": "Filter by company type" }, { "in": "query", "name": "visitorType", "schema": { "type": "string", "enum": [ "suggested-contact", "exact-visitor", "not-found" ] }, "description": "Filter by how the visitor was identified: `suggested-contact` (company matched, contacts suggested), `exact-visitor` (individual identified), `not-found` (no contact data)" }, { "in": "query", "name": "hqLocation", "schema": { "type": "string" }, "description": "Filter by company HQ country (distinct from the visitor's IP-based location)" }, { "in": "query", "name": "hqLocationState", "schema": { "type": "string" }, "description": "Filter by company HQ state/region" }, { "in": "query", "name": "hqCity", "schema": { "type": "string" }, "description": "Filter by company HQ city" }, { "in": "query", "name": "alexa_lower_bound", "schema": { "type": "integer" }, "description": "Minimum Alexa rank (lower = more popular)" }, { "in": "query", "name": "alexa_upper_bound", "schema": { "type": "integer" }, "description": "Maximum Alexa rank" }, { "in": "query", "name": "listId", "schema": { "type": "string" }, "description": "Filter leads to companies in a specific saved list (pass the list ID)" }, { "in": "query", "name": "hubspotStatus", "schema": { "type": "string" }, "description": "Filter by HubSpot CRM sync status (e.g. `synced`, `pending`, `error`)" }, { "in": "query", "name": "pipedriveStatus", "schema": { "type": "string" }, "description": "Filter by Pipedrive CRM sync status" }, { "in": "query", "name": "zohoStatus", "schema": { "type": "string" }, "description": "Filter by Zoho CRM sync status" }, { "in": "query", "name": "signalSource", "schema": { "type": "string", "enum": [ "visit", "topic", "both", "all" ] }, "description": "Filter leads by how they were sourced. **3rd-party intent data context:**\n- `visit` – only leads that arrived through your tracking pixel (website visitors)\n- `topic` – only leads delivered via a subscribed 3rd-party intent topic (companies researching a topic, even if they never visited your site)\n- `both` – leads that have both a website visit AND an intent topic signal\n- `all` (default) – all leads regardless of source\n" }, { "in": "query", "name": "topicSlug", "schema": { "type": "string" }, "description": "Filter leads to those matching a specific intent topic subscription (e.g. `crm-software-buyers`). Use `GET /admin/intent-topics` to list your active subscriptions and their slugs." } ], "responses": { "200": { "description": "Successfully retrieved leads", "content": { "application/json": { "schema": { "type": "object", "properties": { "leads": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "totalLeads": { "type": "integer", "description": "Total number of leads matching filters" }, "totalPages": { "type": "integer", "description": "Total number of pages" }, "currentPage": { "type": "integer", "description": "Current page number" }, "activeAutomations": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "description": "Query too large or server error" } }, "x-mcp-tool": "get_leads" } }, "/admin/lists/{id}/items": { "delete": { "summary": "Remove items from list", "description": "Removes specific contacts or companies from a list by their IDs", "tags": [ "Lists" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "List ID to remove items from", "example": "507f1f77bcf86cd799439020" }, { "in": "query", "name": "listType", "required": true, "schema": { "type": "string", "enum": [ "contact", "company" ] }, "description": "Type of list" }, { "in": "query", "name": "contacts", "required": false, "schema": { "type": "string" }, "description": "Comma-separated string of contact IDs to remove (for contact lists)", "example": "63dac298c028100013252e8b,63dac29cc028100013252f1c" }, { "in": "query", "name": "companies", "required": false, "schema": { "type": "string" }, "description": "Comma-separated string of company IDs to remove (for company lists)", "example": "63dac298c028100013252e8b,63dac29cc028100013252f1c" } ], "responses": { "200": { "description": "Items removed from list successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "Successful deleted" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "List not found, invalid ID, or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] } } }, "examples": { "listNotFound": { "value": { "status": "List was not found" } }, "invalidId": { "value": { "status": "Invalid Id" } }, "validation": { "value": { "status": [ { "msg": "id Is Required" } ] } } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "remove_list_items" } }, "/admin/lists/{id}": { "delete": { "summary": "Delete list", "description": "Permanently deletes a contact or company list and all its associated data", "tags": [ "Lists" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "List ID to delete", "example": "507f1f77bcf86cd799439020" }, { "in": "query", "name": "listType", "required": true, "schema": { "type": "string", "enum": [ "contact", "company" ] }, "description": "Type of list to delete" } ], "responses": { "200": { "description": "List deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "Successful" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Invalid list ID or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] } } }, "examples": { "invalidId": { "value": { "status": "Invalid Id" } }, "validation": { "value": { "status": [ { "msg": "id Is Required" } ] } } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "delete_list" }, "get": { "summary": "Get list with paginated items", "description": "Retrieves a specific list with its contacts or companies using pagination", "tags": [ "Lists" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "List ID to retrieve", "example": "507f1f77bcf86cd799439020" }, { "in": "query", "name": "listType", "required": true, "schema": { "type": "string", "enum": [ "contact", "company" ] }, "description": "Type of list" }, { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number for pagination" }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Number of items per page" } ], "responses": { "200": { "description": "Successfully retrieved list with items", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "website": { "type": "string" }, "user": { "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "businessEmail": { "type": "string", "format": "email" }, "position": { "type": "string" }, "company": { "type": "string" }, "phone": { "type": "string" }, "verifiedStatus": { "type": "string", "enum": [ "valid", "invalid", "risky", "catch-all", "unknown" ] } } }, "description": "Array of contacts (for contact lists)" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "industry": { "type": "string" }, "employeeCount": { "type": "integer" } } }, "description": "Array of companies (for company lists)" }, "totalItems": { "type": "integer" }, "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "example": { "response": { "_id": "507f1f77bcf86cd799439020", "name": "Sales Prospects", "website": "601733dbcedff50114a599f6", "user": "507f1f77bcf86cd799439011", "contacts": [ { "_id": "507f1f77bcf86cd799439022", "firstName": "John", "lastName": "Doe", "businessEmail": "john@example.com", "position": "Sales Manager", "company": "Example Corp", "phone": "+1-555-0123", "verifiedStatus": "valid" } ], "totalItems": 125, "currentPage": 1, "totalPages": 3, "createdAt": "2024-01-01T00:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error or list not found" }, "500": { "description": "Server error" } }, "x-mcp-tool": "get_list" } }, "/admin/lists": { "get": { "summary": "Get contact/company lists", "description": "Retrieves paginated lists of contacts or companies for a specific website", "tags": [ "Lists" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "query", "name": "websiteId", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Website ID to get lists for", "example": "601733dbcedff50114a599f6" }, { "in": "query", "name": "listType", "required": true, "schema": { "type": "string", "enum": [ "contact", "company" ] }, "description": "Type of list to retrieve" }, { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number for pagination" }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Number of lists per page" }, { "in": "query", "name": "excludeListItems", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" }, "description": "Whether to exclude list items from response" } ], "responses": { "200": { "description": "Successfully retrieved lists", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "website": { "type": "string" }, "user": { "type": "string" }, "contacts": { "type": "array", "items": { "type": "object" }, "description": "Array of contacts (for contact lists)" }, "companies": { "type": "array", "items": { "type": "object" }, "description": "Array of companies (for company lists)" }, "totalContacts": { "type": "integer", "description": "Total number of contacts in list" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "example": { "lists": [ { "_id": "507f1f77bcf86cd799439020", "name": "Sales Prospects", "website": "601733dbcedff50114a599f6", "user": "507f1f77bcf86cd799439011", "totalContacts": 125, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" }, { "_id": "507f1f77bcf86cd799439021", "name": "Marketing Leads", "website": "601733dbcedff50114a599f6", "user": "507f1f77bcf86cd799439011", "totalContacts": 89, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error - missing required parameters" }, "500": { "description": "Server error" } }, "x-mcp-tool": "list_lists" }, "post": { "summary": "Create new list", "description": "Creates a new contact or company list for organizing leads and prospects", "tags": [ "Lists" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "query", "name": "listType", "required": true, "schema": { "type": "string", "enum": [ "contact", "company" ] }, "description": "Type of list to create" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "websiteId" ], "properties": { "name": { "type": "string", "description": "Name of the list", "minLength": 1, "maxLength": 100, "example": "Q1 Sales Prospects" }, "websiteId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Website ID to associate the list with", "example": "601733dbcedff50114a599f6" } } }, "example": { "name": "Enterprise Prospects", "websiteId": "601733dbcedff50114a599f6" } } } }, "responses": { "201": { "description": "List created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "website": { "type": "string" }, "user": { "type": "string" }, "contacts": { "type": "array", "items": { "type": "object" }, "description": "Empty array for new contact lists" }, "companies": { "type": "array", "items": { "type": "object" }, "description": "Empty array for new company lists" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "list": { "_id": "507f1f77bcf86cd799439023", "name": "Enterprise Prospects", "website": "601733dbcedff50114a599f6", "user": "507f1f77bcf86cd799439011", "contacts": [], "createdAt": "2024-01-02T00:00:00.000Z", "updatedAt": "2024-01-02T00:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "Validation error - missing required fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "object" } } } } } } }, "500": { "description": "Server error" } }, "x-mcp-tool": "create_list" } }, "/admin/lists/export-csv/{listId}": { "post": { "summary": "Export list to CSV", "description": "Exports a contact or company list to CSV format and emails it to the user", "tags": [ "Lists" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "path", "name": "listId", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "List ID to export", "example": "507f1f77bcf86cd799439020" }, { "in": "query", "name": "listType", "required": true, "schema": { "type": "string", "enum": [ "contact", "company" ] }, "description": "Type of list to export" } ], "responses": { "200": { "description": "Export initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "You will receive the CSV file shortly" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "405": { "description": "List not found or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] } } }, "examples": { "listNotFound": { "value": { "status": "List was not found" } }, "validation": { "value": { "status": [ { "msg": "listId Is Required" } ] } } } } } }, "500": { "description": "Server error during export" } }, "x-mcp-tool": "export_list_csv" } }, "/admin/location/cities": { "get": { "summary": "Search cities for lead filtering and targeting", "description": "## Overview\nSearch for cities across all countries or within a specific country. This endpoint is primarily used for:\n- Filtering leads by visitor city location\n- Setting up location-based targeting criteria\n- Building location filters in the leads table\n\n## How City Search Works\n\n### Global Search (No Country Filter)\nWhen searching without a country parameter:\n- Searches across all countries in the database\n- Returns up to `limit` results (default: 50, max: 200)\n- Results include both city name and country\n- Useful for autocomplete when country is unknown\n\n### Country-Specific Search\nWhen `country` parameter is provided:\n- Searches only within that specific country\n- Faster response time (smaller dataset)\n- No limit applied (returns all matching cities)\n- Recommended when country is already known\n\n## Search Behavior\n\n- **Case-insensitive**: Searches work regardless of capitalization\n- **Prefix matching**: Searches match cities starting with the query\n- **Minimum length**: Query must be at least 2 characters\n- **Example**: \"san\" matches \"San Francisco\", \"San Diego\", \"Santiago\"\n\n## Common Use Cases\n\n**Use Case 1: Lead Filtering UI**\n```javascript\n// User types \"New Y\" in city filter\nGET /admin/location/cities?q=New+Y&limit=10\n// Returns: New York (USA), New York Mills (USA), etc.\n```\n\n**Use Case 2: Country-Specific Targeting**\n```javascript\n// User wants to find cities in United Kingdom starting with \"Man\"\nGET /admin/location/cities?q=Man&country=United+Kingdom\n// Returns: Manchester, Mansfield, etc.\n```\n\n**Use Case 3: Location-Based Lead Segmentation**\n```javascript\n// Find all cities matching \"Los\" to build a segment\nGET /admin/location/cities?q=Los&limit=20\n// Returns: Los Angeles, Los Cabos, Los Santos, etc.\n```\n\n## Performance Tips\n\n- **Use country filter**: When country is known, always include it for faster searches\n- **Limit results**: Use lower limit values (10-20) for autocomplete UI\n- **Debounce**: Debounce user input to avoid excessive API calls\n- **Cache results**: Client-side caching of common searches improves UX\n", "tags": [ "Location" ], "security": [ { "privateKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "privateKey", "required": true, "schema": { "type": "string" }, "description": "Your API Private Key from your account settings" }, { "in": "query", "name": "q", "required": true, "schema": { "type": "string", "minLength": 2 }, "description": "Search query for city name (minimum 2 characters).\n- Case-insensitive prefix matching\n- Examples: \"san\", \"New Y\", \"lon\"\n", "example": "San" }, { "in": "query", "name": "country", "schema": { "type": "string" }, "description": "Optional country filter to narrow search results.\n- Must match country name exactly (case-insensitive)\n- When provided, ignores `limit` parameter\n- Examples: \"United States\", \"United Kingdom\", \"Canada\"\n", "example": "United States" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Maximum number of results to return (only applies to global search).\n- Default: 50\n- Maximum: 200\n- Ignored when `country` parameter is provided\n- Recommended: 10-20 for autocomplete UI\n", "example": 20 } ], "responses": { "200": { "description": "Successfully retrieved matching cities.\nResults are sorted alphabetically by city name.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "cities": { "type": "array", "description": "Array of city objects matching the search query", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "Country name where the city is located", "example": "United States" }, "city": { "type": "string", "description": "City name", "example": "San Francisco" } } } } } }, "examples": { "globalSearch": { "summary": "Global Search Results", "value": { "cities": [ { "country": "United States", "city": "San Francisco" }, { "country": "United States", "city": "San Diego" }, { "country": "Mexico", "city": "San Miguel de Allende" } ] } }, "countrySpecific": { "summary": "Country-Specific Search", "value": { "cities": [ { "country": "United Kingdom", "city": "London" }, { "country": "United Kingdom", "city": "Londonderry" } ] } } } } } }, "400": { "description": "Invalid query parameter - query string too short.\nQuery must be at least 2 characters long.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Query must be at least 2 characters long" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Internal server error during city search", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Failed to search cities" } } } } } } }, "x-mcp-tool": "search_locations" } }, "/admin/location/countries": { "get": { "summary": "Get list of all available countries for location filtering", "description": "## Overview\nRetrieves the complete list of countries that have city data available.\nThis endpoint is used for:\n- Populating country dropdown filters in the leads table\n- Enabling country-based lead segmentation\n- Restricting city searches to specific countries\n- Building location-based targeting criteria\n\n## How Countries Work\n\n### Data Source\n- Only includes countries with city data available\n\n### Response Characteristics\n- **Static list**: Countries don't change frequently\n- **Alphabetically sorted**: Countries ordered A-Z\n- **Full country names**: Returns complete names (e.g., \"United States\", not \"US\")\n- **No pagination**: Returns all countries in single response\n\n## Common Use Cases\n\n**Use Case 1: Country Filter Dropdown**\n```javascript\n// Load countries for filter dropdown on page load\nGET /admin/location/countries\n// Use response to populate