Companies

Get Company Buying Intents

Changed on

List the buying intent topics detected for a company. For each topic, it returns the confidence level (low, medium, high), the number of jobs that mention the topic, and the first and last dates it was mentioned.

You must specify at least one of company_domain, company_name or company_linkedin_url.

It consumes 3 API credits per company lookup, regardless of the number of buying intent topics returned. It doesn't consume credits if there is no response.

post/v1/companies/buying_intents

Request

  • Base URL
    https://api.theirstack.com
  • URL
    https://api.theirstack.com/v1/companies/buying_intents
  • Auth
    HTTP bearer

Request body

company_idstring nullable

Only return companies that match this TheirStack Company ID exactly. This ID is temporary and internal and will change in the future and become stable. Until then, it is only meant to be used internally by our UI (app.theirstack.com). For deduplication logic, use company_domain or company_linkedin_url instead.

company_namestring nullable

Only return companies that match this name exactly, case-sensitively.

company_domainstring nullable

Only return companies that match this domain exactly. It accepts full urls (https://www.google.com/) and emails (andrew@stripe.com).

company_linkedin_urlstring nullable

Return companies whose LinkedIn URL matches this URL exactly.

company_name_orstring[]

Only return companies that match these names exactly, case-sensitively. Deprecated, use the company_name filter instead.

include_total_resultsboolean nullable

When enabled, calculates and returns total_results and total_companies fields in the response. WARNING: This significantly slows down responses as it requires reading the entire dataset. Recommended usage: enable only for the initial request to get totals, then disable for subsequent pagination requests.

offsetinteger nullable

Number of results to skip. Required for offset-based pagination.

pageinteger nullable

Page number. Required when using page-based pagination.

limitinteger nullable

Number of results per page

keyword_slug_orstring[]

Only return these keywords (technologies or buying intent topics). Case sensitive. Pass slugs. Check out all keywords at GET /v0/catalog/keywords

keyword_category_slug_orstring[]

Only return keywords from any of these categories. Case sensitive. Pass slugs. Check out all keyword categories at GET /v1/catalog/keywords/categories

keyword_parent_category_slug_orstring[]

Only return keywords from any of these parent categories. Case sensitive. Pass slugs. Check out all keyword categories at GET /v1/catalog/keywords/categories

technology_slug_orstring[]

Deprecated: use keyword_slug_or instead. Only return these technologies. Case sensitive. Pass slugs.

technology_category_slug_orstring[]

Deprecated: use keyword_category_slug_or instead. Only return keywords from any of these categories. Case sensitive. Pass slugs.

technology_parent_category_slug_orstring[]

Deprecated: use keyword_parent_category_slug_or instead. Only return keywords from any of these parent categories. Case sensitive. Pass slugs.

max_rankinteger nullable

The rank measures how common a keyword (technology or buying intent topic) is within its category for a company. The keyword most mentioned among similar ones by a company has a rank of 1, the second 2, etc. Useful to keep only the primary technology or topic of each category.

min_jobsinteger nullable

Minimum number of jobs in which each company mentions the keyword (technology or buying intent topic)

max_jobsinteger nullable

Maximum number of jobs in which each company mentions the keyword (technology or buying intent topic)

min_relative_occurrencenumber nullable

Minimum value of relative_occurrence_within_category for each keyword (technology or buying intent topic). Higher values increase the probability that the company actually uses the technology or cares about the topic, because a higher share of the mentions within that category are of this keyword.

first_date_found_gtestring date nullable

Only return keywords (technologies or buying intent topics) where the first time they were found was after or on this date. Format: "YYYY-MM-DD"

first_date_found_ltestring date nullable

Only return keywords (technologies or buying intent topics) where the first time they were found was before or on this date. Format: "YYYY-MM-DD"

last_date_found_gtestring date nullable

Only return keywords (technologies or buying intent topics) where the last time they were found was after or on this date. Format: "YYYY-MM-DD"

last_date_found_ltestring date nullable

Only return keywords (technologies or buying intent topics) where the last time they were found was before or on this date. Format: "YYYY-MM-DD"

confidence_orstring[]

Only return keywords (technologies or buying intent topics) detected with any of these confidence levels. Available values: "high", "medium", "low"

Example request

{
  "company_name_or": [],
  "order_by": [
    {
      "field": "confidence"
    }
  ]
}

Response

Successful Response

Example response

{
  "data": [
    {
      "technology": {
        "name": "PostgreSQL",
        "category": "Relational Database",
        "slug": "kafka",
        "category_slug": "message-queue",
        "parent_category": "Data Stores",
        "parent_category_slug": "data-stores"
      },
      "jobs": 54
    }
  ],
  "metadata": {
    "total_results": 2034,
    "total_companies": 1045
  }
}

Changes