Examples use fictional data. Every company, person, address and count in them is invented, and their domains use the reserved .example TLD.

GTM data

Search

One filter grammar across companies, people and places. Send structured filters, plain language, or both — the response always tells you how it was read.

6 endpoints

POST/v1/search/companiesSearch companies
POST/v1/search/peopleSearch people
POST/v1/search/placesSearch places
POST/v1/search/interpretInterpret a query
POST/v1/saved-searchesSave a search
GET/v1/saved-searchesList saved searches

The filter object

Every search endpoint takes the same filters object; irrelevant keys are ignored rather than rejected, so one saved filter set can drive a company search and the people search that follows it. Array filters are OR within a key and AND across keys.

Field	Type	Description
`q`	string	Plain-language query. Parsed into structured filters and merged with anything you set explicitly.
`countries`	string[]	ISO-3166 alpha-2 codes, e.g. ["US","GB"].
`regions`	string[]	Region slugs from /v1/geo, e.g. ["north-america","europe"].
`industries`	string[]	NACE codes or industry labels from /v1/industries.
`segments`	string[]	Segment slugs from /v1/segments. The sharpest filter in the set.
`employeeMin`	number	Lower bound on headcount, inclusive.
`employeeMax`	number	Upper bound on headcount, inclusive.
`revenueRanges`	string[]	Revenue bands, e.g. ["$1M-$10M","$10M-$50M"].
`foundedAfter`	number	Four-digit year. Keeps companies founded in or after it.
`techStack`	string[]	Detected technologies, e.g. ["Shopify","HubSpot"]. Matched with AND.
`hasEmail`	boolean	People search only. Keeps rows with a deliverable address.
`hasPhone`	boolean	People search only. Keeps rows with a direct phone number.
`titles`	string[]	People search. Title fragments, matched loosely: ["Head of Events"].
`seniorities`	string[]	c_level, founder, vp, director, manager or ic.
`departments`	string[]	Department buckets, e.g. ["marketing","operations"].
`emailStatus`	EmailStatus[]	valid, accept_all, risky, invalid or unknown.
`aiCriteria`	string[]	Free-text tests run per row by an LLM. Charged separately — see credits.
`sort`	string	relevance (default), employees_desc, employees_asc or recent.
`limit`	number	Rows to return. Default 25, maximum 100.
`offset`	number	Rows to skip. Use with limit to page.

Before the data catalog is loaded

Until a deployment’s catalog is loaded, every search answers with no rows, total: 0 and catalog_empty: true, and charges nothing — so an integration can tell “nothing is loaded yet” from “the filters matched nothing”.

POST/v1/search/companies

Search companies

Semantic and structured search across the company graph. Returns full company records plus the unpaged total.

API key or session1 credit per row returned

Body parameters

Field	Type	Description
filtersreq	SearchFilters	The filter object documented above.

curl -X POST "https://beamro.com/api/v1/search/companies" \
  -H "x-api-key: $SALVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "filters": {
      "q": "event design studios that install florals",
      "countries": [
        "US"
      ],
      "employeeMin": 5,
      "employeeMax": 50,
      "sort": "relevance",
      "limit": 25
    }
  }'

200 response

{
  "rows": [
    {
      "id": "cmp_3h8q1w6x0m4v9k2t7b",
      "domain": "harlowmeadow.example",
      "name": "Harlow Meadow Events",
      "legal_name": "Harlow Meadow Events LLC",
      "description": "Full-service event design studio for weddings and corporate galas.",
      "ultimate_profile": "Designs and installs floral and lighting schemes for 60–90 events a year across the north-east US.",
      "industry_nace": "N82.30",
      "industry_labels": [
        "Event management",
        "Event design"
      ],
      "employee_count": 24,
      "employee_range": "11-50",
      "revenue_range": "$1M-$10M",
      "founded_year": 2011,
      "country": "US",
      "country_name": "United States",
      "region": "north-america",
      "city": "Providence",
      "address": "100 Sample Street",
      "lat": 41.824,
      "lng": -71.4128,
      "website": "https://harlowmeadow.example",
      "linkedin_url": "https://www.linkedin.example/company/harlow-meadow-events",
      "logo_url": null,
      "tech_stack": [
        "HubSpot",
        "Squarespace",
        "Stripe"
      ],
      "socials": {
        "instagram": "https://instagram.example/harlowmeadow"
      },
      "funding": null,
      "registry": {
        "number": "RG421887",
        "status": "active"
      },
      "gmaps": {
        "rating": 4.8,
        "reviews": 214
      },
      "sources": [
        "website",
        "linkedin",
        "gmaps"
      ],
      "quality_score": 91,
      "updated_at": "2026-08-14T09:12:44.000Z"
    }
  ],
  "total": 312,
  "took_ms": 84,
  "interpretation": {
    "intent": "companies",
    "filters": {
      "segments": [
        "event-management"
      ],
      "countries": [
        "US"
      ],
      "employeeMin": 5,
      "employeeMax": 50
    },
    "explanation": "Read as the event-management segment in the United States, 5 to 50 staff."
  },
  "credits_charged": 25
}

Spending credits takes the member role: a session with the viewer role, or an API key with read-only scope, gets 403 forbidden before anything is read or charged.

POST/v1/search/people

Search people

Decision-maker search over the same graph, joined to their company. Email addresses come back with a deliverability status.

API key or session3 credits per person returned with an email, 2 per person returned without one — charged for the page the call returns

