{ "openapi": "3.0.0", "paths": { "/v1/account-insights": { "get": { "description": "Full Access workspace read. Resolves an account by name, domain, or ID and returns the complete insight in a simplified, PDF-like structure. Designed for AI agents (e.g. Microsoft Copilot) that need the full account picture in a single call. Public API-only organizations always receive `status=not_found` on this route. At least one of query, domain, or accountId is required.\n\n**Resolution order**: accountId (direct lookup) → domain (exact match) → query (domain check, then text search).\n\n**Response `status` field**:\n- `found` — single account matched, `data` contains the full insight.\n- `multiple_matches` — text query matched several accounts. `candidates` lists them with `accountId`, `name`, and `domain`. `bestMatch` contains the highest-scored candidate. Re-call with `accountId` or `domain` to disambiguate.\n- `not_found` — no account matches the given criteria.\n\nAll resolution outcomes return HTTP 200. Only `400` is returned for missing query parameters.", "operationId": "V1DataController_getAccountInsight", "parameters": [ { "name": "signalsLimit", "required": false, "in": "query", "description": "Max signals when included (default 20, max 100)", "schema": { "type": "number" } }, { "name": "contactsLimit", "required": false, "in": "query", "description": "Max contacts when included (default 10, max 100)", "schema": { "type": "number" } }, { "name": "include", "required": false, "in": "query", "description": "Comma-separated opt-in for related resources: contacts, signals", "schema": { "example": "contacts,signals", "type": "string" } }, { "name": "sections", "required": false, "in": "query", "description": "Comma-separated list of insight sections to include in the response: profile, summary, research, swotAnalysis, value. When omitted, all sections are returned. The profile section is always included regardless of this parameter.", "schema": { "example": "profile,summary,swotAnalysis", "type": "string" } }, { "name": "accountId", "required": false, "in": "query", "description": "Direct account ID lookup. Takes priority over domain and query if multiple params are provided.", "schema": { "type": "number" } }, { "name": "domain", "required": false, "in": "query", "description": "Exact domain match. Automatically normalized: leading www/subdomains are stripped and the value is lowercased. Prefer this over query when you have a domain.", "schema": { "example": "hsbc.com", "type": "string" } }, { "name": "query", "required": false, "in": "query", "description": "Free-text company name search. Case-insensitive. If the value looks like a domain (e.g. contains a dot), it is first tried as an exact domain match before falling back to text search.", "schema": { "example": "HSBC", "type": "string" } } ], "responses": { "200": { "description": "Account insight response. Check the `status` field: found (data present), multiple_matches (candidates present), or not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountInsightResponseDto" } } } }, "400": { "description": "No query parameters provided — at least one of query, domain, or accountId is required" } }, "security": [ { "bearer": [] } ], "summary": "Full Access: Get consolidated account insight (agent-friendly, PDF-like structure)", "tags": [ "v1-data" ] } }, "/v1/accounts/{accountId}": { "get": { "description": "Full Access workspace read. Returns one tracked Salesmotion account. Public API-only organizations always receive `404` on this route.", "operationId": "V1DataController_getAccount", "parameters": [ { "name": "accountId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "view", "required": false, "in": "query", "schema": { "enum": [ "default", "export" ], "type": "string" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated account fields to select (e.g. id,name,domain)", "schema": { "type": "string" } }, { "name": "signalsLimit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "contactsLimit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "include", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account payload with optional included resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "404": { "description": "Account not found. Public API-only organizations always receive 404." } }, "security": [ { "bearer": [] } ], "summary": "Full Access: Get account data (agent-friendly representation)", "tags": [ "v1-data" ] } }, "/v1/accounts": { "get": { "description": "Full Access workspace read. Returns tracked Salesmotion accounts for the current organization. Public API-only organizations always receive an empty list on this route.", "operationId": "V1DataController_getAccounts", "parameters": [ { "name": "view", "required": false, "in": "query", "schema": { "enum": [ "default", "export" ], "type": "string" } }, { "name": "perPage", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Sort direction (default: desc)", "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Account field to sort by (default: mainScore)", "schema": { "type": "string" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated account fields to select (e.g. id,name,domain)", "schema": { "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Supported: company,owner", "schema": { "type": "string" } }, { "name": "hasSignalsOfType", "required": false, "in": "query", "description": "Combined with hasSignalsAfterDate — only count signals of this type (comma-separated, e.g. relevant-news,hiring-alert)", "schema": { "type": "string" } }, { "name": "hasSignalsAfterDate", "required": false, "in": "query", "description": "ISO date — only accounts with at least one signal after this date", "schema": { "type": "string" } }, { "name": "priority", "required": false, "in": "query", "description": "Filter by priority (1=high, 2=medium, 3=low)", "schema": { "type": "number" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by account type (e.g. prospect, customer, partner, churned, open-opportunity, competitor, other)", "schema": { "type": "string" } }, { "name": "ownerId", "required": false, "in": "query", "description": "Filter by account owner user ID", "schema": { "type": "string" } }, { "name": "companyId", "required": false, "in": "query", "description": "Filter by linked company ID", "schema": { "type": "string" } }, { "name": "domain", "required": false, "in": "query", "description": "Exact domain match (e.g. acme.com)", "schema": { "type": "string" } }, { "name": "textQuery", "required": false, "in": "query", "description": "Search accounts by name or domain", "schema": { "type": "string" } }, { "name": "ids", "required": false, "in": "query", "description": "Comma-separated account ids", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account list payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountListResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Full Access: Get account list (batch and paginated)", "tags": [ "v1-data" ] } }, "/v1/companies/{companyId}": { "get": { "description": "Public API company profile read. Resolve a company first with `/v1/companies/by-input/{companyInputId}`, then use the returned `data.id` here and on other company sub-resource endpoints. Default responses return the public company profile; generated fields such as `insights` are opt-in via `onlyWithFields`.", "operationId": "V1DataController_getCompanyById", "parameters": [ { "name": "companyId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "view", "required": false, "in": "query", "schema": { "enum": [ "default", "export" ], "type": "string" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated company fields to select (e.g. id,name,domain,insights). Generated fields remain opt-in.", "schema": { "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Supported: latestEarningsCall,latestEarningsCallAnalysis", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public company profile payload with optional included resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponseDto" } } } }, "404": { "description": "Company not found" } }, "security": [ { "bearer": [] } ], "summary": "Public API: Get company profile by canonical id", "tags": [ "v1-data" ] } }, "/v1/companies/by-input/{companyInputId}": { "get": { "description": "Public API company resolution endpoint. Supports canonical company id, domain, website URL, stock symbol, LinkedIn URL, and Crunchbase URL. Use the returned `data.id` with `/v1/companies/{companyId}` and other company sub-resource endpoints to follow the resolve-first workflow.", "operationId": "V1DataController_getCompanyByInput", "parameters": [ { "name": "view", "required": false, "in": "query", "schema": { "enum": [ "default", "export" ], "type": "string" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated company fields to select (e.g. id,name,domain,insights). Generated fields remain opt-in.", "schema": { "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Supported: latestEarningsCall,latestEarningsCallAnalysis", "schema": { "type": "string" } }, { "name": "companyInputId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolved public company profile payload with optional included resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponseDto" } } } }, "404": { "description": "Company not found for the provided input" } }, "security": [ { "bearer": [] } ], "summary": "Public API: Resolve company by input", "tags": [ "v1-data" ] } }, "/v1/companies/{companyId}/news-articles": { "get": { "description": "Public API company news collection. Resolve a company first with `/v1/companies/by-input/{companyInputId}`, then request this company sub-resource. Default responses return article metadata only. Heavy raw text is returned only when explicitly requested with `onlyWithFields=articleBody`.", "operationId": "V1DataController_getCompanyNewsArticles", "parameters": [ { "name": "companyId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "view", "required": false, "in": "query", "schema": { "enum": [ "default", "export" ], "type": "string" } }, { "name": "perPage", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated news article fields to select (e.g. id,headline,url,datePublished,articleBody). Raw text is opt-in.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public company news article list payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsArticleListResponseDto" } } } }, "404": { "description": "Company not found" } }, "security": [ { "bearer": [] } ], "summary": "Public API: Get company news articles", "tags": [ "v1-data" ] } }, "/v1/companies/{companyId}/job-openings": { "get": { "description": "Public API company job openings collection. Resolve a company first with `/v1/companies/by-input/{companyInputId}`, then request this company sub-resource. Default responses return job-opening metadata and public URLs only. Full job description text is returned only when explicitly requested with `onlyWithFields=jobDescription`.", "operationId": "V1DataController_getCompanyJobOpenings", "parameters": [ { "name": "companyId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "view", "required": false, "in": "query", "schema": { "enum": [ "default", "export" ], "type": "string" } }, { "name": "perPage", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated job opening fields to select (e.g. id,title,url,postedOn,jobDescription). Full description text is opt-in.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public company job opening list payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobOpeningListResponseDto" } } } }, "404": { "description": "Company not found" } }, "security": [ { "bearer": [] } ], "summary": "Public API: Get company job openings", "tags": [ "v1-data" ] } }, "/v1/companies/{companyId}/earnings-calls": { "get": { "description": "Public API company earnings-calls collection. Resolve a company first with `/v1/companies/by-input/{companyInputId}`, then request this company sub-resource. Default responses return financial-event metadata and safe public URLs only. Heavy transcript text and AI-generated analysis are returned only when explicitly requested with `onlyWithFields`.", "operationId": "V1DataController_getCompanyEarningsCalls", "parameters": [ { "name": "companyId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "view", "required": false, "in": "query", "schema": { "enum": [ "default", "export" ], "type": "string" } }, { "name": "perPage", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated earnings-call fields to select (e.g. id,year,audioUrl,fullTranscript,generatedAnalysis). Raw transcript text and generated analysis are opt-in.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public company earnings call list payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EarningsCallListResponseDto" } } } }, "404": { "description": "Company not found" } }, "security": [ { "bearer": [] } ], "summary": "Public API: Get company earnings calls", "tags": [ "v1-data" ] } }, "/v1/companies/{companyId}/filings": { "get": { "description": "Public API company filings collection. Resolve a company first with `/v1/companies/by-input/{companyInputId}`, then request this company sub-resource. Default responses return filing metadata and public SEC URLs only. Heavy filing text is returned only when explicitly requested with `onlyWithFields=fullContent`.", "operationId": "V1DataController_getCompanyFilings", "parameters": [ { "name": "companyId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "view", "required": false, "in": "query", "schema": { "enum": [ "default", "export" ], "type": "string" } }, { "name": "perPage", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated filing fields to select (e.g. id,type,accessionNumber,url,filingDate,fullContent). Full filing text is opt-in.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public company filing list payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingListResponseDto" } } } }, "404": { "description": "Company not found" } }, "security": [ { "bearer": [] } ], "summary": "Public API: Get company filings", "tags": [ "v1-data" ] } }, "/v1/contacts": { "get": { "description": "Full Access workspace read. Returns contacts linked to tracked accounts in the current organization. Public API-only organizations always receive an empty list on this route.", "operationId": "V1DataController_getContacts", "parameters": [ { "name": "perPage", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Sort direction (default: desc)", "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Contact field to sort by (default: inCurrentRoleSince)", "schema": { "type": "string" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated contact fields to select (e.g. id,firstName,lastName,currentTitle)", "schema": { "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Supported: account", "schema": { "type": "string" } }, { "name": "isInCurrentRoleBeforeDate", "required": false, "in": "query", "description": "ISO date — contacts in current role before this date", "schema": { "type": "string" } }, { "name": "isInCurrentRoleAfterDate", "required": false, "in": "query", "description": "ISO date — contacts in current role after this date", "schema": { "type": "string" } }, { "name": "lastChangeDetectedBefore", "required": false, "in": "query", "description": "ISO date — only contacts with changes before this date", "schema": { "type": "string" } }, { "name": "lastChangeDetectedAfter", "required": false, "in": "query", "description": "ISO date — only contacts with changes after this date", "schema": { "type": "string" } }, { "name": "currentTitleTextQuery", "required": false, "in": "query", "description": "Title-specific search", "schema": { "type": "string" } }, { "name": "textQuery", "required": false, "in": "query", "description": "Full-text search on name, title, company, location", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by contact type (e.g. prospect, champion, contact)", "schema": { "type": "string" } }, { "name": "changeType", "required": false, "in": "query", "description": "Filter by change type (e.g. promotion, newJoiner, departure, internalChange, newInRole)", "schema": { "type": "string" } }, { "name": "accountId", "required": false, "in": "query", "description": "Filter by account ID (comma-separated for multiple)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact list payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Full Access: Get contact list (paginated and filterable)", "tags": [ "v1-data" ] } }, "/v1/contacts/{contactId}": { "get": { "description": "Full Access workspace read. Returns one tracked contact. Public API-only organizations always receive `404` on this route.", "operationId": "V1DataController_getContact", "parameters": [ { "name": "contactId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated contact fields to select", "schema": { "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Supported: account", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponseDto" } } } }, "404": { "description": "Contact not found. Public API-only organizations always receive 404." } }, "security": [ { "bearer": [] } ], "summary": "Full Access: Get single contact by ID", "tags": [ "v1-data" ] } }, "/v1/signals": { "get": { "description": "Full Access workspace read. Returns signals linked to tracked accounts in the current organization. Public API-only organizations always receive an empty list on this route.", "operationId": "V1DataController_getSignals", "parameters": [ { "name": "perPage", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Sort direction (default: desc)", "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Signal field to sort by (default: date)", "schema": { "type": "string" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated signal fields to select (e.g. id,type,headline,date)", "schema": { "type": "string" } }, { "name": "textQuery", "required": false, "in": "query", "description": "Full-text search on signal content", "schema": { "type": "string" } }, { "name": "beforeDate", "required": false, "in": "query", "description": "ISO date — only signals before this date", "schema": { "type": "string" } }, { "name": "afterDate", "required": false, "in": "query", "description": "ISO date — only signals after this date", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by signal type (comma-separated, e.g. relevant-news,hiring-alert,press-release,m-and-a-alert,funding-alert,earnings-call)", "schema": { "type": "string" } }, { "name": "accountId", "required": false, "in": "query", "description": "Filter by account ID (comma-separated for multiple)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signal list payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalListResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Full Access: Get signal list (paginated and filterable)", "tags": [ "v1-data" ] } }, "/v1/signals/counts": { "get": { "description": "Full Access workspace read. Returns signal aggregates for tracked accounts in the current organization. Public API-only organizations always receive an empty object on this route.", "operationId": "V1DataController_getSignalCounts", "parameters": [ { "name": "textQuery", "required": false, "in": "query", "description": "Full-text search filter", "schema": { "type": "string" } }, { "name": "beforeDate", "required": false, "in": "query", "description": "ISO date — only count signals before this date", "schema": { "type": "string" } }, { "name": "afterDate", "required": false, "in": "query", "description": "ISO date — only count signals after this date", "schema": { "type": "string" } }, { "name": "accountId", "required": false, "in": "query", "description": "Filter by account ID (comma-separated for multiple)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signal counts by type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalCountsResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Full Access: Get signal counts by type", "tags": [ "v1-data" ] } }, "/v1/signals/{signalId}": { "get": { "description": "Full Access workspace read. Returns one tracked signal. Public API-only organizations always receive `404` on this route.", "operationId": "V1DataController_getSignal", "parameters": [ { "name": "signalId", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "onlyWithFields", "required": false, "in": "query", "description": "Comma-separated signal fields to select", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signal payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalResponseDto" } } } }, "404": { "description": "Signal not found. Public API-only organizations always receive 404." } }, "security": [ { "bearer": [] } ], "summary": "Full Access: Get single signal by ID", "tags": [ "v1-data" ] } }, "/v1/feedback": { "post": { "operationId": "V1DataController_submitFeedback", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequestDto" } } } }, "responses": { "200": { "description": "Feedback received", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Submit feedback on API usage", "tags": [ "v1-data" ] } }, "/v1/usage": { "get": { "operationId": "V1DataController_getUsage", "parameters": [ { "name": "window", "required": false, "in": "query", "schema": { "enum": [ "daily", "monthly", "custom" ], "type": "string" } }, { "name": "organizationId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "groupBy", "required": false, "in": "query", "schema": { "enum": [ "endpoint", "apiKey", "day" ], "type": "string" } }, { "name": "to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage totals and quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get customer-facing API usage and quota", "tags": [ "v1-data" ] } }, "/v1/usage/requests": { "get": { "operationId": "V1DataController_getUsageRequests", "parameters": [ { "name": "window", "required": false, "in": "query", "schema": { "enum": [ "daily", "monthly", "custom" ], "type": "string" } }, { "name": "organizationId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "perPage", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated request history for the current organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRequestsResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get recent customer-facing API request history", "tags": [ "v1-data" ] } }, "/v1/usage/limits": { "get": { "operationId": "V1DataController_getUsageLimits", "parameters": [ { "name": "organizationId", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contracted usage limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageLimitsResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get usage limits configured for the current organization", "tags": [ "v1-data" ] } } }, "info": { "title": "Salesmotion API", "description": "B2B sales intelligence platform API. For a compact LLM-optimized reference, see [llms.txt](https://api.salesmotion.io/llms.txt).\nUse `onlyWithFields` on any list endpoint to select specific fields.\n\n## Access Tiers\n\n- **Public API**: Resolve companies with `GET /v1/companies/by-input/{companyInputId}`, then use the returned\n `data.id` with `GET /v1/companies/{companyId}` and other company sub-resources. These routes return the\n public company-data contract shared by all API-enabled organizations.\n- **Full Access**: Account, contact, signal, and account-insight routes depend on tracked Salesmotion\n workspace data and are meaningful only for organizations using the full workspace product. Public API-only\n organizations receive predictable empty-list or `404` behavior on these reads, and workspace mutations\n stay blocked.\n- **Separate Connector Spec**: The account-insight-only Swagger 2.0 spec for WNS / Copilot style\n integrations remains available separately in [openapi-v2-minimal.json](openapi-v2-minimal.json).\n\n## Entity Guide\n\n### Account Insight\nA consolidated, PDF-like view of an Account returned by `GET /v1/account-insights`. Resolves an\naccount by name, domain, or ID and returns the full insight in a single call — ideal for AI agents\n(e.g. Microsoft Copilot). The response is split into sections: **profile** (basic company info,\nowner, external links), **summary** (key insights, opportunities, challenges, executive perspective),\n**research** (company overview, strategic initiatives, financials, business model), **swotAnalysis**\n(strengths, weaknesses, opportunities, threats), and **value** (three whys, value pyramid,\nvalue proposition ideas, point of view). All ContentWithCitations arrays are flattened to plain\nstring arrays for easy consumption. Contacts and signals can be optionally included via the\n`include` query parameter.\n\n### Account\nA target company that your sales organization is tracking. Accounts are the central entity —\nthey link to a Company (shared enrichment data), have Contacts (people), and receive Signals\n(business events). Each account has a mainScore (0-100) reflecting recent activity and relevance.\n\n### Contact\nA person associated with an Account. Contacts have a changeType indicating their latest career\nmove (promotion, newJoiner, departure, internalChange, newInRole). Use lastChangeDetectedOn and\ninCurrentRoleSince to find recent movers. Contacts have a mainScore reflecting targeting relevance.\n\n### Signal\nA business event detected for an Account. Signal types include: relevant-news, hiring-alert,\nhiring-alert-closed, press-release, m-and-a-alert, funding-alert, earnings-call, filing-alert,\nclinical-trial, podcast, media-document. Each signal has a date, headline, and optional description\nwith sources. Use the /signals/counts endpoint to get type-level aggregates.\n\n### Company\nEnriched company data shared across organizations. Companies have structured data from multiple\nsources (LinkedIn, Crunchbase, financial data). Resolve companies first with\n`GET /v1/companies/by-input/{companyInputId}`, then read the normalized company profile with\n`GET /v1/companies/{companyId}`.\n\n### News Article\nA public article linked to a resolved Company. Use\n`GET /v1/companies/{companyId}/news-articles` for metadata-first news records with opt-in\nfull article text via `onlyWithFields=articleBody`.\n\n### Job Opening\nA public company hiring record linked to a resolved Company. Use\n`GET /v1/companies/{companyId}/job-openings` to retrieve metadata-first job listings with\nopt-in full descriptions via `onlyWithFields=jobDescription`.\n\n### Earnings Call\nA public financial event linked to a resolved Company. Use\n`GET /v1/companies/{companyId}/earnings-calls` for fiscal period metadata, public audio,\nreport, and presentation URLs. Raw transcripts and generated analysis are opt-in via\n`onlyWithFields=fullTranscript,generatedAnalysis`.\n\n### Filing\nA public regulatory filing linked to a resolved Company. Use\n`GET /v1/companies/{companyId}/filings` for filing metadata, SEC accession numbers,\nand public URLs. Full filing text is opt-in via `onlyWithFields=fullContent`.\n\n## Entity Relationships\n- Account → Company (via companyId): One account links to one company\n- Account → Contacts (via accountId on Contact): One account has many contacts\n- Account → Signals (via accountId on Signal): One account has many signals\n- Account → Owner (via ownerId): Optional user who owns the account\n- Company → News Articles (via companyId): One company has many news articles\n- Company → Job Openings (via companyId): One company has many job openings\n- Company → Earnings Calls (via companyId): One company has many earnings calls\n- Company → Filings (via companyId): One company has many filings\n\n## Field Catalog\n\n### Account fields\nid, organizationId, companyId, ownerId, createdAt, updatedAt, name, domain, logoUrl,\nfeaturedImageUrl, description, industry, headquartersLocation, numberOfEmployees, type, priority,\nmainScore, mainScoreComponents, summary, insights, swotAnalysis, threeWhys, valuePyramid,\nvalueProposition, valueHypothesis (internal: highLevelMatch), pointOfView, linkedInUrl,\ncrunchbaseUrl, zoomInfoUrl, salesforceUrl, salesNavigatorUrl, addedOn, lastRefreshAt, countryCode\n\n### Contact fields\nid, organizationId, accountId, firstName, lastName, currentTitle, currentCompanyName, changeType,\ninCurrentRoleSince, lastChangeDetectedOn, mainScore, linkedInUrl, email, emailStatus, phone,\nlocation, previousTitle, previousCompanyName, profilePictureUrl, type, contactRole,\npersonInsights, talkingPoints, positionWhenFormerUser, introPaths, matchingTargetKeywords,\nmatchingTargetJobTitles, matchingTargetLocations, matchingTargetTechnologies\n\n### Signal fields\nid, organizationId, accountId, type, subtype, headline, description, date, sources,\nmatchingKeywords, relevance, fullContent, smartSummary, playUrls, slidesUrls, documentsUrls,\nclinicalTrialPrimaryCompletionDate, clinicalTrialStudyCompletionDate, clinicalTrialLastKnownStatus,\nclinicalTrialCollaborators, createdAt, updatedAt\n\n### Company fields\nid, name, domain, websiteUrl, description, industry, headquartersLocation, numberOfEmployees,\nmainStockSymbol, crunchbaseUrl, linkedInUrl, fiscalYearInfo, insights (opt-in)\n\n### News article fields\nid, companyId, headline, url, datePublished, description, excerpt, publisher, publisherUrl,\nfeaturedImageUrl, articleBody (opt-in)\n\n### Job opening fields\nid, companyId, status, url, title, companyName, location, postedOn, applicants, seniorityLevel,\nemploymentType, jobFunction, industries, jobDescription (opt-in)\n\n### Earnings call fields\nid, companyId, stockSymbol, year, quarter, happenedAt, audioUrl, reportUrl, presentationUrl,\nfullTranscript (opt-in), generatedAnalysis (opt-in)\n\n### Filing fields\nid, companyId, type, accessionNumber, url, filingDate, reportDate, fiscalYear, quarter,\nfullContent (opt-in)", "version": "1.0.0", "contact": {} }, "tags": [], "servers": [ { "url": "https://api.salesmotion.io", "description": "Production API" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "AccountInsightProfileDto": { "type": "object", "properties": { "accountId": { "type": "number", "example": 42 }, "name": { "type": "string", "example": "GSK" }, "domain": { "type": "string", "example": "gsk.com" }, "logoUrl": { "type": "string" }, "description": { "type": "string" }, "headquartersLocation": { "type": "string", "example": "Brentford, Middlesex" }, "industry": { "type": "string", "example": "Pharmaceutical Manufacturing" }, "numberOfEmployees": { "type": "number", "example": 187788 }, "score": { "type": "number", "example": 100 }, "type": { "type": "string", "example": "prospect" }, "priority": { "type": "number", "example": 1 }, "countryCode": { "type": "string", "example": "GB" }, "addedOn": { "type": "string" }, "lastRefreshAt": { "type": "string" }, "owner": { "type": "object", "description": "Account owner", "example": { "name": "Zeba Desai", "email": "zeba@example.com" } }, "links": { "type": "object", "description": "External links and financial metadata" } }, "required": [ "accountId" ] }, "ExecutivePerspectiveItemDto": { "type": "object", "properties": { "quote": { "type": "string" }, "attribution": { "type": "string" } }, "required": [ "quote", "attribution" ] }, "AccountInsightSummaryDto": { "type": "object", "properties": { "keyInsights": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "string" } }, "challenges": { "type": "array", "items": { "type": "string" } }, "peopleUpdates": { "type": "array", "items": { "type": "string" } }, "topNews": { "type": "array", "items": { "type": "string" } }, "talkingPoints": { "type": "array", "items": { "type": "string" } }, "executivePerspective": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutivePerspectiveItemDto" } } } }, "AccountInsightResearchDto": { "type": "object", "properties": { "companyOverview": { "type": "array", "items": { "type": "string" } }, "keyPeopleChanges": { "type": "array", "items": { "type": "string" } }, "keyProjects": { "type": "array", "items": { "type": "string" } }, "aspirations": { "type": "array", "items": { "type": "string" } }, "businessGoals": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "string" } }, "macroeconomicPerspective": { "type": "array", "items": { "type": "string" } }, "recentPressAnnouncements": { "type": "array", "items": { "type": "string" } }, "businessModel": { "type": "object", "description": "Business model from point-of-view analysis" }, "strategicInitiatives": { "type": "array", "items": { "type": "string" } }, "financials": { "type": "array", "items": { "type": "string" } } } }, "AccountInsightSwotDto": { "type": "object", "properties": { "strengths": { "type": "array", "items": { "type": "string" } }, "weaknesses": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "string" } }, "threats": { "type": "array", "items": { "type": "string" } } } }, "AccountInsightValueDto": { "type": "object", "properties": { "threeWhys": { "type": "object", "description": "Three Whys framework" }, "valuePyramid": { "type": "object", "description": "Value Pyramid breakdown" }, "valuePropositionIdeas": { "type": "array", "items": { "type": "string" } }, "valueHypothesis": { "type": "array", "items": { "type": "string" } }, "pointOfView": { "type": "array", "items": { "type": "string" } } } }, "AccountInsightDataDto": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/AccountInsightProfileDto" }, "summary": { "$ref": "#/components/schemas/AccountInsightSummaryDto" }, "research": { "$ref": "#/components/schemas/AccountInsightResearchDto" }, "swotAnalysis": { "$ref": "#/components/schemas/AccountInsightSwotDto" }, "value": { "$ref": "#/components/schemas/AccountInsightValueDto" } }, "required": [ "profile" ] }, "CandidateDto": { "type": "object", "properties": { "accountId": { "type": "number", "example": 42 }, "name": { "type": "string", "example": "HSBC Holdings" }, "domain": { "type": "string", "example": "hsbc.com" } }, "required": [ "accountId" ] }, "ResponseMetaDto": { "type": "object", "properties": { "requestId": { "type": "string", "example": "b49f1393-8089-4cad-810c-c3561f1f2a0f" }, "apiVersion": { "type": "string", "example": "v1" }, "timestamp": { "type": "string", "example": "2026-02-25T12:00:00.000Z" } }, "required": [ "requestId", "apiVersion", "timestamp" ] }, "UsageSnapshotDto": { "type": "object", "properties": { "limit": { "type": "number", "example": 10000 }, "used": { "type": "number", "example": 275 }, "remaining": { "type": "number", "example": 9725 }, "resetsAt": { "type": "string", "example": "2026-03-01T00:00:00.000Z" } }, "required": [ "limit", "used", "remaining", "resetsAt" ] }, "AccountInsightResponseDto": { "type": "object", "properties": { "status": { "type": "string", "example": "found", "enum": [ "found", "multiple_matches", "not_found" ], "description": "Resolution outcome: found (single match), multiple_matches (ambiguous query), not_found (no match)" }, "message": { "type": "string", "description": "Explanatory message for multiple_matches and not_found outcomes" }, "data": { "description": "Account insight data (present when status is found)", "allOf": [ { "$ref": "#/components/schemas/AccountInsightDataDto" } ] }, "candidates": { "description": "Matching accounts when status is multiple_matches", "type": "array", "items": { "$ref": "#/components/schemas/CandidateDto" } }, "bestMatch": { "description": "Best-scoring candidate when status is multiple_matches", "allOf": [ { "$ref": "#/components/schemas/CandidateDto" } ] }, "included": { "type": "object", "description": "Contacts and signals when requested via include param" }, "meta": { "$ref": "#/components/schemas/ResponseMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "status", "meta", "usage" ] }, "AccountDto": { "type": "object", "properties": { "id": { "type": "number", "example": 42, "description": "Unique account ID" }, "organizationId": { "type": "string", "example": "org-acme.salesmotion.test", "description": "Organization that owns this account" }, "companyId": { "type": "string", "example": "4Pl7jjFgRxKnHjnUFITd", "description": "Linked Company ID for enrichment data" }, "ownerId": { "type": "string", "example": "user_abc123", "description": "User ID of the account owner" }, "createdAt": { "type": "string", "example": "2025-06-01T10:00:00.000Z" }, "updatedAt": { "type": "string", "example": "2026-02-20T14:30:00.000Z" }, "name": { "type": "string", "example": "Acme Inc", "description": "Display name of the account" }, "domain": { "type": "string", "example": "acme.com", "description": "Primary website domain" }, "logoUrl": { "type": "string", "example": "https://logo.clearbit.com/acme.com", "description": "Company logo URL" }, "featuredImageUrl": { "type": "string", "description": "Featured/banner image URL" }, "description": { "type": "string", "example": "Acme Inc is a leading provider of...", "description": "Company description" }, "industry": { "type": "string", "example": "Software", "description": "Industry classification" }, "headquartersLocation": { "type": "string", "example": "San Francisco, CA", "description": "Headquarters location" }, "numberOfEmployees": { "type": "number", "example": 5000, "description": "Estimated employee count" }, "type": { "type": "string", "example": "prospect", "description": "Account type: prospect, customer, partner, churned, open-opportunity, competitor, other" }, "priority": { "type": "number", "example": 1, "description": "Priority level: 1 (high), 2 (medium), 3 (low)" }, "mainScore": { "type": "number", "example": 85, "description": "Salesmotion score (0-100) reflecting recent activity and relevance" }, "mainScoreComponents": { "type": "object", "description": "Score breakdown: contactsChanges and recentSignals contributing to mainScore" }, "summary": { "type": "object", "description": "AI-generated multi-section summary with keyInsights, opportunities, challenges, executivePerspective, talkingPoints" }, "insights": { "type": "object", "description": "AI-generated account insights grouped by topic: companyOverview, strategicInitiatives, financials, keyPeopleChanges, keyProjects, aspirations, macroeconomicPerspective, industryPerspective, recentPressAnnouncements, businessGoals, opportunities. Request via onlyWithFields." }, "swotAnalysis": { "type": "object", "description": "SWOT analysis with strengths, weaknesses, opportunities, threats, and positioning — each as ContentWithCitations. Request via onlyWithFields." }, "threeWhys": { "type": "object", "description": "The Three Whys framework: whyChange, whyNow, whyYou — each with summary and details as ContentWithCitations. Request via onlyWithFields." }, "valuePyramid": { "type": "object", "description": "Value Pyramid: companyGoals, businessStrategy, challengesAndObstacles, valuePaths — each as ContentWithCitations. Request via onlyWithFields." }, "valueProposition": { "type": "object", "description": "Value proposition ideas generated for this account. Array of strategic value proposition strings. Request via onlyWithFields." }, "valueHypothesis": { "type": "object", "description": "Value hypothesis (internal: highLevelMatch) — a text summary of why this account is a good fit. Request via onlyWithFields." }, "pointOfView": { "type": "object", "description": "Account point of view with accountOverview (revenueStreams, goToMarketStrategy, idealCustomerProfile, keyPriorities, marketPosition, competitiveDynamics, businessRisks), synthesis, and pointOfViewHypothesis. Request via onlyWithFields." }, "linkedInUrl": { "type": "string", "example": "https://www.linkedin.com/company/acme", "description": "LinkedIn company page URL" }, "crunchbaseUrl": { "type": "string", "example": "https://www.crunchbase.com/organization/acme", "description": "Crunchbase profile URL" }, "zoomInfoUrl": { "type": "string", "description": "ZoomInfo profile URL" }, "salesforceUrl": { "type": "string", "description": "Salesforce record URL" }, "salesNavigatorUrl": { "type": "string", "description": "Sales Navigator account URL" }, "addedOn": { "type": "string", "example": "2025-06-01T10:00:00.000Z", "description": "When the account was added to the organization" }, "lastRefreshAt": { "type": "string", "example": "2026-02-20T14:30:00.000Z", "description": "Last automated data refresh timestamp" }, "countryCode": { "type": "string", "example": "US", "description": "ISO 3166-1 alpha-2 country code" } }, "required": [ "id", "organizationId", "createdAt", "updatedAt", "type" ] }, "AccountResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountDto" }, "included": { "type": "object", "description": "Included related resources (company, contacts, signals, owner) when requested via include param" }, "meta": { "$ref": "#/components/schemas/ResponseMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "PaginationMetaDto": { "type": "object", "properties": { "requestId": { "type": "string", "example": "b49f1393-8089-4cad-810c-c3561f1f2a0f" }, "apiVersion": { "type": "string", "example": "v1" }, "timestamp": { "type": "string", "example": "2026-02-25T12:00:00.000Z" }, "page": { "type": "number", "example": 1 }, "perPage": { "type": "number", "example": 20 }, "totalCount": { "type": "number", "example": 100 }, "totalPages": { "type": "number", "example": 5 } }, "required": [ "requestId", "apiVersion", "timestamp", "page", "perPage", "totalCount", "totalPages" ] }, "AccountListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountDto" } }, "included": { "type": "object", "description": "Included related resources when requested via include param" }, "meta": { "$ref": "#/components/schemas/PaginationMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "CompanyDto": { "type": "object", "properties": { "id": { "type": "string", "example": "4Pl7jjFgRxKnHjnUFITd", "description": "Unique company ID" }, "name": { "type": "string", "example": "Acme Inc", "description": "Company name" }, "domain": { "type": "string", "example": "acme.com", "description": "Primary domain" }, "websiteUrl": { "type": "string", "example": "https://www.acme.com", "description": "Company website URL" }, "description": { "type": "string", "example": "Acme Inc is a leading provider of...", "description": "Company description" }, "industry": { "type": "string", "example": "Software", "description": "Industry classification" }, "headquartersLocation": { "type": "string", "example": "San Francisco, CA", "description": "Headquarters location" }, "numberOfEmployees": { "type": "number", "example": 5000, "description": "Estimated employee count" }, "mainStockSymbol": { "type": "string", "example": "ACME", "description": "Main stock ticker symbol" }, "crunchbaseUrl": { "type": "string", "example": "https://www.crunchbase.com/organization/acme", "description": "Crunchbase profile URL" }, "linkedInUrl": { "type": "string", "example": "https://www.linkedin.com/company/acme", "description": "LinkedIn company page URL" }, "fiscalYearInfo": { "type": "object", "description": "Fiscal year information: year start, quarters, current quarter" }, "insights": { "type": "object", "description": "AI-generated company insights grouped by topic. Omitted by default; request via onlyWithFields." } }, "required": [ "id" ] }, "CompanyResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyDto" }, "included": { "type": "object", "description": "Included related resources (latestEarningsCall) when requested via include param" }, "meta": { "$ref": "#/components/schemas/ResponseMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "NewsArticleDto": { "type": "object", "properties": { "id": { "type": "string", "example": "news_abc123", "description": "Unique news article ID" }, "companyId": { "type": "string", "example": "4Pl7jjFgRxKnHjnUFITd", "description": "Linked company ID" }, "headline": { "type": "string", "example": "Acme launches new AI platform", "description": "Article headline" }, "url": { "type": "string", "example": "https://news.example.com/acme-ai-platform", "description": "Canonical public article URL" }, "datePublished": { "type": "string", "example": "2026-04-20", "description": "Publication date (ISO date)" }, "description": { "type": "string", "example": "Acme announced a new AI platform for revenue teams." }, "excerpt": { "type": "string", "example": "The launch expands Acme’s enterprise AI offering." }, "publisher": { "type": "string", "example": "TechCrunch", "description": "Publisher name" }, "publisherUrl": { "type": "string", "example": "https://techcrunch.com", "description": "Publisher home page URL" }, "featuredImageUrl": { "type": "string", "example": "https://images.example.com/acme-ai.jpg", "description": "Featured image URL" }, "articleBody": { "type": "string", "description": "Full raw article text. Omitted by default; request via onlyWithFields=articleBody." } }, "required": [ "id", "url", "datePublished" ] }, "NewsArticleListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NewsArticleDto" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "JobOpeningDto": { "type": "object", "properties": { "id": { "type": "string", "example": "job_abc123", "description": "Unique job opening ID" }, "companyId": { "type": "string", "example": "4Pl7jjFgRxKnHjnUFITd", "description": "Linked company ID" }, "status": { "type": "string", "example": "online", "description": "Current observed job status" }, "url": { "type": "string", "example": "https://www.linkedin.com/jobs/view/1234567890", "description": "Canonical public job posting URL" }, "title": { "type": "string", "example": "Senior Account Executive", "description": "Job title" }, "companyName": { "type": "string", "example": "Acme Inc", "description": "Company name shown on the posting" }, "location": { "type": "string", "example": "San Francisco, CA", "description": "Job location text" }, "postedOn": { "type": "string", "example": "2026-04-20", "description": "Posting date (ISO date)" }, "applicants": { "type": "string", "example": "11-50 applicants", "description": "Public applicants summary text" }, "seniorityLevel": { "type": "string", "example": "Mid-Senior level" }, "employmentType": { "type": "string", "example": "Full-time" }, "jobFunction": { "type": "string", "example": "Sales" }, "industries": { "type": "string", "example": "Software Development" }, "jobDescription": { "type": "string", "description": "Full job description text. Omitted by default; request via onlyWithFields=jobDescription." } }, "required": [ "id", "url", "postedOn" ] }, "JobOpeningListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobOpeningDto" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "EarningsCallDto": { "type": "object", "properties": { "id": { "type": "number", "example": 101, "description": "Unique earnings call ID" }, "companyId": { "type": "string", "example": "4Pl7jjFgRxKnHjnUFITd", "description": "Linked company ID" }, "stockSymbol": { "type": "string", "example": "ACME", "description": "Reported stock ticker symbol" }, "year": { "type": "number", "example": 2026, "description": "Fiscal year for the earnings call" }, "quarter": { "type": "number", "example": 1, "description": "Fiscal quarter for the earnings call" }, "happenedAt": { "type": "string", "example": "2026-04-22T14:00:00.000Z", "description": "Public event timestamp (ISO datetime)" }, "audioUrl": { "type": "string", "example": "https://quartr.com/events/acme-q1-2026/audio", "description": "Canonical public audio URL when available" }, "reportUrl": { "type": "string", "example": "https://quartr.com/events/acme-q1-2026/report", "description": "Canonical public report or press-release URL when available" }, "presentationUrl": { "type": "string", "example": "https://quartr.com/events/acme-q1-2026/slides", "description": "Canonical public slide deck or presentation URL when available" }, "fullTranscript": { "type": "string", "description": "Full raw transcript text. Omitted by default; request via onlyWithFields=fullTranscript." }, "generatedAnalysis": { "type": "object", "description": "AI-generated / derived earnings-call analysis. Omitted by default; request via onlyWithFields=generatedAnalysis." } }, "required": [ "id" ] }, "EarningsCallListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EarningsCallDto" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "FilingDto": { "type": "object", "properties": { "id": { "type": "number", "example": 501, "description": "Unique filing ID" }, "companyId": { "type": "string", "example": "4Pl7jjFgRxKnHjnUFITd", "description": "Linked company ID" }, "type": { "type": "string", "example": "10-Q", "description": "Public filing type" }, "accessionNumber": { "type": "string", "example": "0001234567-26-000001", "description": "Public filing accession number" }, "url": { "type": "string", "example": "https://www.sec.gov/Archives/edgar/data/1234567/000123456726000001/form10q.htm", "description": "Canonical public filing URL" }, "filingDate": { "type": "string", "example": "2026-04-25T00:00:00.000Z", "description": "Filing date (ISO datetime)" }, "reportDate": { "type": "string", "example": "2026-03-31T00:00:00.000Z", "description": "Covered report date (ISO datetime)" }, "fiscalYear": { "type": "number", "example": 2026, "description": "Reported fiscal year when available" }, "quarter": { "type": "number", "example": 1, "description": "Reported fiscal quarter when available" }, "fullContent": { "type": "string", "description": "Full filing text. Omitted by default; request via onlyWithFields=fullContent." } }, "required": [ "id" ] }, "FilingListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FilingDto" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "ContactDto": { "type": "object", "properties": { "id": { "type": "string", "example": "cnt_abc123", "description": "Unique contact ID" }, "organizationId": { "type": "string", "example": "org-acme.salesmotion.test", "description": "Organization that owns this contact" }, "accountId": { "type": "number", "example": 42, "description": "Account this contact belongs to" }, "firstName": { "type": "string", "example": "Jane", "description": "First name" }, "lastName": { "type": "string", "example": "Doe", "description": "Last name" }, "currentTitle": { "type": "string", "example": "VP of Engineering", "description": "Current job title" }, "currentCompanyName": { "type": "string", "example": "Acme Inc", "description": "Current employer name" }, "changeType": { "type": "string", "example": "promotion", "description": "Latest career change type: promotion, newJoiner, departure, internalChange, newInRole" }, "inCurrentRoleSince": { "type": "string", "example": "2025-09-01", "description": "Date the contact started their current role" }, "lastChangeDetectedOn": { "type": "string", "example": "2025-12-15", "description": "Date the latest career change was detected" }, "mainScore": { "type": "number", "example": 85, "description": "Targeting relevance score (0-100)" }, "linkedInUrl": { "type": "string", "example": "https://www.linkedin.com/in/janedoe", "description": "LinkedIn profile URL" }, "email": { "type": "string", "example": "jane@acme.com", "description": "Email address (if enriched)" }, "emailStatus": { "type": "string", "example": "current", "description": "Email validation status: current, stale, uncertain, notFound" }, "phone": { "type": "string", "example": "+1-555-0123", "description": "Phone number (if enriched)" }, "location": { "type": "string", "example": "San Francisco, CA", "description": "Contact location" }, "previousTitle": { "type": "string", "example": "Senior Engineer", "description": "Previous job title (before career change)" }, "previousCompanyName": { "type": "string", "example": "OtherCorp", "description": "Previous employer name (before career change)" }, "profilePictureUrl": { "type": "string", "description": "Profile picture URL" }, "type": { "type": "string", "example": "prospect", "description": "Contact type: prospect, champion, contact" }, "contactRole": { "type": "string", "example": "decision-maker", "description": "Contact role classification" }, "personInsights": { "type": "object", "description": "AI-generated person insights: highlights, personality, howToSellToThisPerson. Request via onlyWithFields." }, "talkingPoints": { "type": "object", "description": "AI-generated talking points with challenge/support pairs. Request via onlyWithFields." }, "positionWhenFormerUser": { "type": "object", "description": "Position details when this contact is a former user of your product: jobTitle, company, startDate, endDate" }, "introPaths": { "description": "Introduction paths to this contact via shared connections, each with intermediary contact details and relationship context", "type": "array", "items": { "type": "string" } }, "matchingTargetKeywords": { "description": "Target keywords this contact matches from your organization targeting criteria", "type": "array", "items": { "type": "string" } }, "matchingTargetJobTitles": { "description": "Target job titles this contact matches from your organization targeting criteria", "type": "array", "items": { "type": "string" } }, "matchingTargetLocations": { "description": "Target locations this contact matches from your organization targeting criteria", "type": "array", "items": { "type": "string" } }, "matchingTargetTechnologies": { "description": "Target technologies this contact matches from your organization targeting criteria", "type": "array", "items": { "type": "string" } } }, "required": [ "id", "organizationId" ] }, "ContactListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactDto" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "ContactResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactDto" }, "meta": { "$ref": "#/components/schemas/ResponseMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "SignalDto": { "type": "object", "properties": { "id": { "type": "number", "example": 100, "description": "Unique signal ID" }, "organizationId": { "type": "string", "example": "org-acme.salesmotion.test", "description": "Organization that owns this signal" }, "accountId": { "type": "number", "example": 42, "description": "Account this signal belongs to" }, "type": { "type": "string", "example": "relevant-news", "description": "Signal type: relevant-news, hiring-alert, hiring-alert-closed, press-release, m-and-a-alert, funding-alert, earnings-call, filing-alert, clinical-trial, podcast, media-document" }, "subtype": { "type": "string", "example": "product-launch", "description": "Signal subtype for more granular classification" }, "headline": { "type": "string", "example": "Acme launches new AI-powered analytics platform", "description": "Signal headline" }, "description": { "type": "string", "example": "Acme Inc announced today...", "description": "Signal description text" }, "date": { "type": "string", "example": "2026-01-15", "description": "Date the event occurred (ISO date)" }, "sources": { "description": "Source URLs and metadata for this signal", "example": [ { "url": "https://techcrunch.com/article", "name": "TechCrunch" } ], "type": "array", "items": { "type": "string" } }, "matchingKeywords": { "description": "Keywords that matched this signal to the account", "example": [ { "label": "AI", "priority": "high" } ], "type": "array", "items": { "type": "string" } }, "relevance": { "type": "object", "description": "Relevance assessment with score and explanation", "example": { "score": 90, "explanation": "Directly mentions product expansion" } }, "fullContent": { "type": "string", "description": "Full content/transcript. Request via onlyWithFields." }, "smartSummary": { "type": "object", "description": "AI-generated smart summary (for earnings calls). Request via onlyWithFields." }, "playUrls": { "type": "object", "description": "Audio/podcast play URLs (audio, spotify, itunes). Request via onlyWithFields." }, "slidesUrls": { "description": "Slide deck URLs. Request via onlyWithFields.", "type": "array", "items": { "type": "string" } }, "documentsUrls": { "description": "Document URLs (name + url). Request via onlyWithFields.", "type": "array", "items": { "type": "string" } }, "clinicalTrialPrimaryCompletionDate": { "type": "string", "example": "2027-03-15", "description": "Clinical trial primary completion date" }, "clinicalTrialStudyCompletionDate": { "type": "string", "example": "2027-06-30", "description": "Clinical trial study completion date" }, "clinicalTrialLastKnownStatus": { "type": "string", "example": "Recruiting", "description": "Clinical trial last known status" }, "clinicalTrialCollaborators": { "description": "Clinical trial collaborating organizations", "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "example": "2026-01-16T08:00:00.000Z" }, "updatedAt": { "type": "string", "example": "2026-01-16T08:00:00.000Z" } }, "required": [ "id", "organizationId", "accountId", "type", "headline", "date", "createdAt", "updatedAt" ] }, "SignalListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignalDto" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "SignalCountsResponseDto": { "type": "object", "properties": { "data": { "type": "object", "example": { "all": 42, "accounts": 10, "relevant-news": 15, "hiring-alert": 8, "press-release": 5, "earnings-call": 3 }, "description": "Signal counts grouped by type" }, "meta": { "$ref": "#/components/schemas/ResponseMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "SignalResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SignalDto" }, "meta": { "$ref": "#/components/schemas/ResponseMetaDto" }, "usage": { "$ref": "#/components/schemas/UsageSnapshotDto" } }, "required": [ "data", "meta", "usage" ] }, "FeedbackRequestDto": { "type": "object", "properties": { "rating": { "type": "number", "example": 4, "description": "Overall satisfaction rating (1-5)" }, "category": { "type": "string", "example": "missing-data", "description": "Feedback category: missing-data, wrong-data, api-usability, feature-request, other" }, "message": { "type": "string", "example": "The signal descriptions are very helpful for prioritizing outreach", "description": "Free-text feedback message" }, "context": { "type": "object", "description": "Context about what the agent was doing when providing feedback", "example": { "endpoint": "/v1/accounts", "accountId": 42 } } }, "required": [ "message" ] }, "FeedbackResponseDto": { "type": "object", "properties": { "data": { "type": "object", "example": { "received": true }, "description": "Feedback confirmation" }, "meta": { "$ref": "#/components/schemas/ResponseMetaDto" } }, "required": [ "data", "meta" ] }, "UsageBreakdownItemDto": { "type": "object", "properties": { "key": { "type": "string", "example": "GetCompanyLatestEarningsCallUseCase" }, "requests": { "type": "number", "example": 25 }, "successful": { "type": "number", "example": 24 }, "failed": { "type": "number", "example": 1 } }, "required": [ "key", "requests", "successful", "failed" ] }, "UsageDataDto": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "daily", "monthly", "custom" ], "example": "monthly" }, "from": { "type": "string", "example": "2026-02-01T00:00:00.000Z" }, "to": { "type": "string", "example": "2026-02-25T12:00:00.000Z" }, "quota": { "$ref": "#/components/schemas/UsageSnapshotDto" }, "totals": { "type": "object", "example": { "requests": 275, "successful": 270, "failed": 5 } }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBreakdownItemDto" } } }, "required": [ "window", "from", "to", "quota", "totals" ] }, "UsageResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UsageDataDto" }, "meta": { "$ref": "#/components/schemas/ResponseMetaDto" } }, "required": [ "data", "meta" ] }, "UsageRequestDto": { "type": "object", "properties": { "id": { "type": "number", "example": 12345, "description": "Unique internal event ID for this tracked API request" }, "occurredAt": { "type": "string", "example": "2026-05-07T12:34:56.000Z", "description": "When the API request was recorded" }, "endpoint": { "type": "string", "example": "GET /v1/companies/:companyId/news-articles" }, "successful": { "type": "boolean", "example": true, "description": "Whether the tracked request completed without a recorded error" }, "error": { "type": "string", "example": "Company not found", "description": "Recorded error message for failed requests" }, "apiKeyId": { "type": "string", "example": "api_key_123", "description": "Internal API key ID when the request used an API key" }, "input": { "type": "object", "description": "Tracked request input such as path params and query string values", "example": { "params": { "companyId": "cmp_123" }, "query": { "perPage": "20", "page": "1" } } } }, "required": [ "id", "occurredAt", "endpoint", "successful" ] }, "UsageRequestsResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRequestDto" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaDto" } }, "required": [ "data", "meta" ] }, "UsageLimitsResponseDto": { "type": "object", "properties": { "data": { "type": "object", "example": { "daily": { "limit": 1000 }, "monthly": { "limit": 10000 } } }, "meta": { "$ref": "#/components/schemas/ResponseMetaDto" } }, "required": [ "data", "meta" ] } } }, "externalDocs": { "description": "LLM-optimized API reference (compact Markdown)", "url": "https://api.salesmotion.io/llms.txt" } }