Skip to main content
POST
Search for companies

Authorizations

​
pubrio-api-key
string
header
required

A unique API token that represents the actions you perform through the API and the corresponding permissions and operations. You can create it through the Settings section.

Body

application/json
​
company_name
string

Filter search results to include a specific company name.

If the value you enter for this parameter does not match with a company's name, the company will not appear in search results, even if it matches other parameters. Partial matches are accepted.

Example:

"pubrio"

​
companies
string<uuid>[]

A list of unique identifiers (domain_search_id) used for company and people search operations.

​
company_groups
integer[]

Restrict to members of these company groups (ids), such as a monitor's source_group_id or excluded_group_id; paginated like any search.

​
domains
string[]

List of company domains used for company and people search operations. If we receive a URL such as www.pubrio.com or https://docs.pubrio.com/, the system will convert it to pubrio.com for processing.

Example:
​
linkedin_urls
string[]

The fully formed URL of the LinkedIn company profile. URL begin with http and contain linkedin.com/company/

Example:
​
company_filters
object

Wrapper object for company-level filters. Recommended grouping that visually separates which keys filter the person (top-level) from which filter the company. Accepts the same keys as the top-level company filters (e.g. technologies, verticals, vertical_categories, vertical_sub_categories, categories, keywords, founded_dates, employees, revenues, company_locations, company_exclude_locations, company_places, company_exclude_places, companies, domains, company_linkedin_urls, is_enable_similarity_search, similarity_score, plus filter_conditions). Engine flattens this object to the top level before processing — top-level keys win on conflict. Same shape used by Monitor company_filters. See the Filters Overview developer guide for examples.

Example:
​
locations
string[]

ISO 3166-1 alpha-2 (cca2) is used for filtering locations. Check out location endpoints under the Filters tab for more information.

Example:
​
exclude_locations
string[]

ISO 3166-1 alpha-2 (cca2) is used to filter out locations that does not need to be returned. Check out location endpoints under the Filters tab for more information.

Example:
​
places
string[]

Place names (city, region) used to filter results. Accepts localized or English place names.

Example:
​
exclude_places
string[]

Place names (city, region) to exclude from results. Accepts localized or English place names.

Example:
​
job_locations
string[]

ISO 3166-1 alpha-2 (cca2) is used for filtering locations. Check out location endpoints under the Filters tab for more information.

Example:
​
job_exclude_locations
string[]

Geographic locations to exclude from job posting results.

Example:
​
job_posted_dates
string[]

Date range of the posted date. The maximum value is the current day. Day boundaries follow your workspace timezone.

Example:
​
job_titles
string[]

Job titles associated with the individuals you aim to locate.

The results will also encompass job titles that include similar terminology, even if they do not match exactly. For instance, searching for software engineer may yield results for individuals with the title senior software engineer.

Example:
​
verticals
integer[]

A list of vertical_id used to search for companies in a specific vertical or industry. To find the ID, call the vertical endpoint under the Filters tab.

This filter supports is_enable_similarity_search, once enabled you can enter any free text, e.g. ["AI"].

​
vertical_categories
integer[]

A list of vertical_category_id used to search for companies in a specific vertical category. To find the ID, call the vertical category endpoint under the Filters tab.

This filter supports is_enable_similarity_search, once enabled you can enter any free text, e.g. ["Information Technology"].

​
vertical_sub_categories
integer[]

A list of vertical_sub_category_id used to search for companies in a specific vertical sub-category. To find the ID, call the vertical sub category endpoint under the Filters tab.

This filter supports is_enable_similarity_search, once enabled you can enter any free text, e.g. ["Software"].

​
categories
integer[]

A list of category_id used to search for specific categories of technology used by companies. To find the ID, call the category endpoint under the Filters tab.

This filter supports is_enable_similarity_search, once enabled you can enter any free text, e.g. ["CDN"].

​
technologies
integer[]

A list of tag_id used to search for specific technologies used by companies. To find the ID, call the technology endpoint under the Filters tab.