Body parameters

Field	Type	Description
filtersreq	SearchFilters	Title, seniority, department and email filters apply here.

curl -X POST "https://beamro.com/api/v1/search/people" \
  -H "x-api-key: $SALVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "filters": {
      "segments": [
        "event-management"
      ],
      "titles": [
        "Founder",
        "Head of Events"
      ],
      "seniorities": [
        "founder",
        "c_level"
      ],
      "hasEmail": true,
      "emailStatus": [
        "valid"
      ],
      "limit": 25
    }
  }'

200 response

{
  "rows": [
    {
      "id": "per_2k7n4v9x1m6q0b3t8c",
      "company_id": "cmp_3h8q1w6x0m4v9k2t7b",
      "company_domain": "harlowmeadow.example",
      "company_name": "Harlow Meadow Events",
      "full_name": "Priya Whitcombe",
      "first_name": "Priya",
      "last_name": "Whitcombe",
      "title": "Founder & Creative Director",
      "seniority": "founder",
      "department": "executive",
      "linkedin_url": "https://www.linkedin.example/in/priya-whitcombe-4c",
      "email": "priya.whitcombe@harlowmeadow.example",
      "email_status": "valid",
      "phone": null,
      "country": "US",
      "city": "Providence",
      "updated_at": "2026-08-14T09:12:44.000Z"
    }
  ],
  "total": 486,
  "took_ms": 112,
  "credits_charged": 125
}

POST/v1/search/places

Search places

Physical locations from the maps dataset — ratings, categories, opening hours — linked back to a company where one is known.

API key or session1 credit per row returned

Body parameters

Field	Type	Description
filtersreq	SearchFilters	Geography and query filters apply; people filters are ignored.

curl -X POST "https://beamro.com/api/v1/search/places" \
  -H "x-api-key: $SALVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "filters": {
      "q": "wedding venues",
      "countries": [
        "US"
      ],
      "limit": 25
    }
  }'

200 response

{
  "rows": [
    {
      "id": "plc_8r3v6k1x9m4q2t7b0n",
      "place_id": "ChIJq7v2mK9xQ4cRy1bT5nP0w8E",
      "name": "Harlow Meadow Events",
      "category": "Event design",
      "rating": 4.8,
      "reviews_count": 214,
      "address": "100 Sample Street, Providence",
      "country": "US",
      "city": "Providence",
      "lat": 41.824,
      "lng": -71.4128,
      "phone": "+14015550142",
      "website": "https://harlowmeadow.example",
      "hours": {
        "mon": "09:00-17:00",
        "sat": "10:00-14:00"
      },
      "attributes": {
        "wheelchair_accessible": true,
        "accepts_cards": true
      },
      "company_id": "cmp_3h8q1w6x0m4v9k2t7b"
    }
  ],
  "total": 167,
  "took_ms": 61,
  "credits_charged": 25
}

Spending credits takes the member role: a session with the viewer role, or an API key with read-only scope, gets 403 forbidden before anything is read or charged.

POST/v1/search/interpret

Interpret a query

Turns a sentence into a filter object without running the search. Use it to preview a query, or to build a filter UI that explains itself.

API key or sessionFree

Body parameters

Field	Type	Description
qreq	string	The sentence to parse.
kind	string	companies (default) or people — decides which filter keys are produced.

curl -X POST "https://beamro.com/api/v1/search/interpret" \
  -H "x-api-key: $SALVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "q": "boutique hotels in Portugal with fewer than 40 rooms",
    "kind": "companies"
  }'

200 response

{
  "intent": "companies",
  "filters": {
    "segments": [
      "hotels"
    ],
    "countries": [
      "PT"
    ],
    "employeeMax": 40
  },
  "explanation": "Hotels in Portugal. Room count is approximated with headcount, which tracks it closely at this size."
}

POST/v1/saved-searches

Save a search

Stores a named filter set so the dashboard, an export and a campaign can all target the same definition.

API key or sessionFree

Body parameters

Field	Type	Description
namereq	string	Label shown in the dashboard.
kindreq	string	companies, people or places.
filtersreq	SearchFilters	The filter object to store.

curl -X POST "https://beamro.com/api/v1/saved-searches" \
  -H "x-api-key: $SALVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "US event designers, 5-50",
    "kind": "companies",
    "filters": {
      "segments": [
        "event-management"
      ],
      "countries": [
        "US"
      ],
      "employeeMin": 5,
      "employeeMax": 50
    }
  }'

200 response

{
  "id": "sch_5v8p2q0w7m1x4h6t9c"
}

GET/v1/saved-searches

List saved searches

Every saved filter set in the workspace, newest first.

API key or sessionFree

curl "https://beamro.com/api/v1/saved-searches" \
  -H "x-api-key: $SALVO_API_KEY"

200 response

{
  "rows": [
    {
      "id": "sch_5v8p2q0w7m1x4h6t9c",
      "name": "US event designers, 5-50",
      "kind": "companies",
      "filters": {
        "segments": [
          "event-management"
        ],
        "countries": [
          "US"
        ],
        "employeeMin": 5,
        "employeeMax": 50
      }
    },
    {
      "id": "sch_1n4b7d2k9s3f0g8j5l",
      "name": "Planners with verified email",
      "kind": "people",
      "filters": {
        "segments": [
          "wedding-planners"
        ],
        "hasEmail": true,
        "emailStatus": [
          "valid"
        ]
      }
    }
  ]
}