Skip to main content
POST
/
companies
/
advertisements
/
search
Search for company advertisements
curl --request POST \
  --url https://api.pubrio.com/companies/advertisements/search \
  --header 'Content-Type: application/json' \
  --header 'pubrio-api-key: <api-key>' \
  --data '
{
  "target_locations": [
    "TW",
    "AE",
    "NO"
  ],
  "exclude_target_locations": [
    "IS",
    "GB",
    "FR",
    "IE",
    "ES"
  ],
  "search_terms": [
    "pubrio"
  ],
  "headlines": [
    "ASUS",
    "iPhone"
  ],
  "filter_conditions": [
    {
      "key": "exclude_target_locations",
      "operator": "or"
    }
  ],
  "start_dates": [
    "2025-12-01",
    "2025-12-01"
  ],
  "end_dates": [
    "2025-12-25",
    "2025-12-25"
  ],
  "company_locations": [
    "US",
    "SG",
    "CN"
  ],
  "companies": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "domains": [
    "pubrio.com"
  ],
  "linkedin_urls": [
    "https://www.linkedin.com/company/pubrio"
  ],
  "is_realtime_enrichment": true,
  "source_types": [
    "linkedin",
    "facebook"
  ],
  "enrichment_mode": "latest",
  "per_page": 25,
  "page": 1,
  "profile_id": 123
}
'
{
  "data": {
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total_entries": 694356,
      "total_pages": 27775,
      "total_display_pages": 250,
      "is_timeout": false
    },
    "advertisements": [
      {
        "advertisement_id": "3af8cb80-9a04-49a8-832d-333961d5f77a",
        "advertisement_search_id": "3af8cb80-9a04-49a8-832d-333961d5f77a",
        "created_at": "2026-03-03T01:46:35.909Z",
        "last_modified": "2026-03-03T12:46:25.289Z",
        "started_at": "2026-02-25T00:00:00.000Z",
        "ended_at": "2026-03-02T00:00:00.000Z",
        "title": "Thuraya-4 Satellite Solutions for Energy",
        "source_type": "linkedin",
        "advertisement_format": "Single Image Ad",
        "video_url": null,
        "image_url": "https://buckets.pubrio.com/images/public/cL1U5ghYPAy65qc4cu5wtmgzv8P9xJgrofNTwohPWsyT3S5ob2zNp6Jov1nM9aaDRy.jpg",
        "carousel_images": null,
        "destination_url": "https://www.thuraya.com/en/thuraya-4-ngs/home/index.html?trk=ad_library_ad_preview_headline_content",
        "companies": {
          "logo_url": "https://buckets.pubrio.com/company-logo/MjA3NTQ4NjQyM2lsajlzc25qMXNwYWNlNDIuYWlsaW5rZWRpbl82NDIyMjM3NA==.jpg",
          "domain_search_id": "fe3963dc-87a4-4016-8c95-217ea68cd57a",
          "company_name": "Space42",
          "linkedin_name": "space42ai",
          "country_code": "AE",
          "domain": "space42.ai"
        }
      },
      "..."
    ]
  }
}

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
​
target_locations
string[]

Filter advertisements to include those targeting specific locations by country code. Use this to find ads that are being shown in specific countries. Combines with filter_conditions using OR operator - the advertisement must target at least one of the specified locations.

Example:
["TW", "AE", "NO"]
​
exclude_target_locations
string[]

Filter advertisements to exclude those targeting specific locations by country code. Use this to filter out ads that are being shown in specific countries. When specified in filter_conditions with operator 'or', the advertisement must not target any of the excluded locations.

Example:
["IS", "GB", "FR", "IE", "ES"]
​
search_terms
string[]

A list of strings over which we want to filter the results.

Example:
["pubrio"]
​
headlines
string[]

A list of headlines to filter search results.

Example:
["ASUS", "iPhone"]
​
filter_conditions
object[]

Advanced filtering options for advertisement searches. Specify conditions to refine your search results for the ads search endpoint.

​
start_dates
string<date>[]

A list of start dates to filter search results.

Example:
["2025-12-01", "2025-12-01"]
​
end_dates
string<date>[]

A list of end dates to filter search results.

Example:
["2025-12-25", "2025-12-25"]
​
company_locations
string[]

The location of the company headquarters. Check out location endpoints under the Filters tab for more information.

Example:
["US", "SG", "CN"]
​
companies
string<uuid>[]

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

​
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:
["pubrio.com"]
​
linkedin_urls
string[]

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

Example:
["https://www.linkedin.com/company/pubrio"]
​
is_realtime_enrichment
boolean
default:false

Opt into realtime enrichment for a single, company-scoped query (filtered by domain_search_id, domains, or linkedin_urls). When the initial search returns zero results, the endpoint scrapes the source, persists the records, and re-runs the search before responding. Subject to a per-route deadline.

Example:

true

​
source_types
enum<string>[]

Restricts which advertisement source types are eligible for realtime enrichment. Defaults to all sources when omitted. Only applies when realtime enrichment actually runs — i.e. when is_realtime_enrichment or enrichment_mode: latest is set.

Available options:
linkedin,
facebook,
google
Example:
["linkedin", "facebook"]
​
enrichment_mode
enum<string>
default:default

Controls realtime enrichment behavior. default returns whatever is already in the database, and triggers enrichment only when the result set is empty and is_realtime_enrichment is set. latest bypasses the cache and forces a re-enrichment pass against the freshest source records on every call — it triggers enrichment on its own without needing any other flag.

Available options:
default,
latest
Example:

"latest"

​
per_page
integer

The number of search results that should be returned for each page. Limited the number of results per page improves the endpoint's performance.

Example:

25

​
page
integer

The page number of the Pubrio data that you want to retrieve.

Example:

1

​
profile_id
integer

Optional. An identifier for the user profile (workspace) making the request. This is no longer required as the API key already includes your workspace information. If provided, it helps in associating the lookup with a specific user, allowing for data retrieval and credit tracking.

Check out user details endpoints under the Profile tab for more information.

Response

Successful response containing company advertisement search details.

​
data
object

Response info depends on specific endpoint.