This filter supports is_enable_similarity_search, once enabled you can enter any free text, e.g. ["Shopify"].

A product name the technology list knows matches that product and its own products ("Salesforce" also matches Salesforce Desk and Salesforce Service Cloud), never look-alikes; other text matches by similarity.

​
exclude_technologies
string[]

Technologies the company must not use, as tag_ids or, with is_enable_similarity_search, names such as ["Shopify"]. A company with no known technologies is kept.

Example:
​
employees
string[][]

The number range of employees working for the company. This enables you to find companies based on headcount. You can add multiple ranges to expand your search results.

Check out company size endpoints under the Filters tab for more information.

Example:
​
revenues
integer[]

Minimum and maximum range of company revenue.

Example:
​
founded_dates
integer[]

Years of company founded range. The maximum value founded is the current year.

Example:
​
keywords
string[]

A list of keywords to filter companies by relevance, specialties, or descriptions.

Example:
​
social_media
enum<string>[]

Companies with a profile on any of: linkedin, facebook, instagram, tiktok, twitter, x, github, wantedly, rocketpunch. Promote to AND with filter_conditions.

Available options:
linkedin,
facebook,
instagram,
tiktok,
twitter,
x,
github,
wantedly,
rocketpunch
Example:
​
news_categories
string[]

List of category slugs for searching for specific news categories. To find a slug, call the news categories endpoint under the Filters tab.

Example:
​
news_published_dates
string[]

Date range of the published date. The maximum value is the current day. Day boundaries follow your workspace timezone.

Example:
​
advertisement_search_terms
string[]

Keywords used to search within advertisement content or titles.

Example:
​
advertisement_target_locations
string[]

Target geographic locations for advertisements.

Example:
​
advertisement_exclude_target_locations
string[]

Geographic locations to exclude from advertisement targeting.

Example:
​
advertisement_start_dates
string<date>[]

Start date range for advertisement filtering.

Example:
​
advertisement_end_dates
string<date>[]

End date range for advertisement filtering.

Example:
​
advertisement_active_dates
string<date>[]

Find advertisements that were running at any point during this date range (overlap-based: includes ads that started before the range and are still running, not just ads that started inside it).

Example:
​
advertisement_status
enum<string>[]

currently_running: companies with advertising on record. active_last_30_min: companies whose advertising changed in the last 30 minutes.

Available options:
currently_running,
active_last_30_min
Example:
​
advertisement_headlines
string[]

Keywords to search for within advertisement headline text.

Example:
​
advertisement_platforms
enum<string>[]

Filter by which ad library the advertisement was sourced from. Lowercase, case-insensitive. meta is accepted as an alias for facebook.

Available options:
linkedin,
facebook,
google,
tiktok,
apple
Example:
​
advertisement_publisher_platforms
enum<string>[]

Filter Facebook/Meta ads by the platform surface they were delivered on. Lowercase and case-insensitive. Only applies to the facebook source (other sources are single-platform).

Available options:
facebook,
instagram,
messenger,
threads,
audience_network
Example:
​
advertisement_exclude_publisher_platforms
enum<string>[]

Exclude Facebook/Meta ads delivered on these platform surfaces.

Available options:
facebook,
instagram,
messenger,
threads,
audience_network
Example:
​
advertisement_formats
enum<string>[]

Find companies with at least one advertisement in any of these creative formats.

Available options:
image,
video,
text,
carousel,
dynamic_product,
document,
message,
event,
article,
spotlight,
follow,
job,
engagement
Example:
​
advertisement_active_ads
(integer | null)[]

Minimum and maximum count of the company's currently active advertisements, across all countries. Use null for an open-ended bound, e.g. [1, null] for "at least one active ad".

Required array length: 2 elements
Example:
​
advertisement_running_ads
(integer | null)[]

Minimum and maximum count of the company's advertisements that are still running (no end date, or an end date in the future). Currently populated for LinkedIn ads only.

Required array length: 2 elements
Example:
​
advertisement_total_ads
(integer | null)[]

