Base URL and Authentication
All API requests use the base URL:
https://api.salesmotion.io
Authenticate every request with your API key as a Bearer token in the Authorization header:
Authorization: Bearer YOUR_API_KEY
API access is included with the Enterprise plan. Contact your account manager to receive your credentials.
API keys are read only unless you pick Read and write when you create one in Settings > Integrations > API. Read-and-write keys can also add and remove accounts. Organization-owned service keys are always read only.
To check a key, call GET /v1/me. It is not counted against your allowance and returns your organization (with hasApiAccess, hasFullWorkspaceAccess and hasLifeSciencesPack), the key's type and access level (read_only or read_write) and, for personal keys, its user. A missing, malformed, invalid, expired or revoked key gets HTTP 401 with a message that says which.
The API reference lists every endpoint with all its parameters and response shapes, and api.salesmotion.io/llms.txt has the same reference as markdown for AI agents. What changed, and when, is in the API changelog. Version 1 grows by addition: routes, parameters and fields are never removed or renamed, and behaviour changes are announced in the changelog first.
Response Format
Data endpoints return JSON in the same envelope:
{
"data": { },
"meta": { "requestId": "...", "apiVersion": "v1", "timestamp": "..." },
"usage": { "limit": 1000, "used": 42, "remaining": 958, "resetsAt": "..." }
}
List endpoints add page, perPage, totalCount and totalPages to meta. Every response carries an X-Request-Id header equal to meta.requestId; include it when you contact us.
Timestamps (createdAt, updatedAt, addedOn, lastRefreshAt, news datePublished) are UTC and end in Z. Calendar days such as signal date, filingDate and postedOn have no offset, so they read the same in every timezone.
Errors
Every error has the same JSON body:
{
"error": {
"code": "unknown_parameter",
"message": "Unknown parameter \"limit\". Did you mean \"perPage\"?",
"param": "limit",
"requestId": "8a3f6c2e-4b1d-4f7a-9c0e-2d5b7e1a9f30"
},
"message": "Unknown parameter \"limit\". Did you mean \"perPage\"?",
"statusCode": 400
}
| Status | error.code | Meaning |
|---|---|---|
| 400 | invalid_parameter, unknown_parameter, invalid_request | A bad value (param names it, allowedValues lists the valid ones) or a parameter the route does not take |
| 401 | unauthorized | Missing, malformed, invalid, expired or revoked key |
| 403 | forbidden, account_disabled | API access is off, the route needs the Life Sciences pack, or a write needs a read-and-write key |
| 404 | not_found | No such record in your organization, or no such endpoint |
| 422 | idempotency_conflict | An Idempotency-Key reused with a different body |
| 429 | rate_limited | Allowance used up; wait Retry-After seconds |
| 500 | internal_error | Something failed on our side; send us the requestId |
| 504 | timeout | The query ran too long; add a filter such as accountId or a date, or lower perPage |
Pagination
List endpoints return paginated results. Use the page and perPage query parameters to navigate:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
perPage | integer | 20 | Results per page (maximum 100) |
On contacts, signals, account sub-routes and company news, totalCount is exact up to 500 rows and on the last page; above that it is an estimate and meta.totalCountIsEstimate is true. To read everything, request pages until one has fewer than perPage rows.
Keeping a Copy in Sync
To keep accounts, contacts and signals in your own database or CRM, poll for what changed since your last run:
- Accounts and contacts:
sortBy=updatedAt&sortOrder=asc&updatedAfter=<cursor>.updatedAtis when Salesmotion last created or updated the row. - Signals:
sortBy=createdAt&sortOrder=asc&createdAfter=<cursor>.createdAtis when Salesmotion recorded the signal;afterDateandbeforeDatefilter the event date instead. - Follow the cursor. Each page carries
meta.nextCursor, e.g.{ "updatedAfter": "2026-11-18T09:12:44.120Z", "afterId": 204811 }. Pass both values on the next request, instead ofpage, untilmeta.nextCursorisnull, and store the last one. - Overlap a little. Start each run a few minutes before the stored cursor and upsert by
id.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/accounts?sortBy=updatedAt&sortOrder=asc&updatedAfter=2026-11-18T09:00:00Z&perPage=100"
The same parameters work on /v1/accounts/{accountId}/contacts, /v1/accounts/{accountId}/signals and /v1/account-lists/{listId}/accounts. Removed records drop out of the lists.
Rate Limits
Allowances are per organization and use rolling windows: the last 30 days and the last 24 hours. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the oldest counted call ages out), and a 429 carries Retry-After in seconds. GET /v1/usage and GET /v1/me are not counted.
Field Selection
Most endpoints support the onlyWithFields query parameter — a comma-separated list of field names to return. This reduces payload size when you only need specific data:
GET /v1/accounts?onlyWithFields=id,name,domain,mainScore
Account Insights
Get Account Insights
GET /v1/account-insights
Find a tracked account by ID, domain, or name and get its full AI-generated insight in one call. Built for AI agents and copilots. Pass at least one of accountId, domain, or query.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
accountId | number | Direct account ID lookup. Takes priority over domain and query |
domain | string | Exact domain match (e.g. acme.com) |
query | string | Search on company name or domain |
sections | string | Comma-separated: profile, summary, research, swotAnalysis, value. All by default; profile is always included |
include | string | Related resources: contacts, signals |
contactsLimit | number | Max contacts when included (default 10, max 100) |
signalsLimit | number | Max signals when included (default 20, max 100) |
Example request:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/account-insights?domain=acme.com&include=signals"
Response: A status field: found (the insight is in data), multiple_matches (see candidates and bestMatch, then call again with accountId or domain), or not_found. data.profile.companyId links to the company endpoints, and every included contact and signal carries its id.
Accounts
List Accounts
GET /v1/accounts
Retrieve a paginated list of accounts with filtering and sorting.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
view | string | default or export |
perPage | integer | Results per page |
page | integer | Page number |
sortBy | string | Account field to sort by. Default: newest first (by id, descending); with textQuery, best match first |
sortOrder | string | asc or desc (default: desc) |
onlyWithFields | string | Comma-separated fields to return (e.g. id,name,domain) |
include | string | Related resources to include: company, owner |
textQuery | string | Search accounts by name or domain |
ids | string | Comma-separated account IDs to fetch |
domain | string | Exact domain match (e.g. acme.com) |
companyId | string | Filter by linked company ID |
ownerId | string | Filter by account owner user ID |
type | string | Filter by account type: prospect, customer, partner, churned, open-opportunity, competitor, other |
priority | number | Filter by priority: 1 (high), 2 (medium), 3 (low) |
hasSignalsOfType | string | Comma-separated signal types — combined with hasSignalsAfterDate to filter accounts by signal activity |
hasSignalsAfterDate | string | ISO date — only accounts with signals after this date |
updatedAfter | string | ISO date or timestamp — accounts created or updated at or after this time (see Keeping a Copy in Sync) |
createdAfter | string | ISO date or timestamp — accounts created at or after this time |
afterId | integer | Sync cursor, from meta.nextCursor |
Example request:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/accounts?perPage=10&type=prospect&sortBy=mainScore&sortOrder=desc"
Response: Paginated array of Account objects.
Get Account
GET /v1/accounts/{accountId}
Retrieve a single account by ID, with optional related resources.
Path parameters:
| Parameter | Type | Description |
|---|---|---|
accountId | integer | Required. The account ID |
Query parameters:
| Parameter | Type | Description |
|---|---|---|
view | string | default or export |
onlyWithFields | string | Comma-separated fields to return |
include | string | Related resources: company, owner, contacts, signals |
signalsLimit | integer | Max number of signals to include |
contactsLimit | integer | Max number of contacts to include |
Example request:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/accounts/12345?include=company"
Add Accounts
POST /v1/accounts
Add up to 25 companies as accounts in your workspace and queue them for research. Needs a key with Read and write access. Accounts are always added to the organization of the key, and your plan's account limit applies.
Request body:
| Field | Type | Description |
|---|---|---|
accounts | array | Required. 1 to 25 objects, each with a unique input |
accounts[].input | string | Required. Website domain, website URL, LinkedIn company URL, Crunchbase URL or company name |
accounts[].companyName | string | Business name, needed when the website is a page on a shared site |
Each input gets one result, in request order. status is added (new account, research usually ready within minutes), existing (already an account, nothing is re-run; a removed account is restored), needs_review (several companies match, see candidates) or failed (see code: invalid_input, account_limit_reached, could_not_add).
Example request:
curl -X POST "https://api.salesmotion.io/v1/accounts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"accounts": [{"input": "acme.com"}, {"input": "https://www.linkedin.com/company/globex"}]}'
To make retries safe, send an Idempotency-Key header (for example a UUID). A retry with the same key and body within 24 hours returns the original response with Idempotent-Replayed: true instead of adding again; the same key with a different body returns 422 (idempotency_conflict). A response in which any input failed is not stored, so a retry runs again. Read-only and service keys get 403 before the body is checked.
Remove Account
DELETE /v1/accounts/{accountId}
Remove an account from your workspace, the same as Remove in the app. Adding the company again restores it. Needs a key with Read and write access. Returns removed, or already_removed if it was removed before. An ID that is not an account in your organization returns 404.
Example request:
curl -X DELETE "https://api.salesmotion.io/v1/accounts/12345" \
-H "Authorization: Bearer YOUR_API_KEY"
Account Lists
GET /v1/account-lists
GET /v1/account-lists/{listId}/accounts
The account lists you can see, and the accounts in one of them. A personal key sees the lists shared with the organization plus its user's own and assigned lists; a service key sees shared lists only. The accounts route takes the same onlyWithFields, include, sorting, paging and sync parameters as List accounts. A list you cannot see returns 404. Lists are read-only through the API.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/account-lists/42/accounts?onlyWithFields=id,name,domain&perPage=100"
Companies
Resolve Companies
GET /v1/companies/resolve?input=
POST /v1/companies/resolve
Turn a domain, website URL, LinkedIn or Crunchbase company URL, stock symbol, company ID or company name into a Salesmotion company. Names are matched against your workspace accounts first, then against known companies. Each result has status found, not_found or multiple_matches (with up to 10 candidates), the company, and accountId when it is one of your accounts. POST takes {"inputs": [...]} with 1 to 25 inputs and returns one result per input, in order. Each request counts as one call. Nothing is added to your workspace.
curl -X POST "https://api.salesmotion.io/v1/companies/resolve" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs": ["acme.com", "https://www.linkedin.com/company/globex", "Initech"]}'
Get Company
GET /v1/companies/{companyId}
Retrieve a company by its canonical Salesmotion ID. Get the ID from Get company by external identifier below. AI-generated insights are returned only when you ask for them in onlyWithFields.
Path parameters:
| Parameter | Type | Description |
|---|---|---|
companyId | string | Required. The company ID |
Query parameters:
| Parameter | Type | Description |
|---|---|---|
view | string | default or export |
onlyWithFields | string | Comma-separated fields to return |
include | string | latestEarningsCall, latestEarningsCallAnalysis |
Example request:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/companies/cOWCt7iJhT9r5D1VWBox?include=latestEarningsCall,latestEarningsCallAnalysis"
Get Company by External Identifier
GET /v1/companies/by-input/{companyInputId}
Look up a company using a domain, website URL, stock symbol, LinkedIn URL, Crunchbase URL, or company ID. Use the returned data.id on the other company endpoints.
Path parameters:
| Parameter | Type | Description |
|---|---|---|
companyInputId | string | Required. Domain, website URL, stock symbol, LinkedIn URL, Crunchbase URL, or company ID |
Query parameters: Same as Get company above.
Example request:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/companies/by-input/salesforce.com"
Company News, Job Openings, Earnings Calls, and Filings
GET /v1/companies/{companyId}/news-articles
GET /v1/companies/{companyId}/job-openings
GET /v1/companies/{companyId}/earnings-calls
GET /v1/companies/{companyId}/filings
Paginated lists for any company. Default responses return metadata and public links. Ask for the heavy text fields in onlyWithFields:
| Endpoint | Opt-in fields |
|---|---|
news-articles | articleBody |
job-openings | jobDescription |
earnings-calls | fullTranscript, generatedAnalysis |
filings | fullContent |
Query parameters: page, perPage, view, onlyWithFields. News also takes afterDate and beforeDate (publication date, inclusive) and textQuery (text in the headline or description).
Example request:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/companies/cOWCt7iJhT9r5D1VWBox/earnings-calls?perPage=1&onlyWithFields=year,quarter,happenedAt,generatedAnalysis"
Contacts
List Contacts
GET /v1/contacts
Retrieve a paginated list of contacts with filtering. For one account, GET /v1/accounts/{accountId}/contacts takes the same parameters.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
perPage | integer | Results per page |
page | integer | Page number |
sortBy | string | Contact field to sort by (default: inCurrentRoleSince) |
sortOrder | string | asc or desc (default: desc) |
onlyWithFields | string | Comma-separated fields to return |
include | string | Related resources: account |
accountId | string | Filter by account ID (comma-separated for multiple) |
textQuery | string | Full-text search on name, title, company, location. A first and last name ("Jane Doe") matches both |
currentTitleTextQuery | string | Title-specific search |
type | string | Filter by contact type: champion |
changeType | string | Filter by career change: promotion, newJoiner, departure, internalChange, newInRole |
isInCurrentRoleBeforeDate | string | ISO date — contacts in their current role before this date |
isInCurrentRoleAfterDate | string | ISO date — contacts in their current role after this date |
lastChangeDetectedBefore | string | ISO date — career change detected before this date |
lastChangeDetectedAfter | string | ISO date — career change detected after this date |
updatedAfter | string | ISO date or timestamp — contacts created or updated at or after this time |
createdAfter | string | ISO date or timestamp — contacts created at or after this time |
afterId | integer | Sync cursor, from meta.nextCursor |
Example request:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/contacts?accountId=12345&changeType=newJoiner"
Get Contact
GET /v1/contacts/{contactId}
Retrieve a single contact by ID.
Path parameters:
| Parameter | Type | Description |
|---|---|---|
contactId | integer | Required. The contact ID |
Query parameters:
| Parameter | Type | Description |
|---|---|---|
onlyWithFields | string | Comma-separated fields to return |
include | string | Related resources: account |
Signals
List Signals
GET /v1/signals
Retrieve a paginated list of signals with filtering. For one account, GET /v1/accounts/{accountId}/signals takes the same parameters.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
perPage | integer | Results per page |
page | integer | Page number |
sortBy | string | Signal field to sort by (default: date) |
sortOrder | string | asc or desc (default: desc) |
onlyWithFields | string | Comma-separated fields to return |
textQuery | string | Full-text search on signal content |
accountId | string | Filter by account ID (comma-separated for multiple) |
type | string | Comma-separated signal types, e.g. relevant-news, hiring-alert, press-release, m-and-a-alert, funding-alert, earnings-call |
subtype | string | Comma-separated signal subtypes. Cannot be combined with textQuery |
afterDate | string | ISO date — signals whose event date is on or after this date |
beforeDate | string | ISO date — signals whose event date is on or before this date |
createdAfter | string | ISO date or timestamp — signals Salesmotion recorded at or after this time; the one to use for sync |
updatedAfter | string | ISO date or timestamp — signals created or updated at or after this time |
afterId | integer | Sync cursor, from meta.nextCursor |
Example request:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.salesmotion.io/v1/signals?accountId=12345&type=earnings-call,funding-alert&afterDate=2026-01-01"
Get Signal Counts
GET /v1/signals/counts
Retrieve aggregated signal counts by type. Useful for dashboards and prioritization.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
textQuery | string | Full-text search filter |
accountId | string | Filter by account ID (comma-separated for multiple) |
afterDate | string | ISO date — count signals after this date |
beforeDate | string | ISO date — count signals before this date |
Response fields: all (every type), accounts (distinct accounts with signals), plus counts per signal type. Each type is counted exactly up to 500; a type with more reports 500 and is listed in meta.cappedCounts.
Get Signal
GET /v1/signals/{signalId}
Retrieve a single signal by ID, including full content and sources.
Path parameters:
| Parameter | Type | Description |
|---|---|---|
signalId | integer | Required. The signal ID |
Query parameters:
| Parameter | Type | Description |
|---|---|---|
onlyWithFields | string | Comma-separated fields to return |
Usage
Get Usage
GET /v1/usage
Retrieve API usage and quota information for your organization.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
window | string | daily, monthly, or custom |
groupBy | string | endpoint, apiKey, client, or day |
from | string | Start date for custom window |
to | string | End date for custom window |
Response: Quota snapshot, totals (requests, successful, failed, pending), and a breakdown when groupBy is set. Windows are rolling: monthly is the last 30 days (windowType: "rolling", windowDays: 30), and quota.resetsAt is when the oldest counted call ages out. Not counted against your allowance.
Get Usage Limits
GET /v1/usage/limits
Retrieve your contracted daily and monthly API limits.
Get Request History
GET /v1/usage/requests
Retrieve a paginated list of your recent API requests, with the endpoint, time, whether each call succeeded, and its requestId (the X-Request-Id of that call).
Query parameters: window, from, to, page, perPage.
Life Sciences
Available to organizations with the Life Sciences pack.
| Endpoint | Description |
|---|---|
GET /v1/trial-radar | Clinical trials that the companies behind your tracked accounts sponsor or collaborate on, with facet counts |
GET /v1/accounts/{accountId}/clinical-trials | Clinical trials linked to an account's company |
GET /v1/companies/{companyId}/clinical-trials | Clinical trials linked to any company |
GET /v1/clinical-trials/{trialId} | One trial with every field, its contacts, sites, and linked companies |
GET /v1/clinical-trials/by-registry-id/{registryId} | Look up a trial by NCT ID or EU CT number |
GET /v1/companies/{companyId}/tags | Company tags: therapeutic area, modality, lifecycle moment, topic, organization type |
Trials come from ClinicalTrials.gov and the EU Clinical Trials Register. See the API reference for the filters and fields.
Feedback
Submit Feedback
POST /v1/feedback
Submit feedback on API data quality or feature requests.
Request body (JSON):
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Your feedback |
rating | number | No | 1–5 satisfaction rating |
category | string | No | missing-data, wrong-data, api-usability, feature-request, other |
context | object | No | Additional context: endpoint, accountId, etc. |
Example request:
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Missing earnings data for MSFT Q3", "category": "missing-data", "context": {"accountId": "12345"}}' \
"https://api.salesmotion.io/v1/feedback"
Data Schemas
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 · pointOfView · linkedInUrl · crunchbaseUrl · zoomInfoUrl · salesforceUrl · hubspotUrl · salesNavigatorUrl · addedOn · lastRefreshAt · countryCode · employeeCountDetails
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 · createdAt · updatedAt
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 · employeeCountDisplay · employeeCountAlternatives · mainStockSymbol · crunchbaseUrl · linkedInUrl · fiscalYearInfo · insights (opt-in)
Frequently Asked Questions
What Authentication Method Does the API Use?
The API uses API keys sent as Bearer tokens. Include your key in the Authorization header of every request. Your account manager will provide your key when you activate API access.
What Are the Rate Limits?
Your organization has daily and monthly call allowances, counted over rolling 24-hour and 30-day windows. Successful calls count; failed calls do not. When an allowance runs out, calls return HTTP 429 with a Retry-After header. Every response carries RateLimit-Remaining, and the /v1/usage and /v1/usage/limits endpoints show your consumption. Contact your account manager if you need higher throughput.
Can I Look Up a Company by Domain Instead of ID?
Yes. Use GET /v1/companies/resolve?input= with the company's domain (e.g. salesforce.com), website URL, stock symbol, LinkedIn URL, Crunchbase URL or name, or POST /v1/companies/resolve for up to 25 at once. GET /v1/companies/by-input/{companyInputId} works too for identifiers.
How Do I Get Signals for a Specific Account?
Use GET /v1/accounts/{accountId}/signals, or GET /v1/signals with the accountId query parameter (comma-separated for several accounts). You can also filter by signal type and date range.
How Do I Keep My Database Up to Date?
Poll with updatedAfter on accounts and contacts and createdAfter on signals, sorted ascending, and follow meta.nextCursor. See Keeping a Copy in Sync above.
Is There a Sandbox or Test Environment?
Contact your account manager to discuss testing options. We recommend starting with read-only requests against a small set of accounts to validate your integration before scaling.