{ "openapi": "3.1.0", "info": { "title": "Max (yourmax.ai) REST API", "version": "1.0.0", "summary": "Public buying-signal discovery and authenticated Max team workflows.", "description": "The versioned Max API exposes a public signal catalog and team-scoped resources for businesses, monitoring subscriptions, discovered leads, and webhooks. All protected operations accept a Max API key or OAuth access token in the Authorization: Bearer header. API keys inherit the permissions of one team. A signal is evidence to review, not proof of buying intent. Max announces a v1 deprecation in the API documentation and changelog before removal; affected responses use standard Deprecation and Sunset headers during the announced migration window.", "termsOfService": "https://yourmax.ai/terms/", "contact": { "name": "Max developer support", "email": "hello@yourmax.ai", "url": "https://yourmax.ai/contact/" }, "license": { "name": "Max Terms of Use", "identifier": "LicenseRef-Max-Terms", "url": "https://yourmax.ai/terms/" }, "x-api-version": "v1", "x-rate-limit": "60 requests per minute per API key", "x-deprecation-policy": { "currentVersion": "v1", "documentation": "https://yourmax.ai/api.md#versioning-and-deprecation-policy", "changelog": "https://yourmax.ai/changelog/", "responseHeaders": [ "Deprecation", "Sunset" ], "policy": "Breaking removals are announced before removal. Deprecated operations return Deprecation and Sunset headers during the announced migration window." } }, "externalDocs": { "description": "Human-readable Max API documentation", "url": "https://api.yourmax.ai/docs/api" }, "servers": [ { "url": "https://api.yourmax.ai/api/v1", "description": "Max production API, version 1" } ], "tags": [ { "name": "Signals", "description": "Public catalog of signal types Max can monitor." }, { "name": "Businesses", "description": "Businesses and their Ideal Customer Profiles within a team." }, { "name": "Integrations", "description": "Third-party connections configured for a business. Integration credentials are never returned." }, { "name": "Subscriptions", "description": "Signal-monitoring configurations scoped to a business." }, { "name": "Leads", "description": "Discovered and enriched leads scoped to a business." }, { "name": "Webhooks", "description": "HTTPS endpoints for real-time new-lead notifications." } ], "paths": { "/signals": { "get": { "tags": [ "Signals" ], "operationId": "listSignals", "summary": "List active signal types", "description": "Public endpoint. Returns the signal types Max can monitor, including each signal's configuration schema when available.", "security": [], "responses": { "200": { "description": "Active signal types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalsResponse" } } } }, "429": { "description": "The public request rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/signals/{slug}": { "get": { "tags": [ "Signals" ], "operationId": "getSignal", "summary": "Get one signal type", "description": "Public endpoint. Looks up an active signal by its stable slug.", "security": [], "parameters": [ { "$ref": "#/components/parameters/SignalSlug" } ], "responses": { "200": { "description": "Signal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalResponse" } } } }, "404": { "description": "No active signal has this slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The public request rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses": { "get": { "tags": [ "Businesses" ], "operationId": "listBusinesses", "summary": "List team businesses", "description": "Returns every business available to the bearer token's team.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "responses": { "200": { "description": "Businesses in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessesResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Businesses" ], "operationId": "createBusiness", "summary": "Create a business", "description": "Creates a business. Supplying only a website URL triggers automatic analysis; manual creation can supply a name, description, and ICP fields.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessWrite" } } } }, "responses": { "201": { "description": "The business was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}": { "get": { "tags": [ "Businesses" ], "operationId": "getBusiness", "summary": "Get a business and its ICP", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" } ], "responses": { "200": { "description": "Business details and its Ideal Customer Profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Businesses" ], "operationId": "updateBusiness", "summary": "Update a business or its ICP", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessWrite" } } } }, "responses": { "200": { "description": "The updated business.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/integrations": { "get": { "tags": [ "Integrations" ], "operationId": "listIntegrations", "summary": "List a business's integrations", "description": "Returns the third-party connections configured for a business. Credentials and other secrets are never exposed.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" } ], "responses": { "200": { "description": "Integrations configured for the business.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationsResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/integrations/{integrationId}/campaigns": { "get": { "tags": [ "Integrations" ], "operationId": "listIntegrationCampaigns", "summary": "List campaigns for an integration", "description": "Returns campaigns from a campaign-based Overloop or Instantly integration. Results are cached for five minutes. Integrations that do not support campaigns return 422.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/IntegrationId" } ], "responses": { "200": { "description": "Campaigns available through the selected integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCampaignsResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/subscriptions": { "get": { "tags": [ "Subscriptions" ], "operationId": "listSubscriptions", "summary": "List a business's subscriptions", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Signal-monitoring subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Subscriptions" ], "operationId": "createSubscription", "summary": "Create a signal-monitoring subscription", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionWrite" } } } }, "responses": { "201": { "description": "The subscription was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/subscriptions/{subscriptionId}": { "get": { "tags": [ "Subscriptions" ], "operationId": "getSubscription", "summary": "Get one subscription", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/SubscriptionId" } ], "responses": { "200": { "description": "Subscription details and statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Subscriptions" ], "operationId": "updateSubscription", "summary": "Update a subscription", "description": "Updates the name, configuration, active state, or linked integrations. When supplied, the integrations array replaces all existing links.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/SubscriptionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionWrite" } } } }, "responses": { "200": { "description": "The updated subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Subscriptions" ], "operationId": "deleteSubscription", "summary": "Delete a subscription", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/SubscriptionId" } ], "responses": { "204": { "description": "The resource was removed successfully." }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/subscriptions/{subscriptionId}/pause": { "post": { "tags": [ "Subscriptions" ], "operationId": "pauseSubscription", "summary": "Pause a subscription", "description": "Stops the subscription from scanning for new leads.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/SubscriptionId" } ], "responses": { "200": { "description": "The subscription with active set to false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/subscriptions/{subscriptionId}/resume": { "post": { "tags": [ "Subscriptions" ], "operationId": "resumeSubscription", "summary": "Resume a subscription", "description": "Restarts lead scanning for a paused subscription.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/SubscriptionId" } ], "responses": { "200": { "description": "The subscription with active set to true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/leads": { "get": { "tags": [ "Leads" ], "operationId": "listLeads", "summary": "List discovered leads", "description": "Returns a business's leads, newest first.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of discovered leads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadsResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/leads/{leadId}": { "get": { "tags": [ "Leads" ], "operationId": "getLead", "summary": "Get one discovered lead", "description": "Returns the enriched lead record and delivery history.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/LeadId" } ], "responses": { "200": { "description": "The discovered lead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Leads" ], "operationId": "deleteLead", "summary": "Soft-delete a lead", "description": "Removes a lead from list results without immediately erasing it.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/LeadId" } ], "responses": { "204": { "description": "The resource was removed successfully." }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/leads/enroll": { "post": { "tags": [ "Leads" ], "operationId": "enrollLeads", "summary": "Queue leads for campaign enrollment", "description": "Queues selected leads for delivery to an Overloop or Instantly campaign. Leads without an email address or LinkedIn URL are skipped.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadEnrollmentRequest" } } } }, "responses": { "200": { "description": "Counts of leads queued and skipped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadEnrollmentResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List webhook endpoints", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" } ], "responses": { "200": { "description": "Webhooks configured for the business.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhooksResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Register a new-lead webhook", "description": "Registers an HTTPS endpoint. When a secret is supplied, Max signs the raw payload with HMAC-SHA256 in X-Signals-Signature.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWrite" } } } }, "responses": { "201": { "description": "The webhook was registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/businesses/{businessId}/webhooks/{webhookId}": { "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint", "security": [ { "bearerAuth": [] }, { "oauth2": [ "read" ] } ], "x-permission-scope": "team", "parameters": [ { "$ref": "#/components/parameters/BusinessId" }, { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "204": { "description": "The resource was removed successfully." }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found in the authenticated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The team-scoped rate limit of 60 requests per minute was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Max API key or OAuth 2.0 access token", "description": "Create a team-scoped API key in Settings → API Keys, or supply a Max OAuth access token." }, "oauth2": { "type": "oauth2", "description": "Max OAuth supports authorization code with PKCE and the device flow used by the official CLI. The API currently requests the read scope; it does not publish invented granular write scopes.", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.yourmax.ai/authorize", "tokenUrl": "https://auth.yourmax.ai/oauth/token", "scopes": { "read": "Access the Max API resources available to the authorized team.", "openid": "Authenticate the user with OpenID Connect.", "profile": "Read basic user profile claims.", "email": "Read the user's email claim.", "offline_access": "Request a refresh token when the client is eligible." } } }, "x-device-authorization-url": "https://auth.yourmax.ai/oauth/device/code", "x-pkce-methods": [ "S256" ], "x-openid-configuration": "https://auth.yourmax.ai/.well-known/openid-configuration" } }, "parameters": { "SignalSlug": { "name": "slug", "in": "path", "required": true, "description": "Stable signal slug returned by listSignals.", "schema": { "type": "string", "minLength": 1 } }, "BusinessId": { "name": "businessId", "in": "path", "required": true, "description": "Business ID within the authenticated team.", "schema": { "type": "integer", "minimum": 1 } }, "SubscriptionId": { "name": "subscriptionId", "in": "path", "required": true, "description": "Subscription ID within the selected business.", "schema": { "type": "integer", "minimum": 1 } }, "IntegrationId": { "name": "integrationId", "in": "path", "required": true, "description": "Integration ID within the selected business.", "schema": { "type": "integer", "minimum": 1 } }, "LeadId": { "name": "leadId", "in": "path", "required": true, "description": "Lead ID within the selected business.", "schema": { "type": "integer", "minimum": 1 } }, "WebhookId": { "name": "webhookId", "in": "path", "required": true, "description": "Webhook ID within the selected business.", "schema": { "type": "integer", "minimum": 1 } }, "Page": { "name": "page", "in": "query", "required": false, "description": "One-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "required": false, "description": "Results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } }, "schemas": { "JsonObject": { "type": "object", "additionalProperties": true }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable description of the API error." } }, "additionalProperties": true, "examples": [ { "error": "Unauthorized. Please provide a valid API key or OAuth token." } ] }, "PaginationMeta": { "type": "object", "required": [ "current_page", "total_pages", "total_count", "per_page" ], "properties": { "current_page": { "type": "integer", "minimum": 1 }, "total_pages": { "type": "integer", "minimum": 0 }, "total_count": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "Signal": { "type": "object", "required": [ "id", "name", "slug", "description", "active", "default_config" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "active": { "type": "boolean" }, "default_config": { "$ref": "#/components/schemas/JsonObject" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "SignalsResponse": { "type": "object", "required": [ "signals" ], "properties": { "signals": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } } }, "additionalProperties": false }, "SignalResponse": { "type": "object", "required": [ "signal" ], "properties": { "signal": { "$ref": "#/components/schemas/Signal" } }, "additionalProperties": false }, "IdealCustomerProfile": { "type": "object", "properties": { "id": { "type": "integer" }, "target_job_titles": { "type": "array", "items": { "type": "string" } }, "target_locations": { "type": "array", "items": { "type": "string" } }, "target_industries": { "type": "array", "items": { "type": "string" } }, "company_types": { "type": "array", "items": { "type": "string" } }, "company_sizes": { "type": "array", "items": { "type": "string" } }, "mandatory_keywords": { "type": "array", "items": { "type": "string" } }, "excluded_companies": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" } }, "additionalProperties": true }, "IdealCustomerProfileWrite": { "allOf": [ { "$ref": "#/components/schemas/IdealCustomerProfile" } ], "description": "ICP fields to create or update. Include id when updating an existing profile." }, "Business": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "website": { "type": [ "string", "null" ], "format": "uri" }, "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "ideal_customer_profile": { "$ref": "#/components/schemas/IdealCustomerProfile" } }, "additionalProperties": true }, "BusinessWrite": { "type": "object", "properties": { "name": { "type": "string", "description": "Required for manual creation." }, "website": { "type": "string", "format": "uri", "description": "When supplied alone on create, Max analyzes the website and generates the business and ICP." }, "description": { "type": "string" }, "ideal_customer_profile_attributes": { "$ref": "#/components/schemas/IdealCustomerProfileWrite" } }, "additionalProperties": false, "minProperties": 1 }, "BusinessesResponse": { "type": "object", "required": [ "businesses" ], "properties": { "businesses": { "type": "array", "items": { "$ref": "#/components/schemas/Business" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "additionalProperties": true }, "BusinessResponse": { "type": "object", "required": [ "business" ], "properties": { "business": { "$ref": "#/components/schemas/Business" } }, "additionalProperties": false }, "Integration": { "type": "object", "required": [ "id", "type", "display_name", "created_at" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "description": "Stable integration type, such as overloop_ai or webhook." }, "display_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true, "description": "A configured third-party connection. Credential fields are intentionally absent." }, "IntegrationsResponse": { "type": "object", "required": [ "integrations" ], "properties": { "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } }, "additionalProperties": false }, "IntegrationCampaign": { "type": "object", "required": [ "id", "name", "status" ], "properties": { "id": { "type": "string", "description": "Campaign identifier supplied by the integration." }, "name": { "type": "string" }, "status": { "type": "string", "description": "Provider-reported campaign state, such as on or paused." } }, "additionalProperties": true }, "IntegrationCampaignsResponse": { "type": "object", "required": [ "campaigns" ], "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationCampaign" } } }, "additionalProperties": false }, "SubscriptionIntegration": { "type": "object", "required": [ "integration_id" ], "properties": { "integration_id": { "type": "integer" }, "auto_deliver": { "type": "boolean", "default": false }, "campaign_id": { "type": "string" }, "campaign_name": { "type": "string" } }, "additionalProperties": true }, "Subscription": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "signal_slug": { "type": "string" }, "config": { "$ref": "#/components/schemas/JsonObject" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionIntegration" } }, "total_leads": { "type": "integer", "minimum": 0 }, "leads_today": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "SubscriptionWrite": { "type": "object", "properties": { "signal_slug": { "type": "string", "description": "Required when creating a subscription." }, "name": { "type": "string", "description": "Required when creating a subscription." }, "config": { "$ref": "#/components/schemas/JsonObject" }, "active": { "type": "boolean" }, "integrations": { "type": "array", "description": "When present on update, replaces all linked integrations.", "items": { "$ref": "#/components/schemas/SubscriptionIntegration" } } }, "additionalProperties": false, "minProperties": 1 }, "SubscriptionsResponse": { "type": "object", "required": [ "subscriptions" ], "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "additionalProperties": true }, "SubscriptionResponse": { "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" } }, "additionalProperties": false }, "Delivery": { "type": "object", "properties": { "id": { "type": "integer" }, "integration_type": { "type": "string" }, "status": { "type": "string" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "Lead": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "external_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "headline": { "type": [ "string", "null" ] }, "job_title": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ], "format": "uri" }, "profile_picture": { "type": [ "string", "null" ], "format": "uri" }, "location": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "company_logo": { "type": [ "string", "null" ], "format": "uri" }, "company_industry": { "type": [ "string", "null" ] }, "company_size": { "type": [ "string", "null" ] }, "company_website": { "type": [ "string", "null" ], "format": "uri" }, "company_linkedin": { "type": [ "string", "null" ], "format": "uri" }, "company_founded": { "type": [ "string", "null" ] }, "connections": { "type": [ "integer", "null" ] }, "followers": { "type": [ "integer", "null" ] }, "icp_score": { "type": [ "number", "null" ] }, "engagement_type": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ], "format": "uri" }, "signals": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } }, "additionalProperties": true } }, "subscription_ids": { "type": "array", "items": { "type": "integer" } }, "payload": { "$ref": "#/components/schemas/JsonObject" }, "triggered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } }, "additionalProperties": true }, "LeadsResponse": { "type": "object", "required": [ "leads", "meta" ], "properties": { "leads": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "additionalProperties": false }, "LeadResponse": { "type": "object", "required": [ "lead" ], "properties": { "lead": { "$ref": "#/components/schemas/Lead" } }, "additionalProperties": false }, "LeadEnrollmentRequest": { "type": "object", "required": [ "integration_id", "campaign_id", "lead_ids" ], "properties": { "integration_id": { "type": "integer", "minimum": 1 }, "campaign_id": { "type": "string", "minLength": 1 }, "lead_ids": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": false }, "LeadEnrollmentResponse": { "type": "object", "required": [ "enqueued", "skipped" ], "properties": { "enqueued": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "Webhook": { "type": "object", "required": [ "id", "url" ], "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "WebhookWrite": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "secret": { "type": "string", "minLength": 1, "writeOnly": true, "description": "Optional shared secret for X-Signals-Signature HMAC-SHA256 signatures." } }, "additionalProperties": false }, "WebhooksResponse": { "type": "object", "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "additionalProperties": true }, "WebhookResponse": { "type": "object", "required": [ "webhook" ], "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" } }, "additionalProperties": false } } } }