Skip to main content

Company Search API via Filters

The Company Search API allows you to search for company profiles based on various filters, providing detailed information about companies that match your criteria. This guide will help you understand how to make queries to the API using filters, with easy-to-follow examples.

Endpoint​

POST /screener/company/search

Authentication​

Include your Bearer token in the Authorization header of your request.

Request​

Headers​

  • Content-Type: application/json
  • Authorization: Bearer <your_token>

Body Parameters​

  • filters (array): An array of filter objects specifying your search criteria.
  • page (integer): The page number for pagination.

Building Filters​

Each filter in the filters array is an object that specifies a filter_type and associated parameters. You can combine multiple filters to refine your search results.

For detailed information on how to build filters, including valid filter_type values and their usage, refer to How to Build Filters.

Example Request​

Example 1: Companies with Large Headcounts and High Revenue Outside the US​

To find companies with headcounts over 1,000 employees, annual revenue between $1 million and $500 million USD, excluding companies in the United States:

{
  "filters": [
    {
      "filter_type": "COMPANY_HEADCOUNT",
      "type": "in",
      "value": ["1,001-5,000", "5,001-10,000", "10,001+"]
    },
    {
      "filter_type": "ANNUAL_REVENUE",
      "type": "between",
      "value": { "min": 1, "max": 500 },
      "sub_filter": "USD"
    },
    {
      "filter_type": "REGION",
      "type": "not in",
      "value": ["United States"]
    }
  ],
  "page": 1
}

Example 2: Technology Companies Hiring on LinkedIn​

To find technology companies that are currently hiring on LinkedIn:

{
  "filters": [
    {
      "filter_type": "INDUSTRY",
      "type": "in",
      "value": ["Technology", "Information Technology and Services"]
    },
    {
      "filter_type": "JOB_OPPORTUNITIES",
      "type": "in",
      "value": ["Hiring on Linkedin"]
    }
  ],
  "page": 1
}

Example 3: Companies with Recent Funding Events​

To find companies that have had funding events in the past 12 months:

{
  "filters": [
    {
      "filter_type": "ACCOUNT_ACTIVITIES",
      "type": "in",
      "value": ["Funding events in past 12 months"]
    }
  ],
  "page": 1
}

Response​

Successful Response (200 OK)​

A successful response returns a JSON object containing:

  • companies: An array of company objects matching your filters.
  • total_display_count: The total number of results available for your query.

Example Response​

{
  "companies": [
        {
            "name": "Mashreq",
            "description": "Disclaimer: Mashreq will never ask for your bank related information via phone call, SMS or email. We will also never contact you from a mobile number to resolve your query.\n\nWelcome to the LinkedIn page of Mashreq. More than half a century old, we proudly think like a challenger, startup, and innovator in banking and finance, powered by a diverse and dynamic team who put customers first. Together, we pioneer key innovations and developments in banking and financial services. Our mandate? To help customers find their way to Rise Every Day, partnering with them through the highs and lows to help them reach their goals and unlock their unique vision of success. Join Mashreq and find your way to Rise Every Day.",
            "linkedin_company_url": "https://www.linkedin.com/company/mashreq-uae/",
            "linkedin_company_id": "11425",
            "website": "http://www.mashreq.com/rise",
            "industry": "Banking",
            "company_type": "Public Company",
            "founded_year": 1967,
            "location": "Dubai, Dubai, United Arab Emirates",
            "headquarters": {
                "country": "United Arab Emirates",
                "geographicArea": "UAE",
                "city": "Dubai",
                "line1": "Mashreq Bank PSC, Umniyati Street (off Al Asayel Street Burj Khalifa Community"
            },
            "employee_count": 9085,
            "employee_count_range": "1001-5000",
            "employee_growth_percentages": [
                {
                    "timespan": "SIX_MONTHS",
                    "percentage": 2
                },
                {
                    "timespan": "YEAR",
                    "percentage": 5
                },
                {
                    "timespan": "TWO_YEAR",
                    "percentage": 15
                }
            ],
            "specialties": [
                "Retail Banking",
                "Corporate Banking",
                "SME Banking",
                "Islamic Banking",
                "Treasury and Capital Markets",
                "Digital Banking",
                "Financial Institutions",
                "Global Trade Banking",
                "Wholesale Banking",
                "International Banking"
            ],
            "revenue_range": {
                "estimatedMinRevenue": {
                    "amount": 500.0,
                    "unit": "MILLION",
                    "currencyCode": "USD"
                },
                "estimatedMaxRevenue": {
                    "amount": 1.0,
                    "unit": "BILLION",
                    "currencyCode": "USD"
                }
            },
            "decision_makers_count": "681",
            "logo_urls": {
                "200x200": "...",
                "100x100": "...",
                "400x400": "..."
      }
    },
    // More company objects...
  ],
  "total_display_count": 120
}

Error Response (400 Bad Request)​

If your filters are invalid or there is an error processing your request, you will receive an error message:

{
  "error": "Failed to parse filters"
}

Usage Notes​

  • Pagination: Each request returns up to 25 results. Use the page parameter to access additional results.
  • Combining Filters: You can combine multiple filters to narrow down your search. Filters are combined using logical AND operations.
  • Valid Values: Ensure you're using valid values for each filter_type. Refer to How to Build Filters for a comprehensive list of filter types and acceptable values.
  • Authentication: A valid Bearer token is required for all requests. Ensure your token has the necessary permissions.

Additional Examples​

Explore more examples and learn how to build complex queries in the How to Build Filters guide.