# Salesmotion API > Compact API reference for AI agents. For the full OpenAPI spec with JSON schemas, see [openapi.json](openapi.json). Base URL: `https://api.salesmotion.io` Auth: `Authorization: Bearer ` ## Validation and Usage Data and feedback routes require API access to be enabled for the organization, including requests authenticated with a user token. Usage routes remain available to authenticated users for their own organization. Invalid identifiers, dates, enum values, sort fields, query shapes, and feedback return HTTP 400. Numeric resource IDs must be positive integers. Pages start at 1. Dates accept ISO dates or timestamps with a timezone. Unknown field selections are omitted. Unknown query parameter names are rejected. Daily and monthly allowances use rolling 24-hour and 30-day windows. A limit of 0 means unlimited. Successful calls and active requests consume allowance; failed calls do not. Exhausted allowance returns HTTP 429. Usage totals separate successful, failed, and pending calls. Unfinished reservations expire after 15 minutes. resetsAt is the next counted request expiry, so allowance returns incrementally. Usage headers describe the monthly window. Access tiers: - `Public API`: company resolution and company sub-resource reads shared by both full-workspace and public-api-only organizations. - `Full Access`: workspace-backed account, contact, signal, and account-insight reads. Public API-only organizations receive predictable empty-list or `404` behavior on these routes. - `Life Sciences`: clinical trial, Trial Radar and company tag routes, available to organizations with the Life Sciences pack; others receive `403`. Company and trial reads cover every company in the catalog. Trial Radar and account trials follow the Full Access tier. - Separate account-insight connector spec: [openapi-v2-minimal.json](openapi-v2-minimal.json). ## Field Catalog ### Account fields id, organizationId, companyId, ownerId, createdAt, updatedAt, name, domain, logoUrl, featuredImageUrl, description, industry, headquartersLocation, numberOfEmployees, type, priority, mainScore, mainScoreComponents, summary, insights, swotAnalysis, threeWhys, valuePyramid, valueProposition, valueHypothesis (internal: highLevelMatch), pointOfView, linkedInUrl, crunchbaseUrl, zoomInfoUrl, salesforceUrl, salesNavigatorUrl, addedOn, lastRefreshAt, countryCode ### Contact fields id, organizationId, accountId, firstName, lastName, currentTitle, currentCompanyName, changeType, inCurrentRoleSince, lastChangeDetectedOn, mainScore, linkedInUrl, email, emailStatus, phone, location, previousTitle, previousCompanyName, profilePictureUrl, type, contactRole, personInsights, talkingPoints, positionWhenFormerUser, introPaths, matchingTargetKeywords, matchingTargetJobTitles, matchingTargetLocations, matchingTargetTechnologies ### Signal fields id, organizationId, accountId, type, subtype, headline, description, date, sources, matchingKeywords, relevance, fullContent, smartSummary, playUrls, slidesUrls, documentsUrls, clinicalTrialPrimaryCompletionDate, clinicalTrialStudyCompletionDate, clinicalTrialLastKnownStatus, clinicalTrialCollaborators, clinicalTrialId, configuredSignalId, createdAt, updatedAt ### Company fields id, name, domain, websiteUrl, description, industry, headquartersLocation, numberOfEmployees, mainStockSymbol, crunchbaseUrl, linkedInUrl, fiscalYearInfo, insights (opt-in) ### News article fields id, companyId, headline, url, datePublished, description, excerpt, publisher, publisherUrl, featuredImageUrl, articleBody (opt-in) ### Job opening fields id, companyId, status, url, title, companyName, location, postedOn, applicants, seniorityLevel, employmentType, jobFunction, industries, jobDescription (opt-in) ### Earnings call fields id, companyId, stockSymbol, year, quarter, happenedAt, audioUrl, reportUrl, presentationUrl, callType, title, sourceUrl, artifacts, fullTranscript (opt-in), generatedAnalysis (opt-in) ### Filing fields id, companyId, type, accessionNumber, url, filingDate, reportDate, fiscalYear, quarter, fullContent (opt-in) ### Clinical trial fields (Life Sciences) id, registry, nctId, euCtNumber, url, briefTitle, officialTitle, briefSummary, detailedDescription, studyType, phases, lastKnownStatus, whyStopped, leadSponsor, collaborators, firstPostedDate, registryStartDate, actualStartDate, estimatedStartDate, actualPrimaryCompletionDate, estimatedPrimaryCompletionDate, actualStudyCompletionDate, estimatedStudyCompletionDate, resultsFirstPostedDate, lastUpdatePostDate, estimatedEnrollment, actualEnrollment, conditions, indications, keywords, interventions, therapeuticAreas, modalities, designInfo, eligibility, pointOfContact, locations, siteRegions, createdAt, updatedAt Lists add companyRoles; a single trial adds companies. Lists leave officialTitle, briefSummary, detailedDescription, keywords, interventions, designInfo, eligibility, pointOfContact, locations, firstPostedDate, registryStartDate, resultsFirstPostedDate, whyStopped, createdAt and updatedAt out unless onlyWithFields asks for them. ### Company tag fields (Life Sciences) id, companyId, definitionKey, categoryKey, value, label, activityStartedOn, activityLastSupportedOn, visibleUntil, evidenceCount ## Life Sciences Enum Catalog - Trial registry: clinicalTrialsGov, euCtis - Trial phase: notAvailable, earlyPhase1, phase1, phase2, phase3, phase4 - Trial status: activeNotRecruiting, completed, enrollingByInvitation, notYetRecruiting, recruiting, suspended, terminated, withdrawn, available, noLongerAvailable, temporarilyNotAvailable, approvedForMarketing, withheld, unknown - Company role on a trial: leadSponsor, collaborator, responsibleParty, facility - Therapeutic area: cardiovascular, dermatology, endocrinology, gastroenterology, hematology, immunology, infectiousDiseases, nephrology, neurology, oncology, ophthalmology, psychiatry, rareDiseases, respiratory, rheumatology, womensHealth - Therapeutic modality: smallMolecules, largeMoleculesBiologics, cellTherapies, geneTherapies, rnaTherapies, vaccines, radiopharmaceuticals - Company tag definitionKey: therapeuticArea, therapeuticModality, lifecycleMoment, topic, organizationType - Trial Radar lens: startingSoon, completingSoon - Clinical-trial signal subtype: trial-started, phase-transition, trial-readout, site-activation --- ## GET /v1/analytics/events Service Account: Get raw organization activity events | Param | Type | Required | Description | |-------|------|----------|-------------| | `occurredBefore` | string | no | ISO timestamp, inclusive | | `occurredAfter` | string | no | ISO timestamp, inclusive | | `eventType` | string | no | Comma-separated event types | | `userId` | string | no | Comma-separated user IDs | | `limit` | number | no | Page size, default 100 and maximum 200 | | `cursor` | string | no | Opaque cursor from the previous page | **200** Organization activity events and the next-page cursor when more results exist --- ## GET /v1/account-insights 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. **Resolution order**: accountId (direct lookup) → domain (exact match) → query (domain check, then text search). **Response `status` field**: - `found` — single account matched, `data` contains the full insight. - `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. - `not_found` — no account matches the given criteria. All resolution outcomes return HTTP 200. Only `400` is returned for missing query parameters. | Param | Type | Required | Description | |-------|------|----------|-------------| | `signalsLimit` | number | no | Max signals when included (default 20, max 100) | | `contactsLimit` | number | no | Max contacts when included (default 10, max 100) | | `include` | string | no | Comma-separated opt-in for related resources: contacts, signals | | `sections` | string | no | 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. | | `accountId` | number | no | Direct account ID lookup. Takes priority over domain and query if multiple params are provided. | | `domain` | string | no | Exact domain match. Automatically normalized: leading www/subdomains are stripped and the value is lowercased. Prefer this over query when you have a domain. | | `query` | string | no | Case-insensitive substring search on company name or domain, without fuzzy or typo matching. 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. | **200** Account insight response. Check the `status` field: found (data present), multiple_matches (candidates present), or not_found. ``` { status: string message?: string data?: { profile: { accountId, name?, domain?, logoUrl?, description?, headquartersLocation?, industry?, numberOfEmployees?, score?, type?, priority?, countryCode?, addedOn?, lastRefreshAt?, owner?, links? } summary?: { keyInsights?, opportunities?, challenges?, peopleUpdates?, topNews?, talkingPoints?, executivePerspective? } research?: { companyOverview?, keyPeopleChanges?, keyProjects?, aspirations?, businessGoals?, opportunities?, macroeconomicPerspective?, recentPressAnnouncements?, businessModel?, strategicInitiatives?, financials? } swotAnalysis?: { strengths?, weaknesses?, opportunities?, threats? } value?: { threeWhys?, valuePyramid?, valuePropositionIdeas?, valueHypothesis?, pointOfView? } } candidates?: [{ accountId: number name?: string domain?: string }] bestMatch?: { accountId: number name?: string domain?: string } included?: object meta: { requestId: string apiVersion: string timestamp: string } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **400** No query parameters provided — at least one of query, domain, or accountId is required --- ## GET /v1/accounts/{accountId} Full Access workspace read. Returns one tracked Salesmotion account. Public API-only organizations always receive `404` on this route. | Param | Type | Required | Description | |-------|------|----------|-------------| | `accountId` | number | yes | | | `view` | `default`, `export` | no | | | `onlyWithFields` | string | no | Comma-separated account fields to select (e.g. id,name,domain) | | `signalsLimit` | number | no | | | `contactsLimit` | number | no | | | `include` | string | no | | **200** Account payload with optional included resources ``` { data: { id: number organizationId: string companyId?: string ownerId?: string createdAt: string updatedAt: string name?: string domain?: string logoUrl?: string featuredImageUrl?: string description?: string industry?: string headquartersLocation?: string numberOfEmployees?: number type: string priority?: number mainScore?: number mainScoreComponents?: object summary?: object insights?: object swotAnalysis?: object threeWhys?: object valuePyramid?: object valueProposition?: object valueHypothesis?: object pointOfView?: object linkedInUrl?: string crunchbaseUrl?: string zoomInfoUrl?: string salesforceUrl?: string hubspotUrl?: string salesNavigatorUrl?: string addedOn?: string lastRefreshAt?: string countryCode?: string } included?: object meta: { requestId: string apiVersion: string timestamp: string } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **404** Account not found. Public API-only organizations always receive 404. --- ## GET /v1/accounts Full Access workspace read. Returns tracked Salesmotion accounts for the current organization. Public API-only organizations always receive an empty list on this route. | Param | Type | Required | Description | |-------|------|----------|-------------| | `view` | `default`, `export` | no | | | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `sortOrder` | `asc`, `desc` | no | Sort direction (default: desc) | | `sortBy` | `id`, `name`, `domain`, `createdAt`, `updatedAt`, `type`, `priority`, `mainScore`, `addedOn`, `lastRefreshAt`, `numberOfEmployees`, `industry`, `countryCode`, `ownerId` | no | Account field to sort by (default: mainScore) | | `onlyWithFields` | string | no | Comma-separated account fields to select (e.g. id,name,domain) | | `include` | string | no | Supported: company,owner | | `hasSignalsOfType` | string | no | Combined with hasSignalsAfterDate — only count signals of this type (comma-separated, e.g. relevant-news,hiring-alert) | | `hasSignalsAfterDate` | string | no | ISO date — only accounts with at least one signal after this date | | `priority` | number | no | Filter by priority (1=high, 2=medium, 3=low) | | `type` | string | no | Filter by account type (e.g. prospect, customer, partner, churned, open-opportunity, competitor, other) | | `ownerId` | string | no | Filter by account owner user ID | | `companyId` | string | no | Filter by linked company ID | | `domain` | string | no | Exact domain match (e.g. acme.com) | | `textQuery` | string | no | Case-insensitive substring search on account name or domain. No fuzzy or typo matching. Results follow sortBy and sortOrder. | | `ids` | string | no | Comma-separated account ids | **200** Account list payload ``` { data: [{ id: number organizationId: string companyId?: string ownerId?: string createdAt: string updatedAt: string name?: string domain?: string logoUrl?: string featuredImageUrl?: string description?: string industry?: string headquartersLocation?: string numberOfEmployees?: number type: string priority?: number mainScore?: number mainScoreComponents?: object summary?: object insights?: object swotAnalysis?: object threeWhys?: object valuePyramid?: object valueProposition?: object valueHypothesis?: object pointOfView?: object linkedInUrl?: string crunchbaseUrl?: string zoomInfoUrl?: string salesforceUrl?: string hubspotUrl?: string salesNavigatorUrl?: string addedOn?: string lastRefreshAt?: string countryCode?: string }] included?: object meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` --- ## GET /v1/companies/{companyId} 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`. | Param | Type | Required | Description | |-------|------|----------|-------------| | `companyId` | string | yes | | | `view` | `default`, `export` | no | | | `onlyWithFields` | string | no | Comma-separated company fields to select (e.g. id,name,domain,insights). Generated fields remain opt-in. | | `include` | string | no | Supported: latestEarningsCall,latestEarningsCallAnalysis | **200** Public company profile payload with optional included resources ``` { data: { id: string name?: string domain?: string websiteUrl?: string description?: string industry?: string headquartersLocation?: string numberOfEmployees?: number mainStockSymbol?: string crunchbaseUrl?: string linkedInUrl?: string fiscalYearInfo?: object insights?: object } included?: object meta: { requestId: string apiVersion: string timestamp: string } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **404** Company not found --- ## GET /v1/companies/by-input/{companyInputId} 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. | Param | Type | Required | Description | |-------|------|----------|-------------| | `view` | `default`, `export` | no | | | `onlyWithFields` | string | no | Comma-separated company fields to select (e.g. id,name,domain,insights). Generated fields remain opt-in. | | `include` | string | no | Supported: latestEarningsCall,latestEarningsCallAnalysis | | `companyInputId` | string | yes | | **200** Resolved public company profile payload with optional included resources ``` { data: { id: string name?: string domain?: string websiteUrl?: string description?: string industry?: string headquartersLocation?: string numberOfEmployees?: number mainStockSymbol?: string crunchbaseUrl?: string linkedInUrl?: string fiscalYearInfo?: object insights?: object } included?: object meta: { requestId: string apiVersion: string timestamp: string } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **404** Company not found for the provided input --- ## GET /v1/companies/{companyId}/news-articles 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`. | Param | Type | Required | Description | |-------|------|----------|-------------| | `companyId` | string | yes | | | `view` | `default`, `export` | no | | | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `onlyWithFields` | string | no | Comma-separated news article fields to select (e.g. id,headline,url,datePublished,articleBody). Raw text is opt-in. | **200** Public company news article list payload ``` { data: [{ id: string companyId?: string headline?: string url: string datePublished: string description?: string excerpt?: string publisher?: string publisherUrl?: string featuredImageUrl?: string articleBody?: string }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **404** Company not found --- ## GET /v1/companies/{companyId}/job-openings 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`. | Param | Type | Required | Description | |-------|------|----------|-------------| | `companyId` | string | yes | | | `view` | `default`, `export` | no | | | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `onlyWithFields` | string | no | Comma-separated job opening fields to select (e.g. id,title,url,postedOn,jobDescription). Full description text is opt-in. | **200** Public company job opening list payload ``` { data: [{ id: string companyId?: string status?: string url: string title?: string companyName?: string location?: string postedOn: string applicants?: string seniorityLevel?: string employmentType?: string jobFunction?: string industries?: string jobDescription?: string }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **404** Company not found --- ## GET /v1/companies/{companyId}/earnings-calls 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`. | Param | Type | Required | Description | |-------|------|----------|-------------| | `companyId` | string | yes | | | `view` | `default`, `export` | no | | | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `onlyWithFields` | string | no | Comma-separated earnings-call fields to select (e.g. id,year,audioUrl,fullTranscript,generatedAnalysis). Raw transcript text and generated analysis are opt-in. | **200** Public company earnings call list payload ``` { data: [{ id: number companyId?: string stockSymbol?: string year?: number quarter?: number happenedAt?: string audioUrl?: string reportUrl?: string presentationUrl?: string fullTranscript?: string transcriptCompleteness?: string generatedAnalysis?: object }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **404** Company not found --- ## GET /v1/companies/{companyId}/filings 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`. | Param | Type | Required | Description | |-------|------|----------|-------------| | `companyId` | string | yes | | | `view` | `default`, `export` | no | | | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `onlyWithFields` | string | no | Comma-separated filing fields to select (e.g. id,type,accessionNumber,url,filingDate,fullContent). Full filing text is opt-in. | **200** Public company filing list payload ``` { data: [{ id: number companyId?: string type?: string accessionNumber?: string url?: string filingDate?: string reportDate?: string fiscalYear?: number quarter?: number fullContent?: string }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **404** Company not found --- ## GET /v1/contacts 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. | Param | Type | Required | Description | |-------|------|----------|-------------| | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `sortOrder` | `asc`, `desc` | no | Sort direction (default: desc) | | `sortBy` | `id`, `firstName`, `lastName`, `currentTitle`, `currentCompanyName`, `changeType`, `inCurrentRoleSince`, `lastChangeDetectedOn`, `mainScore`, `type`, `email`, `emailStatus`, `location`, `accountId` | no | Contact field to sort by (default: inCurrentRoleSince) | | `onlyWithFields` | string | no | Comma-separated contact fields to select (e.g. id,firstName,lastName,currentTitle) | | `include` | string | no | Supported: account | | `isInCurrentRoleBeforeDate` | string | no | ISO date — contacts in current role before this date | | `isInCurrentRoleAfterDate` | string | no | ISO date — contacts in current role after this date | | `lastChangeDetectedBefore` | string | no | ISO date — only contacts with changes before this date | | `lastChangeDetectedAfter` | string | no | ISO date — only contacts with changes after this date | | `currentTitleTextQuery` | string | no | Title-specific search | | `textQuery` | string | no | Full-text search on name, title, company, location | | `type` | `champion` | no | Filter by contact type | | `changeType` | string | no | Filter by change type (e.g. promotion, newJoiner, departure, internalChange, newInRole) | | `accountId` | string | no | Filter by account ID (comma-separated for multiple) | **200** Contact list payload ``` { data: [{ account?: { id, name?, domain? } id: string organizationId: string accountId?: number firstName?: string lastName?: string currentTitle?: string currentCompanyName?: string changeType?: string inCurrentRoleSince?: string lastChangeDetectedOn?: string mainScore?: number linkedInUrl?: string email?: string emailStatus?: string phone?: string location?: string previousTitle?: string previousCompanyName?: string profilePictureUrl?: string type?: string contactRole?: string personInsights?: object talkingPoints?: object positionWhenFormerUser?: object introPaths?: string[] matchingTargetKeywords?: string[] matchingTargetJobTitles?: string[] matchingTargetLocations?: string[] matchingTargetTechnologies?: string[] }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` --- ## GET /v1/contacts/{contactId} Full Access workspace read. Returns one tracked contact. Public API-only organizations always receive `404` on this route. | Param | Type | Required | Description | |-------|------|----------|-------------| | `contactId` | string | yes | | | `onlyWithFields` | string | no | Comma-separated contact fields to select | | `include` | string | no | Supported: account | **200** Contact payload ``` { data: { account?: { id, name?, domain? } id: string organizationId: string accountId?: number firstName?: string lastName?: string currentTitle?: string currentCompanyName?: string changeType?: string inCurrentRoleSince?: string lastChangeDetectedOn?: string mainScore?: number linkedInUrl?: string email?: string emailStatus?: string phone?: string location?: string previousTitle?: string previousCompanyName?: string profilePictureUrl?: string type?: string contactRole?: string personInsights?: object talkingPoints?: object positionWhenFormerUser?: object introPaths?: string[] matchingTargetKeywords?: string[] matchingTargetJobTitles?: string[] matchingTargetLocations?: string[] matchingTargetTechnologies?: string[] } meta: { requestId: string apiVersion: string timestamp: string } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **404** Contact not found. Public API-only organizations always receive 404. --- ## GET /v1/signals 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. | Param | Type | Required | Description | |-------|------|----------|-------------| | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `sortOrder` | `asc`, `desc` | no | Sort direction (default: desc) | | `sortBy` | `id`, `date`, `type`, `subtype`, `headline`, `createdAt`, `updatedAt`, `accountId` | no | Signal field to sort by (default: date) | | `onlyWithFields` | string | no | Comma-separated signal fields to select (e.g. id,type,headline,date). clinicalTrialId links a clinical-trial signal to /v1/clinical-trials/{trialId}; configuredSignalId names the signal configuration that produced it. | | `textQuery` | string | no | Full-text search on signal content | | `beforeDate` | string | no | ISO date — only signals before this date | | `afterDate` | string | no | ISO date — only signals after this date | | `subtype` | string | no | Filter by signal subtype (comma-separated). Life Sciences clinical-trial signals use trial-started, phase-transition, trial-readout and site-activation. Cannot be combined with textQuery. | | `type` | string | no | Filter by signal type (comma-separated, e.g. relevant-news,hiring-alert,press-release,m-and-a-alert,funding-alert,earnings-call) | | `accountId` | string | no | Filter by account ID (comma-separated for multiple) | **200** Signal list payload ``` { data: [{ id: number organizationId: string accountId: number type: string subtype?: string headline: string description?: string date: string sources?: string[] matchingKeywords?: string[] relevance?: object fullContent?: string smartSummary?: object playUrls?: object slidesUrls?: string[] documentsUrls?: string[] clinicalTrialPrimaryCompletionDate?: string clinicalTrialStudyCompletionDate?: string clinicalTrialLastKnownStatus?: string clinicalTrialCollaborators?: string[] clinicalTrialId?: number configuredSignalId?: number createdAt: string updatedAt: string }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` --- ## GET /v1/signals/counts 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. | Param | Type | Required | Description | |-------|------|----------|-------------| | `textQuery` | string | no | Full-text search filter | | `beforeDate` | string | no | ISO date — only count signals before this date | | `afterDate` | string | no | ISO date — only count signals after this date | | `accountId` | string | no | Filter by account ID (comma-separated for multiple) | **200** Signal counts by type ``` { data: object meta: { requestId: string apiVersion: string timestamp: string } usage: { limit: number used: number remaining: number resetsAt: string } } ``` --- ## GET /v1/signals/{signalId} Full Access workspace read. Returns one tracked signal. Public API-only organizations always receive `404` on this route. | Param | Type | Required | Description | |-------|------|----------|-------------| | `signalId` | number | yes | | | `onlyWithFields` | string | no | Comma-separated signal fields to select | **200** Signal payload ``` { data: { id: number organizationId: string accountId: number type: string subtype?: string headline: string description?: string date: string sources?: string[] matchingKeywords?: string[] relevance?: object fullContent?: string smartSummary?: object playUrls?: object slidesUrls?: string[] documentsUrls?: string[] clinicalTrialPrimaryCompletionDate?: string clinicalTrialStudyCompletionDate?: string clinicalTrialLastKnownStatus?: string clinicalTrialCollaborators?: string[] clinicalTrialId?: number configuredSignalId?: number createdAt: string updatedAt: string } meta: { requestId: string apiVersion: string timestamp: string } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **404** Signal not found. Public API-only organizations always receive 404. --- ## POST /v1/feedback Submit feedback on API usage **Request body** ``` { rating?: integer category?: string message: string context?: object } ``` **200** Feedback received ``` { data: object meta: { requestId: string apiVersion: string timestamp: string } } ``` --- ## GET /v1/usage Get customer-facing API usage and quota | Param | Type | Required | Description | |-------|------|----------|-------------| | `window` | `daily`, `monthly`, `custom` | no | | | `organizationId` | string | no | | | `groupBy` | `endpoint`, `apiKey`, `client`, `day` | no | 'client' splits first-party integrations (e.g. 'mcp' for the Salesmotion MCP server) from direct API calls ('direct') | | `to` | string | no | | | `from` | string | no | | **200** Usage totals and quota ``` { data: { window: string from: string to: string quota: { limit, used, remaining, resetsAt } totals: { requests, successful, failed, pending } breakdown?: [{ requests, successful, failed, pending, key }] } meta: { requestId: string apiVersion: string timestamp: string } } ``` --- ## GET /v1/usage/requests Get recent customer-facing API request history | Param | Type | Required | Description | |-------|------|----------|-------------| | `window` | `daily`, `monthly`, `custom` | no | | | `organizationId` | string | no | | | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `to` | string | no | | | `from` | string | no | | **200** Paginated request history for the current organization ``` { data: [{ status: string id: number occurredAt: string endpoint: string successful: boolean error?: string apiKeyId?: string client?: string input?: object }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } } ``` --- ## GET /v1/usage/limits Get usage limits configured for the current organization | Param | Type | Required | Description | |-------|------|----------|-------------| | `organizationId` | string | no | | **200** Contracted usage limits ``` { data: { daily: { limit, used, remaining, resetsAt } monthly: { limit, used, remaining, resetsAt } } meta: { requestId: string apiVersion: string timestamp: string } } ``` --- ## GET /v1/trial-radar The Trial Radar view: clinical trials that the companies behind your tracked accounts sponsor or collaborate on, each with its account. `meta.facets` counts trials per phase, status, therapeutic area and modality; each facet ignores its own filter. Public API-only organizations receive an empty page. | Param | Type | Required | Description | |-------|------|----------|-------------| | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `sortOrder` | `asc`, `desc` | no | | | `sortBy` | `phase`, `enrollment`, `startDate`, `completionDate`, `lastUpdate` | no | Defaults to the lens date (soonest first), or to highest phase then enrollment without a lens | | `textQuery` | string | no | Matches trial titles, registry IDs and account names | | `modalities` | string | no | Comma-separated: smallMolecules, largeMoleculesBiologics, cellTherapies, geneTherapies, rnaTherapies, vaccines, radiopharmaceuticals | | `therapeuticAreas` | string | no | Comma-separated: cardiovascular, dermatology, endocrinology, gastroenterology, hematology, immunology, infectiousDiseases, nephrology, neurology, oncology, ophthalmology, psychiatry, rareDiseases, respiratory, rheumatology, womensHealth | | `statuses` | string | no | Comma-separated: activeNotRecruiting, completed, enrollingByInvitation, notYetRecruiting, recruiting, suspended, terminated, withdrawn, available, noLongerAvailable, temporarilyNotAvailable, approvedForMarketing, withheld, unknown | | `phases` | string | no | Comma-separated: notAvailable, earlyPhase1, phase1, phase2, phase3, phase4 | | `accountId` | number | no | Only the trials of this account | | `lens` | `startingSoon`, `completingSoon` | no | startingSoon: trials starting in the next 180 days. completingSoon: primary completion in the next 180 days. | **200** Trial Radar rows with facet counts ``` { data: [{ trial: { id, registry, nctId?, euCtNumber?, briefTitle, phases?, lastKnownStatus, estimatedEnrollment?, actualEnrollment?, actualStartDate?, estimatedStartDate?, actualPrimaryCompletionDate?, estimatedPrimaryCompletionDate?, lastUpdatePostDate, therapeuticAreas?, modalities?, url? } account: { id, name?, domain?, logoUrl? } companyId: string }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number facets: { phases, statuses, therapeuticAreas, modalities } } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **403** API access is disabled, or the organization does not have the Life Sciences pack --- ## GET /v1/accounts/{accountId}/clinical-trials Clinical trials linked to the account's company, the same list as `/v1/companies/{companyId}/clinical-trials`. Each row carries `companyRoles`, the roles the company holds on the trial. Public API-only organizations always receive `404` on this route. | Param | Type | Required | Description | |-------|------|----------|-------------| | `accountId` | number | yes | | | `onlyWithFields` | string | no | Comma-separated trial fields. Defaults to registry identifiers, title, phases, status, sponsors, dates, enrollment, conditions, indications, therapeutic areas and modalities. Long texts (briefSummary, detailedDescription, officialTitle), eligibility, designInfo, pointOfContact and locations are opt-in. | | `roles` | string | no | Comma-separated company roles on the trial: leadSponsor, collaborator, responsibleParty, facility. Defaults to leadSponsor,collaborator. | | `statuses` | string | no | Comma-separated trial statuses: activeNotRecruiting, completed, enrollingByInvitation, notYetRecruiting, recruiting, suspended, terminated, withdrawn, available, noLongerAvailable, temporarilyNotAvailable, approvedForMarketing, withheld, unknown | | `lastUpdatePostDateAfter` | string | no | ISO date. Only trials the registry updated on or after this date, for incremental sync. | | `sortBy` | `lastUpdatePostDate`, `id` | no | | | `sortOrder` | `asc`, `desc` | no | | | `page` | integer | no | | | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | **200** Clinical trial list payload ``` { data: [{ id: number registry: string nctId?: string euCtNumber?: string url?: string briefTitle: string officialTitle?: string briefSummary?: string detailedDescription?: string studyType?: string phases?: string[] lastKnownStatus: string whyStopped?: string leadSponsor?: string collaborators?: string[] firstPostedDate?: { date, precision, type } registryStartDate?: { date, precision, type } actualStartDate?: string estimatedStartDate?: string actualPrimaryCompletionDate?: string estimatedPrimaryCompletionDate?: string actualStudyCompletionDate?: string estimatedStudyCompletionDate?: string resultsFirstPostedDate?: string lastUpdatePostDate: string estimatedEnrollment?: number actualEnrollment?: number conditions?: string[] indications?: string[] keywords?: string[] interventions?: [{ name, type? }] therapeuticAreas?: string[] modalities?: string[] designInfo?: object eligibility?: object pointOfContact?: { title?, organization?, email?, phone?, phoneExt? } locations?: [{ facility, status, city, state?, zip?, country, contacts }] siteRegions?: string[] createdAt?: string updatedAt?: string companyRoles: string[] }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **403** API access is disabled, or the organization does not have the Life Sciences pack **404** Account not found. Public API-only organizations always receive 404. --- ## GET /v1/companies/{companyId}/clinical-trials Clinical trials linked to any company in the catalog, resolved with `/v1/companies/by-input/{companyInputId}`. Trials come from ClinicalTrials.gov and the EU Clinical Trials Register; `registry` names the source and `nctId` or `euCtNumber` its ID. Each row carries `companyRoles`, the roles the company holds on the trial. Sorted by the registry update date, newest first. | Param | Type | Required | Description | |-------|------|----------|-------------| | `companyId` | string | yes | | | `onlyWithFields` | string | no | Comma-separated trial fields. Defaults to registry identifiers, title, phases, status, sponsors, dates, enrollment, conditions, indications, therapeutic areas and modalities. Long texts (briefSummary, detailedDescription, officialTitle), eligibility, designInfo, pointOfContact and locations are opt-in. | | `roles` | string | no | Comma-separated company roles on the trial: leadSponsor, collaborator, responsibleParty, facility. Defaults to leadSponsor,collaborator. | | `statuses` | string | no | Comma-separated trial statuses: activeNotRecruiting, completed, enrollingByInvitation, notYetRecruiting, recruiting, suspended, terminated, withdrawn, available, noLongerAvailable, temporarilyNotAvailable, approvedForMarketing, withheld, unknown | | `lastUpdatePostDateAfter` | string | no | ISO date. Only trials the registry updated on or after this date, for incremental sync. | | `sortBy` | `lastUpdatePostDate`, `id` | no | | | `sortOrder` | `asc`, `desc` | no | | | `page` | integer | no | | | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | **200** Clinical trial list payload ``` { data: [{ id: number registry: string nctId?: string euCtNumber?: string url?: string briefTitle: string officialTitle?: string briefSummary?: string detailedDescription?: string studyType?: string phases?: string[] lastKnownStatus: string whyStopped?: string leadSponsor?: string collaborators?: string[] firstPostedDate?: { date, precision, type } registryStartDate?: { date, precision, type } actualStartDate?: string estimatedStartDate?: string actualPrimaryCompletionDate?: string estimatedPrimaryCompletionDate?: string actualStudyCompletionDate?: string estimatedStudyCompletionDate?: string resultsFirstPostedDate?: string lastUpdatePostDate: string estimatedEnrollment?: number actualEnrollment?: number conditions?: string[] indications?: string[] keywords?: string[] interventions?: [{ name, type? }] therapeuticAreas?: string[] modalities?: string[] designInfo?: object eligibility?: object pointOfContact?: { title?, organization?, email?, phone?, phoneExt? } locations?: [{ facility, status, city, state?, zip?, country, contacts }] siteRegions?: string[] createdAt?: string updatedAt?: string companyRoles: string[] }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **403** API access is disabled, or the organization does not have the Life Sciences pack **404** Company not found --- ## GET /v1/clinical-trials/{trialId} One clinical trial with every field, including its point of contact, sites with their contacts, and `companies`: each linked company with the roles it holds (leadSponsor, collaborator, responsibleParty, facility). | Param | Type | Required | Description | |-------|------|----------|-------------| | `trialId` | number | yes | | | `onlyWithFields` | string | no | Comma-separated trial fields | **200** Clinical trial payload ``` { data: { id: number registry: string nctId?: string euCtNumber?: string url?: string briefTitle: string officialTitle?: string briefSummary?: string detailedDescription?: string studyType?: string phases?: string[] lastKnownStatus: string whyStopped?: string leadSponsor?: string collaborators?: string[] firstPostedDate?: { date, precision, type } registryStartDate?: { date, precision, type } actualStartDate?: string estimatedStartDate?: string actualPrimaryCompletionDate?: string estimatedPrimaryCompletionDate?: string actualStudyCompletionDate?: string estimatedStudyCompletionDate?: string resultsFirstPostedDate?: string lastUpdatePostDate: string estimatedEnrollment?: number actualEnrollment?: number conditions?: string[] indications?: string[] keywords?: string[] interventions?: [{ name, type? }] therapeuticAreas?: string[] modalities?: string[] designInfo?: object eligibility?: object pointOfContact?: { title?, organization?, email?, phone?, phoneExt? } locations?: [{ facility, status, city, state?, zip?, country, contacts }] siteRegions?: string[] createdAt?: string updatedAt?: string companies: [{ companyId, name?, roles }] } meta: { requestId: string apiVersion: string timestamp: string } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **403** API access is disabled, or the organization does not have the Life Sciences pack **404** Clinical trial not found --- ## GET /v1/clinical-trials/by-registry-id/{registryId} Looks a trial up by its NCT ID (ClinicalTrials.gov, e.g. NCT01234567) or its EU CT number (EU Clinical Trials Register, e.g. 2023-501234-12-00). Returns the same payload as `/v1/clinical-trials/{trialId}`. | Param | Type | Required | Description | |-------|------|----------|-------------| | `registryId` | string | yes | | | `onlyWithFields` | string | no | Comma-separated trial fields | **200** Clinical trial payload ``` { data: { id: number registry: string nctId?: string euCtNumber?: string url?: string briefTitle: string officialTitle?: string briefSummary?: string detailedDescription?: string studyType?: string phases?: string[] lastKnownStatus: string whyStopped?: string leadSponsor?: string collaborators?: string[] firstPostedDate?: { date, precision, type } registryStartDate?: { date, precision, type } actualStartDate?: string estimatedStartDate?: string actualPrimaryCompletionDate?: string estimatedPrimaryCompletionDate?: string actualStudyCompletionDate?: string estimatedStudyCompletionDate?: string resultsFirstPostedDate?: string lastUpdatePostDate: string estimatedEnrollment?: number actualEnrollment?: number conditions?: string[] indications?: string[] keywords?: string[] interventions?: [{ name, type? }] therapeuticAreas?: string[] modalities?: string[] designInfo?: object eligibility?: object pointOfContact?: { title?, organization?, email?, phone?, phoneExt? } locations?: [{ facility, status, city, state?, zip?, country, contacts }] siteRegions?: string[] createdAt?: string updatedAt?: string companies: [{ companyId, name?, roles }] } meta: { requestId: string apiVersion: string timestamp: string } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **403** API access is disabled, or the organization does not have the Life Sciences pack **404** Clinical trial not found --- ## GET /v1/companies/{companyId}/tags The company's current tags (therapeutic area, therapeutic modality, lifecycle moment, topic, organization type) in the tag categories your organization has enabled. Each tag carries the period the evidence covers and how many evidence items support it. | Param | Type | Required | Description | |-------|------|----------|-------------| | `companyId` | string | yes | | | `perPage` | number | no | Results per page (default 20, maximum 100; larger values are clamped) | | `page` | integer | no | | | `definitionKey` | string | no | Comma-separated: therapeuticArea, therapeuticModality, lifecycleMoment, topic, organizationType | **200** Company tag list payload ``` { data: [{ id: number companyId: string definitionKey: string categoryKey?: string value: string label: string activityStartedOn: string activityLastSupportedOn: string visibleUntil: string evidenceCount: number }] meta: { requestId: string apiVersion: string timestamp: string page: number perPage: number totalCount: number totalPages: number } usage: { limit: number used: number remaining: number resetsAt: string } } ``` **403** API access is disabled, or the organization does not have the Life Sciences pack **404** Company not found ---