Watch a company
curl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/companies/{id}/watch \
--header 'Authorization: Bearer <token>'const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-prod.heliyos.ai/v1/platform/companies/{id}/watch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api-prod.heliyos.ai/v1/platform/companies/{id}/watch"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text){
"meta": {
"message": "Company watched."
},
"data": {
"_id": "66f1a8c3e4b0a1b2c3d4e5f6",
"organizationId": "66a0f1e2d3c4b5a697887766",
"baseSchemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company",
"data": {
"company_name": "Northwind Traders",
"website": "https://northwind.example.com",
"account_status": "unknown",
"engagement_status": "unknown"
},
"isAgentAssigned": true,
"agentAssignmentStatus": "STARTED",
"enrichmentStatus": "FINISHED",
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e600",
"schemaId": "66a0f1e2d3c4b5a697880002",
"objectType": "people"
}
],
"metadata": {
"created": {
"at": "2026-09-12T10:00:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}Watchlist
Watch a company
Adds a company record to the watchlist. Watching an already watched company changes nothing and uses no Watcher.
When the company was not watched yet:
- It uses one Watcher from your plan. With none left, the call answers 403 and nothing changes.
- Its
account_statusandengagement_statusare set tounknownif empty, and the records linked to it (for example its people and deals) are marked watched too. - In the background, the workers enrich it and pull in its emails and meetings (enrichment uses credits), and every active Scout scoped to the watchlist starts on it. Custom Scouts cost credits per run.
Background steps that fail do not fail the call. Check progress in agentAssignmentStatus and with
GET /v1/platform/companies/{id}/scouts.
POST
/
v1
/
platform
/
companies
/
{id}
/
watch
Watch a company
curl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/companies/{id}/watch \
--header 'Authorization: Bearer <token>'const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-prod.heliyos.ai/v1/platform/companies/{id}/watch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api-prod.heliyos.ai/v1/platform/companies/{id}/watch"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text){
"meta": {
"message": "Company watched."
},
"data": {
"_id": "66f1a8c3e4b0a1b2c3d4e5f6",
"organizationId": "66a0f1e2d3c4b5a697887766",
"baseSchemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company",
"data": {
"company_name": "Northwind Traders",
"website": "https://northwind.example.com",
"account_status": "unknown",
"engagement_status": "unknown"
},
"isAgentAssigned": true,
"agentAssignmentStatus": "STARTED",
"enrichmentStatus": "FINISHED",
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e600",
"schemaId": "66a0f1e2d3c4b5a697880002",
"objectType": "people"
}
],
"metadata": {
"created": {
"at": "2026-09-12T10:00:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}In the Heliyos MCP server:
heliyos_companies_watch.Authorizations
A workspace API key, sent as Authorization: Bearer heliyos_.... Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in.
Path Parameters
The company record's id.
Pattern:
^[0-9a-fA-F]{24}$Was this page helpful?