Minimum and maximum count of the company's total advertisements ever recorded, across all countries.

Required array length: 2 elements
Example:
​
advertisement_platform_count
(integer | null)[]

Minimum and maximum number of distinct ad platforms (linkedin, facebook, google, tiktok, apple) the company is actively advertising on.

Required array length: 2 elements
Example:
​
advertisement_format_count
(integer | null)[]

Minimum and maximum number of distinct advertisement creative formats the company is actively running.

Required array length: 2 elements
Example:
​
advertisement_impressions_estimate
(integer | null)[]

Minimum and maximum estimated advertisement impressions, summed across all countries. Only advertisements with a reported impression range are counted.

Required array length: 2 elements
Example:
​
advertisement_country_activity
object

Advertising activity for one specific country. country is required, and at least one other field must be set (a country by itself matches nothing). For an all-country total instead, use the top-level advertisement_active_ads / advertisement_total_ads / advertisement_impressions_estimate filters.

Example:
​
sort_by
enum<string>

Result ordering. Omit for the default relevance order. advertisement_country_rank orders by the company's advertising rank inside the country named in advertisement_country_activity (rank 1 = biggest advertiser in that market) and is ignored unless that filter is present. Pair with is_ascending_order: false to list the smallest advertisers first. Not yet available: name (either direction) and relevance with is_ascending_order: false — those requests time out. Use the default relevance order, number_of_employees or founded_year instead.

Available options:
relevance,
name,
number_of_employees,
founded_year,
advertisement_country_rank
Example:

"advertisement_country_rank"

​
is_ascending_order
boolean

Direction for sort_by. Defaults to ascending, which for advertisement_country_rank means the biggest advertisers first.

Example:

true

​
filter_conditions
object[]

Advanced filtering options for company searches. Specify conditions combining keys and logical operators to refine search results.

​
is_enable_similarity_search
boolean

When enabled, the filters listed above that support similarity searches can be filled with free text for specific IDs.

​
similarity_score
number<float>

It is used in conjunction with is_enable_similarity_search. This number is used to analyze whether a specific slug (e.g. vertical industry, technology) is similar to the user input, and the higher the number, the more stringent it is.

Example:

0.7

​
query
string

Natural-language search. When provided, Pubrio interprets it into the company filters below: industry (and industries to leave out), specialty, technology (and tools to leave out), social profiles, HQ country, region or city, head-count, revenue, founded year, roles being hired and where, news events such as "recently expanded", advertising (platform, format, target country, ad counts, impressions, dates, rank in one country) and cloud hosting (provider, server countries and cities, host and server counts, overall or in one country). Values joined by "or" match any of them; tools or profiles joined by "and" ("uses both Salesforce and HubSpot") must all match. Any explicit filters you also pass take precedence over the interpreted ones. A part of the sentence no filter can express (for example ownership) comes back in metadata.unmatched_criteria rather than being dropped; a sentence with nothing searchable returns no results with metadata.nl_no_intent: true.

Example:

"Food & Beverage companies in Singapore that recently expanded"

​
exclude_fields
string[]

List of fields to exclude from the response payload.

Example:
​
is_parameter_metadata_available
boolean

Indicates whether parameter metadata is available for the request.

​
is_profile_metadata_available
boolean

Indicates whether profile metadata is available for the request.

​
per_page
integer
default:25

Records per page. Defaults to 25, which is also the ceiling on most plans — the limit is your subscription's max_search_per_page, returned by Profile. Exceeding it returns HTTP 416 with code 41676 (or 41613 on company and people search), not a clamped result set.

Required range: x <= 25
Example:

25

​
page
integer
default:1

Page number, starting at 1. The ceiling is your subscription's max_search_page (max_company_search_page for company search), returned by Profile. Exceeding it returns HTTP 416.

Example:

1

​
cloud_footprint_providers
string[]

Companies that use any of these providers anywhere. The unprefixed providers narrows the rows returned; this narrows the companies.

Example:
​
cloud_footprint_exclude_providers
string[]

