API Reference

Accounts

The companies in your workspace. Read, create, update, and delete them, manage tags and owners, activate and scan them, read signal intelligence, and push them to your CRM.

List accounts

GET/accounts

Returns accounts ordered by score (highest first), paginated. Supports filters:

Query parameters

statusstringoptional

Filter by suggested, active, rejected, or unqualified.

owner_idstringoptional

Filter by assigned owner (user id).

tagstringoptional

Filter to accounts carrying this tag.

domainstringoptional

Substring match on domain.

industrystringoptional

Substring match on industry.

min_scoreintegeroptional

Only accounts scoring at or above this value.

searchstringoptional

Substring match on name or domain.

sortstringoptional

score (default), last_signal_at, or created_at.

orderstringoptional

asc or desc. Default desc.

pageintegeroptional

Page number. Default 1.

per_pageintegeroptional

Max 100. Default 50.

Request

curl "https://usehunch.co/api/v1/accounts?status=active&min_score=70&per_page=25" \
  -H "Authorization: Bearer hunch_YOUR_KEY"

Response

{
  "data": [
    {
      "id": "...",
      "name": "Ramp",
      "domain": "ramp.com",
      "status": "active",
      "score": 88,
      "employees": 1000,
      "industry": "Financial Services",
      "location": "New York, NY",
      "country": "United States",
      "tags": ["strategic"],
      "owner_id": null,
      "linkedin_url": "https://www.linkedin.com/company/ramp",
      "short_description": "Finance automation platform...",
      "logo_url": "...",
      "created_at": "2026-07-01T...",
      "last_signal_at": "2026-07-03T...",
      "is_hot": true,
      "qualified": true
    }
  ],
  "pagination": { "total": 42, "page": 1, "per_page": 25, "has_more": true }
}

Create accounts

POST/accounts

Accepts a single account object or an array (max 500). Deduplicates by domain within the workspace, so re-posting an existing domain is a no-op. Created accounts default to suggested status.

Body fields

namestringrequired

Company name.

domainstringoptional

Company domain, e.g. acme.com. Used for deduplication.

statusstringoptional

suggested (default) or active.

tagsstring[]optional

Tags to attach.

owner_idstringoptional

Assign to a workspace member.

Request

curl -X POST https://usehunch.co/api/v1/accounts \
  -H "Authorization: Bearer hunch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "Acme", "domain": "acme.com", "tags": ["inbound"] },
    { "name": "Globex", "domain": "globex.com" }
  ]'

Get an account

GET/accounts/:id

Returns the full account including firmographics, why_now_md, source, and last_scanned_at.

Update an account

PATCH/accounts/:id

Patchable fields:

namestringoptional

Company name.

domainstringoptional

Company domain.

tagsstring[]optional

Replaces the tag list.

owner_idstringoptional

Assign or reassign owner.

employees / industry / location / countrymixedoptional

Firmographic overrides.

linkedin_url / short_descriptionstringoptional

Profile overrides.

Delete an account

DELETE/accounts/:id

Permanently deletes the account and tears down its monitor.

Response

{ "data": { "id": "...", "deleted": true } }

Activate an account

POST/accounts/:id/activate

Flips a suggested account to active, consuming a plan credit, then enriches it and starts monitoring it, the same flow as the in-app Activate button. Optionally set the owner in the body.

Body fields

owner_idstringoptional

Optional. Assign an owner on activation.

Activation requires an active subscription and available credits. Returns 402 with no subscription or when the plan account limit is reached.

Reject an account

POST/accounts/:id/reject

Rejects a suggested account, setting its status to rejected. Active accounts cannot be rejected, deactivate or delete them instead.

Scan an account

POST/accounts/:id/scan

Enqueues a fresh research pass for the account across every active signal. Returns immediately with the run id, work executes in the background.

Scans consume paid research resources and require an active subscription. Without one it returns 402.

202 Accepted

{ "data": { "run_id": "...", "jobs": 4, "status": "running" } }

Add tags

POST/accounts/:id/tags

Merges tags into the account's existing tag list (deduplicated).

Body fields

tagsstring[]required

Tags to add.

Response

{ "data": { "id": "...", "tags": ["inbound", "strategic"] } }

Remove tags

DELETE/accounts/:id/tags

Removes the given tags from the account.

Body fields

tagsstring[]required

Tags to remove.

Assign owner

PUT/accounts/:id/owner

Assigns or clears the account owner. owner_idmust be a workspace member's user id, or null to unassign.

Body fields

owner_idstring | nullrequired

A member's user id, or null to clear.

Response

{ "data": { "id": "...", "owner_id": "..." } }

Get an account's signal detections

GET/accounts/:id/signals

Returns every signal detection for the account, newest first, including signal_present, alpha (score), icp_fit, headline, narrative, why_reach_out_md, drafted_message_md, evidence, key_facts, personas, and sources.

Response

{
  "data": [
    {
      "id": "...",
      "signal_id": "...",
      "signal_present": true,
      "alpha": 88,
      "icp_fit": 91,
      "detected_at": "2026-06-28",
      "headline": "New CRO hired, pipeline build begins",
      "narrative": "...",
      "why_reach_out_md": "...",
      "drafted_message_md": "...",
      "evidence": [ { "claim": "...", "source_url": "...", "published_date": "..." } ],
      "key_facts": ["..."],
      "personas": ["VP Revenue Operations"],
      "sources": ["https://..."],
      "created_at": "2026-06-28T..."
    }
  ]
}

Get an account's monitor events

GET/accounts/:id/monitor-events

Returns the paginated activity feed for the account's monitor, what it surfaced on each pass and how each item was judged.

Query parameters

pageintegeroptional

Page number. Default 1.

per_pageintegeroptional

Max 100. Default 25.

Response

{
  "data": [
    {
      "id": "...",
      "url": "https://...",
      "status": "processed",
      "search_status": "hit",
      "meaningful": true,
      "confidence": 0.82,
      "reason": "New executive announcement matches signal",
      "run_id": "...",
      "created_at": "2026-07-03T..."
    }
  ],
  "pagination": { "total": 120, "page": 1, "per_page": 25, "has_more": true }
}

Push accounts to CRM

POST/accounts/crm-push

Pushes the given accounts to the connected CRM (HubSpot) with their signal context. Requires a connected CRM integration.

Body fields

account_idsstring[]required

Accounts to push.

Request

curl -X POST https://usehunch.co/api/v1/accounts/crm-push \
  -H "Authorization: Bearer hunch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_ids": ["...", "..."] }'

PreviousOverview & auth Next People