GET /api/companies
Browse and search companies.
Query parameters
| name | Substring match on name (case-insensitive). Example: name=acme |
|---|---|
| domain | Substring match on domain (case-insensitive). Example: domain=acme.com |
| fit | true, false, or unknown (null). Example: fit=true |
| segment | Filter by one or more segments. Repeat param for multi-select. Example: segment=SaaS&segment=Sales |
| owner | Owner user id. Example: owner=usr_12345 |
| overall_score_min | Minimum overall score (integer). Example: overall_score_min=50 |
| overall_score_max | Maximum overall score (integer). Example: overall_score_max=90 |
| never_enriched | true to return companies with no enrichments. Example: never_enriched=true |
| enriched_before | ISO date YYYY-MM-DD. Last completed enrichment on or before this date. Example: enriched_before=2024-07-01 |
| enriched_after | ISO date YYYY-MM-DD. Last completed enrichment on or after this date. Example: enriched_after=2024-01-01 |
| sort | name | domain | fit | segments | overall_score | owner | last_enrichment |
| direction | asc or desc. Defaults to asc when sort provided; otherwise default order is created_at desc. |
| page | 1-based page number. |
| per | Items per page. Default 50. |
Example requests
curl "http://localhost:3000/api/companies?page=1&per=50"
curl "http://localhost:3000/api/companies?name=acme&sort=overall_score&direction=desc"
curl "http://localhost:3000/api/companies?segment=SaaS&segment=Sales&owner=usr_12345"
curl "http://localhost:3000/api/companies?enriched_after=2024-01-01&enriched_before=2024-07-01"
Response
200 OK
{
"items": [
{
"id": "com_12345",
"name": "Acme Inc",
"domain": "acme.com",
"fit": true,
"segments": ["SaaS", "Sales"],
"owner_id": "usr_12345",
"countries_readable": "United States",
"countries": ["US"],
"enrichment_status": "completed"
}
],
"pagination": {
"current_page": 1,
"per_page": 50,
"total_pages": 10,
"total_count": 500
}
}
When sort is omitted, default order is created_at desc. Use fit=unknown to match records where fit is null.
GET /api/companies/:id
Fetch a single company by id.
Path parameters
| id | Company id (format: com_xxx). |
|---|
Example request
curl "http://localhost:3000/api/companies/com_12345"
Response
200 OK
{
"id": "com_12345",
"name": "Acme Inc",
"domain": "acme.com",
"fit": true,
"segments": ["SaaS", "Sales"],
"owner_id": "usr_12345",
"countries_readable": "United States",
"countries": ["US"],
"enrichment_status": "completed"
}
GET /api/companies/ensure
Finds or creates a company by domain and triggers enrichment.
Query parameters
| domain | Required. Company domain. Example: domain=acme.com |
|---|
Example request
curl "http://localhost:3000/api/companies/ensure?domain=acme.com"
Response
202 Accepted when enrichment_status is in_progress; otherwise 200 OK.
{
"id": "com_67890",
"name": "Acme Inc",
"domain": "acme.com",
"fit": true,
"segments": ["SaaS"],
"owner_id": "usr_12345",
"countries_readable": "United States",
"countries": ["US"],
"enrichment_status": "in_progress"
}
This endpoint starts company enrichment if needed and returns the company record.
GET /api/companies/:id/people
Triggers enrichment for company people and returns outreach-ready, enriched people.
Path parameters
| id | Company id (format: com_xxx). |
|---|
Example request
curl "http://localhost:3000/api/companies/com_12345/people"
Response
202 Accepted when all_enriched is false; otherwise 200 OK.
{
"people": [
{
"id": "per_24680",
"name": "Jane Doe",
"enrichment_status": "completed"
}
],
"all_enriched": false
}
The people array contains enriched, outreach-ready people (excluding archived) and includes enrichment_status. all_enriched indicates whether there are no people currently being enriched.