API Reference

Last updated 2026-11-18

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
}
Statuserror.codeMeaning
400invalid_parameter, unknown_parameter, invalid_requestA bad value (param names it, allowedValues lists the valid ones) or a parameter the route does not take
401unauthorizedMissing, malformed, invalid, expired or revoked key
403forbidden, account_disabledAPI access is off, the route needs the Life Sciences pack, or a write needs a read-and-write key
404not_foundNo such record in your organization, or no such endpoint
422idempotency_conflictAn Idempotency-Key reused with a different body
429rate_limitedAllowance used up; wait Retry-After seconds
500internal_errorSomething failed on our side; send us the requestId
504timeoutThe 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:

ParameterTypeDefaultDescription
pageinteger1Page number
perPageinteger20Results 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:

  1. Accounts and contacts: sortBy=updatedAt&sortOrder=asc&updatedAfter=<cursor>. updatedAt is when Salesmotion last created or updated the row.
  2. Signals: sortBy=createdAt&sortOrder=asc&createdAfter=<cursor>. createdAt is when Salesmotion recorded the signal; afterDate and beforeDate filter the event date instead.
  3. 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 of page, until meta.nextCursor is null, and store the last one.
  4. 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:

ParameterTypeDescription
accountIdnumberDirect account ID lookup. Takes priority over domain and query
domainstringExact domain match (e.g. acme.com)
querystringSearch on company name or domain
sectionsstringComma-separated: profile, summary, research, swotAnalysis, value. All by default; profile is always included
includestringRelated resources: contacts, signals
contactsLimitnumberMax contacts when included (default 10, max 100)
signalsLimitnumberMax 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:

ParameterTypeDescription
viewstringdefault or export
perPageintegerResults per page
pageintegerPage number
sortBystringAccount field to sort by. Default: newest first (by id, descending); with textQuery, best match first
sortOrderstringasc or desc (default: desc)
onlyWithFieldsstringComma-separated fields to return (e.g. id,name,domain)
includestringRelated resources to include: company, owner
textQuerystringSearch accounts by name or domain
idsstringComma-separated account IDs to fetch
domainstringExact domain match (e.g. acme.com)
companyIdstringFilter by linked company ID
ownerIdstringFilter by account owner user ID
typestringFilter by account type: prospect, customer, partner, churned, open-opportunity, competitor, other
prioritynumberFilter by priority: 1 (high), 2 (medium), 3 (low)
hasSignalsOfTypestringComma-separated signal types — combined with hasSignalsAfterDate to filter accounts by signal activity
hasSignalsAfterDatestringISO date — only accounts with signals after this date
updatedAfterstringISO date or timestamp — accounts created or updated at or after this time (see Keeping a Copy in Sync)
createdAfterstringISO date or timestamp — accounts created at or after this time
afterIdintegerSync 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:

ParameterTypeDescription
accountIdintegerRequired. The account ID

Query parameters:

ParameterTypeDescription
viewstringdefault or export
onlyWithFieldsstringComma-separated fields to return
includestringRelated resources: company, owner, contacts, signals
signalsLimitintegerMax number of signals to include
contactsLimitintegerMax 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:

FieldTypeDescription
accountsarrayRequired. 1 to 25 objects, each with a unique input
accounts[].inputstringRequired. Website domain, website URL, LinkedIn company URL, Crunchbase URL or company name
accounts[].companyNamestringBusiness 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:

ParameterTypeDescription
companyIdstringRequired. The company ID

Query parameters:

ParameterTypeDescription
viewstringdefault or export
onlyWithFieldsstringComma-separated fields to return
includestringlatestEarningsCall, 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:

ParameterTypeDescription
companyInputIdstringRequired. 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:

EndpointOpt-in fields
news-articlesarticleBody
job-openingsjobDescription
earnings-callsfullTranscript, generatedAnalysis
filingsfullContent

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:

ParameterTypeDescription
perPageintegerResults per page
pageintegerPage number
sortBystringContact field to sort by (default: inCurrentRoleSince)
sortOrderstringasc or desc (default: desc)
onlyWithFieldsstringComma-separated fields to return
includestringRelated resources: account
accountIdstringFilter by account ID (comma-separated for multiple)
textQuerystringFull-text search on name, title, company, location. A first and last name ("Jane Doe") matches both
currentTitleTextQuerystringTitle-specific search
typestringFilter by contact type: champion
changeTypestringFilter by career change: promotion, newJoiner, departure, internalChange, newInRole
isInCurrentRoleBeforeDatestringISO date — contacts in their current role before this date
isInCurrentRoleAfterDatestringISO date — contacts in their current role after this date
lastChangeDetectedBeforestringISO date — career change detected before this date
lastChangeDetectedAfterstringISO date — career change detected after this date
updatedAfterstringISO date or timestamp — contacts created or updated at or after this time
createdAfterstringISO date or timestamp — contacts created at or after this time
afterIdintegerSync 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:

ParameterTypeDescription
contactIdintegerRequired. The contact ID

Query parameters:

ParameterTypeDescription
onlyWithFieldsstringComma-separated fields to return
includestringRelated 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:

ParameterTypeDescription
perPageintegerResults per page
pageintegerPage number
sortBystringSignal field to sort by (default: date)
sortOrderstringasc or desc (default: desc)
onlyWithFieldsstringComma-separated fields to return
textQuerystringFull-text search on signal content
accountIdstringFilter by account ID (comma-separated for multiple)
typestringComma-separated signal types, e.g. relevant-news, hiring-alert, press-release, m-and-a-alert, funding-alert, earnings-call
subtypestringComma-separated signal subtypes. Cannot be combined with textQuery
afterDatestringISO date — signals whose event date is on or after this date
beforeDatestringISO date — signals whose event date is on or before this date
createdAfterstringISO date or timestamp — signals Salesmotion recorded at or after this time; the one to use for sync
updatedAfterstringISO date or timestamp — signals created or updated at or after this time
afterIdintegerSync 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:

ParameterTypeDescription
textQuerystringFull-text search filter
accountIdstringFilter by account ID (comma-separated for multiple)
afterDatestringISO date — count signals after this date
beforeDatestringISO 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:

ParameterTypeDescription
signalIdintegerRequired. The signal ID

Query parameters:

ParameterTypeDescription
onlyWithFieldsstringComma-separated fields to return

Usage

Get Usage

GET /v1/usage

Retrieve API usage and quota information for your organization.

Query parameters:

ParameterTypeDescription
windowstringdaily, monthly, or custom
groupBystringendpoint, apiKey, client, or day
fromstringStart date for custom window
tostringEnd 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.

EndpointDescription
GET /v1/trial-radarClinical trials that the companies behind your tracked accounts sponsor or collaborate on, with facet counts
GET /v1/accounts/{accountId}/clinical-trialsClinical trials linked to an account's company
GET /v1/companies/{companyId}/clinical-trialsClinical 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}/tagsCompany 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):

FieldTypeRequiredDescription
messagestringYesYour feedback
ratingnumberNo1–5 satisfaction rating
categorystringNomissing-data, wrong-data, api-usability, feature-request, other
contextobjectNoAdditional 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.

See it in action

Take a 2-minute tour

New to Salesmotion? Walk through the interactive demo — no signup required.

Try the interactive demo →
Still need help?

Talk to the team

Email us with a question, or book 30 minutes with the team to see Salesmotion on your accounts.