Remove footprint rows matching these cloud or hosting providers. Scoped to this footprint row — one provider in one country.

Example:
​
cloud_footprint_target_locations
string[]

Companies present in any of these countries anywhere in their footprint.

Example:
​
cloud_footprint_exclude_target_locations
string[]

Remove footprint rows matching these country codes the infrastructure sits in.

Example:
​
cloud_footprint_cloud_regions
string[]

Restrict results to footprint rows matching these cloud regions. Scoped to this footprint row — one provider in one country.

Example:
​
cloud_footprint_exclude_cloud_regions
string[]

Remove footprint rows matching these cloud regions. Scoped to this footprint row — one provider in one country.

Example:
​
cloud_footprint_cities
string[]

Restrict results to footprint rows matching these cities. Scoped to this footprint row — one provider in one country.

Example:
​
cloud_footprint_exclude_cities
string[]

Remove footprint rows matching these cities. Scoped to this footprint row — one provider in one country.

Example:
​
cloud_footprint_first_seen_dates
(string | null)[]

Two ISO 8601 dates (YYYY-MM-DD) bounding when the footprint was first seen. Scoped to this footprint row — one provider in one country.

Required array length: 2 elements
Example:
​
cloud_footprint_last_seen_dates
(string | null)[]

Two ISO 8601 dates (YYYY-MM-DD) bounding when the footprint was last seen. Scoped to this footprint row — one provider in one country.

Required array length: 2 elements
Example:
​
cloud_footprint_is_cross_border_only
boolean

When true, return only footprint rows outside the company's home market. Rows whose company has no known headquarters are excluded.

Example:

true

​
cloud_footprint_host_count
(integer | null)[]

Minimum and maximum hosts. Use null for an open-ended bound. Counted for the whole company, across every provider and country.

Required array length: 2 elements
Example:
​
cloud_footprint_server_count
(integer | null)[]

Minimum and maximum servers (distinct IP addresses). Use null for an open-ended bound. Counted for the whole company, across every provider and country.

Required array length: 2 elements
Example:
​
cloud_footprint_shared_server_count
(integer | null)[]

Minimum and maximum servers shared with other companies. Use null for an open-ended bound. Counted for the whole company, across every provider and country.

Required array length: 2 elements
Example:
​
cloud_footprint_provider_count
(integer | null)[]

Minimum and maximum distinct providers used by the company. Use null for an open-ended bound. Counted for the whole company, across every provider and country.

Required array length: 2 elements
Example:
​
cloud_footprint_country_count
(integer | null)[]

Minimum and maximum countries the company hosts in. Use null for an open-ended bound. Counted for the whole company, across every provider and country.

Required array length: 2 elements
Example:
​
cloud_footprint_cross_border_country_count
(integer | null)[]

Minimum and maximum countries outside the company's home market. Use null for an open-ended bound. Counted for the whole company, across every provider and country.

Required array length: 2 elements
Example:
​
cloud_footprint_region_count
(integer | null)[]

Minimum and maximum cloud regions. Use null for an open-ended bound. Counted for the whole company, across every provider and country.

Required array length: 2 elements
Example:
​
cloud_footprint_city_count
(integer | null)[]

Minimum and maximum cities. Use null for an open-ended bound. Counted for the whole company, across every provider and country.

Required array length: 2 elements
Example:
​
cloud_footprint_primary_provider
string[]

Companies whose single largest provider is one of these.

Example:
​
cloud_footprint_country_activity
object

Bounds scoped to one country: {"country":"DE","host_count":[100,null]} finds companies running 100+ hosts in Germany specifically. The bare cloud_footprint_host_count is the company total across all countries, so the two cannot express this together. country alone is rejected.

Response

Successful response containing company search details.

​
metadata
object

Request context: recent_search_log_identifier, echoed parameters and filters, an optional profile credit block, and ignored_fields (body keys the endpoint dropped).

​
data
object | null

Response info depends on specific endpoint.

Last modified on November 12, 2024