{ "openapi": "3.1.0", "info": { "title": "Signaliz API", "version": "2.0.0", "description": "Signaliz GTM intelligence platform. Find companies, discover contacts, verify emails, detect buying signals, and run autonomous sales systems.", "contact": { "name": "Signaliz", "url": "https://signaliz.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.signaliz.com", "description": "Production" } ], "paths": { "/find-emails-with-verification": { "post": { "operationId": "findEmailsWithVerification", "summary": "Find and verify a work email address", "description": "Finds a professional email address for a person at a company and verifies its deliverability. Uses a waterfall of providers for maximum coverage.", "x-credits": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_domain" ], "properties": { "company_domain": { "type": "string", "description": "Company domain (e.g., 'stripe.com')", "example": "stripe.com" }, "first_name": { "type": "string", "description": "Contact's first name" }, "last_name": { "type": "string", "description": "Contact's last name" }, "full_name": { "type": "string", "description": "Full name (alternative to first_name + last_name)" }, "linkedin_url": { "type": "string", "description": "LinkedIn profile URL for improved accuracy" }, "wait_for_result": { "type": "boolean", "default": true, "description": "Wait for synchronous result (default: true)" }, "timeout_ms": { "type": "integer", "default": 120000, "description": "Timeout in milliseconds (default: 120000)" } } } } } }, "responses": { "200": { "description": "Email found and verification result returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "COMPLETED", "FAILED" ] }, "output": { "type": "object", "properties": { "email": { "type": "string" }, "verified_for_sending": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "source": { "type": "string" } } }, "durationMs": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] }, { "OAuth2": [ "enrichment:read" ] } ] } }, "/email-verification": { "post": { "operationId": "verifyEmail", "summary": "Verify an email address", "description": "Checks if an email is valid, deliverable, and whether the domain is a catch-all.", "x-credits": 0.5, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address to verify", "example": "john@stripe.com" } } } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "output": { "type": "object", "properties": { "email": { "type": "string" }, "is_valid": { "type": "boolean" }, "is_deliverable": { "type": "boolean" }, "is_catch_all": { "type": "boolean" }, "risk_level": { "type": "string", "enum": [ "low", "medium", "high" ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] }, { "OAuth2": [ "enrichment:read" ] } ] } }, "/company-signal-enrichment": { "post": { "operationId": "enrichCompanySignals", "summary": "Detect buying signals for a company", "description": "AI-powered company signal discovery. Identifies hiring, funding, product launches, partnerships, and other timing-based indicators.", "x-credits": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_domain": { "type": "string", "description": "Company domain to research", "example": "acme.com" }, "company_name": { "type": "string", "description": "Company name (alternative to domain)" }, "signal_types": { "type": "array", "items": { "type": "string" }, "description": "Signal types to detect", "example": [ "hiring", "funding", "product", "leadership" ] }, "lookback_days": { "type": "integer", "default": 30, "description": "How far back to search (days)" }, "workspace_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Signals discovered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "signals": { "type": "array", "items": { "type": "object", "properties": { "signal_type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "high", "medium", "low" ] }, "source_url": { "type": "string" }, "detected_at": { "type": "string", "format": "date-time" } } } }, "total_signals": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] }, { "OAuth2": [ "signals:read" ] } ] } }, "/find-contacts-with-email": { "post": { "operationId": "findContactsWithEmail", "summary": "Find contacts at a company with verified emails", "description": "Discovers contacts at a company by role or department and returns verified email addresses.", "x-credits": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_linkedin_url" ], "properties": { "domain": { "type": "string", "description": "Company domain. Preferred canonical field; company_domain is also accepted.", "example": "stripe.com" }, "company_domain": { "type": "string", "description": "Company domain alias accepted for compatibility.", "example": "stripe.com" }, "role": { "type": "string", "description": "Target role alias for job_title (e.g., 'VP Sales')" }, "job_title": { "type": "string", "description": "Target role/title (e.g., 'VP Sales')" }, "target_titles": { "type": "array", "items": { "type": "string" }, "description": "Target titles to search for." }, "job_titles": { "type": "array", "items": { "type": "string" }, "description": "Alias for target_titles." }, "target_persona": { "type": "string", "description": "Natural-language persona to expand into target titles." }, "department": { "type": "string", "description": "Fallback role hint when job_title or role is omitted." }, "limit": { "type": "integer", "default": 5, "description": "Reserved compatibility field. Current API returns the best matching contact per request." }, "company_linkedin_url": { "type": "string", "description": "Company LinkedIn URL required by the current contact discovery provider.", "example": "https://www.linkedin.com/company/stripe" } }, "anyOf": [ { "required": [ "domain" ] }, { "required": [ "company_domain" ] } ], "oneOf": [ { "required": [ "role" ] }, { "required": [ "job_title" ] }, { "required": [ "target_titles" ] }, { "required": [ "job_titles" ] }, { "required": [ "target_persona" ] } ] } } } }, "responses": { "200": { "description": "Contacts found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "title": { "type": "string" }, "linkedin_url": { "type": "string" }, "verified": { "type": "boolean" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] }, { "OAuth2": [ "enrichment:read" ] } ] } }, "/deep-research": { "post": { "operationId": "deepResearch", "summary": "AI-powered deep research on a company or topic", "description": "Uses AI models with web search to conduct comprehensive research and return structured findings.", "x-credits": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "research_prompt" ], "properties": { "research_prompt": { "type": "string", "description": "What to research", "example": "What are Stripe's recent product launches in the last 90 days?" }, "company_domain": { "type": "string", "description": "Optional company context" }, "output_format": { "type": "string", "enum": [ "summary", "detailed", "bullets" ], "default": "summary" } } } } } }, "responses": { "200": { "description": "Research results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "research": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] }, { "OAuth2": [ "enrichment:read" ] } ] } }, "/token": { "post": { "operationId": "oauthToken", "summary": "Exchange credentials for an access token", "description": "OAuth 2.0 token endpoint. Supports authorization_code and client_credentials grant types.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "client_credentials", "refresh_token" ], "description": "OAuth grant type" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "code": { "type": "string", "description": "Authorization code (for authorization_code grant)" }, "redirect_uri": { "type": "string" }, "scope": { "type": "string", "description": "Space-separated scopes", "example": "signals:read enrichment:read systems:execute" }, "refresh_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 3600 }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } } } } } }, "400": { "description": "Invalid request or grant" }, "401": { "description": "Invalid client credentials" } } } }, "/authorize": { "get": { "operationId": "oauthAuthorize", "summary": "OAuth 2.0 authorization endpoint", "description": "Redirects the user to the Signaliz login/consent page. For M2M agents, use /token with client_credentials instead.", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "scope", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to login/consent page" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Signaliz API key. Generate at signaliz.com/settings → API Keys." }, "OAuth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://api.signaliz.com/token", "scopes": { "signals:read": "Read company signals", "enrichment:read": "Use enrichment tools (email, company)", "systems:read": "List and view systems", "systems:execute": "Create and run systems", "contracts:read": "View governance contracts", "contracts:write": "Create and modify contracts", "audit:read": "View audit trail" } }, "authorizationCode": { "authorizationUrl": "https://api.signaliz.com/authorize", "tokenUrl": "https://api.signaliz.com/token", "scopes": { "signals:read": "Read company signals", "enrichment:read": "Use enrichment tools", "systems:read": "List and view systems", "systems:execute": "Create and run systems", "contracts:read": "View governance contracts", "contracts:write": "Create and modify contracts", "audit:read": "View audit trail" } } } } }, "responses": { "BadRequest": { "description": "Bad request — invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "error_code": { "type": "string", "example": "INPUT_001" }, "suggested_action": { "type": "string" }, "doc_uri": { "type": "string" } } } } } }, "Unauthorized": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "error_code": { "type": "string", "example": "AUTH_001" }, "suggested_action": { "type": "string" }, "doc_uri": { "type": "string" } } } } } }, "RateLimited": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "error_code": { "type": "string", "example": "RATE_001" }, "retry_after_seconds": { "type": "integer" }, "doc_uri": { "type": "string" } } } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "error_code": { "type": "string", "example": "INTERNAL_001" }, "suggested_action": { "type": "string" }, "retry_eligible": { "type": "boolean" }, "doc_uri": { "type": "string" } } } } } } } } }