Integration guide for sales intelligence software
This guide provides detailed instructions on integrating TheirStack into your product, including all possible connectors, marketing content and best practices.
Are you a sales intelligence platform like Clay, Databar, or Trigify? We've compiled everything you need to seamlessly integrate TheirStack as a source of job data and technographics into your product. This is a dynamic, evolving guide that improves with each integration. Your feedback and suggestions are always welcome!
Introduction
At TheirStack, we are passionate about building long-term partnerships with sales intelligence platforms. Our goal is to become the largest, most reliable, and fastest-responding job and technographics database. Everything we do is driven by this vision. If you're seeking top-quality job and technographic data, we're the ideal partner for you.
Why TheirStack is the right partner for you
- Coverage:
- Job data: 355k job data sources, 30+ advanced job and company filters, worldwide coverage. (learn more).
- Technographics data: 33k technologies and 13M companies. Learn more
- API designed for you:
- Use our API Preview mode to show a preview to your end users.
- Use our Free count to estimate the number of records that match your search criteria with no credits consumption.
- Pricing Flexibility:
- We know estimating your consumption is hard, with us you don't need to worry about it. You can start with a low volume of credits and increase it as your users need more data. No commitment, cancel anytime, and you can enable a auto recharge rule to avoid running out of credits.
- Learn how our API pricing works here
Use cases
TheirStack allow you to build different features in your platform:
| Type | Features |
|---|---|
| On-Demand Actions (API) When your users actively request information | List Building - Find jobs - Find companies by hiring signals - Find companies by tech stack Enrichment - Get the tech stack of a company - Get all jobs posted by a company |
| Real-Time Signals (Webhooks) Trigger workflows when an event occurs | - Monitor new jobs - Detect companies adopting new technologies - Detect when the tech stack of a company changes |
| Bulk (Datasets) Load the data into your own warehouse at scale | - Backfill your product with the full jobs, companies or technographics database - Run analytics, matching or ML on the complete dataset - Keep a local copy in sync with recurring deliveries |
Features
List building
The list building category are all the features that start from a collection of filters and return a list of records (jobs or companies)
Find jobs / Find companies by hiring signals
These two features share the same filters, in the same order, backed by the same catalogs. The only difference is which endpoint you call, depending on what you want to return:
- Return jobs → use the Job Search API endpoint.
- Return companies → use the Company Search API endpoint. Pass the job filters below inside the
job_filtersobject, and you'll get back the companies currently hiring that match them, along with the matching jobs for each company.
Catalogs: several filters take IDs or slugs instead of free text. Use our catalog endpoints to power the autocomplete inputs in your UI: Locations (countries, states and cities with their IDs), Technologies, and Industries. They are free to call and don't consume credits.
Call the catalogs live — don't ship a downloaded copy
Query the catalog endpoints from your product rather than exporting them once and hardcoding the result. We add technologies continuously, so a snapshot silently goes stale and your users stop being able to filter by anything new.
Caching is fine and encouraged. What breaks is a list that is never refreshed at all.
The one exception is company HQ country, which takes ISO-2 codes. Those are a stable 250-row standard, so there is no catalog endpoint for them and a hardcoded list is correct.
How to wire the technology picker. The technology catalog has 42k entries, so it is built to be queried, not downloaded — limit=100000 returns a 27MB payload in about 7 seconds and should never be on a user's path:
- On open, with no query:
GET /v0/catalog/keywords?limit=50. Results are sorted by number of companies, so this gives you the most popular technologies for the empty state. This list moves slowly — cache it for hours or a day. - As the user types:
GET /v0/catalog/keywords?q=snow&limit=10. This is the autocomplete path, roughly 350ms, and it rankssnowflakefirst. - Debounce input by ~200ms, so a four-letter query fires one request instead of four.
The industry catalog is the opposite case: 434 entries, ~191KB, well under half a second for the whole thing. Fetch it once on load, cache it, and filter client-side.
Recommended filters sorted by importance:
| # | Filter Name | Description | API Field(s) |
|---|---|---|---|
| 1 | Days since posted (required) | Number of days since the job was posted (default: 30 days) | posted_at_max_age_days |
| 2 | Job location | Locations to include or exclude, at any granularity (country, state or city). Pass location IDs from the Location Catalog | job_location_or, job_location_not |
| 3 | Job titles to include | Keywords to include in the job title | job_title_or |
| 4 | Job titles to exclude | Keywords to exclude from the job title | job_title_not |
| 5 | Job description keywords include | Keywords to include in the job description | job_description_contains_or |
| 6 | Job description keywords exclude | Keywords to exclude from the job description | job_description_contains_not |
| 7 | Job technologies | Technologies mentioned in the job description (see Technology Catalog) | job_technology_slug_or |
| 8 | Remote | Whether the job is remote (yes/no) | remote |
| 9 | Annual salary | Annual salary of the job post | min_salary_usd, max_salary_usd |
| 10 | Has hiring manager | Whether the job lists a hiring manager (yes/no) | only_jobs_with_hiring_managers |
| 11 | Company domain | Company website URL(s) | company_domain_or, company_domain_not |
| 12 | Company name | Name(s) of the company | company_name_or, company_name_not |
| 13 | Company industry | Industry(s) of the company (see Industry Catalog) | industry_id_or, industry_id_not |
| 14 | Company headcount | Number of employees (min and max) | min_employee_count, max_employee_count |
| 15 | Company headquarters country | Company headquarters country codes | company_country_code_or |
| 16 | Company technologies | Technologies used by the company (see Technology Catalog) | company_technology_slug_or, company_technology_slug_and, company_technology_slug_not |
Marketing content to help your users understand this action:
Find companies by tech stack
Use Company Search API endpoint to build this feature.
Recommended filters sorted by importance:
| Order | Filter | Description | API Field |
|---|---|---|---|
| 1 | Technologies used | Back the picker with the Technology Catalog, free to call — see the autocomplete pattern below. Show logo, name, short description (one_liner), category, and number of companies. | company_technology_slug_or, company_technology_slug_and, company_technology_slug_not |
| 2 | Company headquarters country | Options to include or exclude countries. ISO-2 codes. | company_country_code_or, company_country_code_not |
| 3 | Industry | Options to include or exclude industries. Values come from the Industry Catalog — your own industry taxonomy will not match ours. | industry_or, industry_not |
| 4 | Company headcount | Specify minimum or maximum employee count, with options for null values. | min_employee_count, max_employee_count, min_employee_count_or_null, max_employee_count_or_null |
| 5 | Company revenue | Annual revenue in USD. Sparse: filtering on it drops every company we have no revenue for. | min_revenue_usd, max_revenue_usd |
| 6 | Company type | Whether the company hires for itself or for others. Values: direct_employer, recruiting_agency, all — not public/private. | company_type |
| 7 | Company location | Country only. Use the ISO-2 country codes in row 2. Do not use company_location_pattern_or for this — see the warning below. | company_country_code_or, company_country_code_not |
| 8 | Company website | Company website URL(s) | company_domain_or, company_domain_not |
Company location: filter by country, not by pattern
Our company-level geography is only structured to the country. company_country_code_or (ISO-2 codes) is the filter to build your location picker on.
There is also a company_location_pattern_or field, and it is not the company equivalent of the job location filter. It matches the company's city as a case-insensitive substring, so passing a country name into it returns only the handful of companies whose city string happens to contain that name. Filtering companies using Snowflake by company_location_pattern_or: ["United States"] returns 21 companies; company_country_code_or: ["US"] returns 18,987.
Two related traps if you are populating this field from a general-purpose places autocomplete: values that carry a country suffix ("Madrid, Spain") match no city and return zero results with no error, and some inputs are rejected outright. Neither is a coverage problem — it is the wrong field.
Do not use the Location Catalog here either. Those IDs address job locations, at country, state and city granularity, and are the right input for job_location_or on the hiring-signals feature. They do not apply to company HQ.
Use the following content to help your users understand this action.
Enrichment
Get the tech stack of a company
Use Technographics API endpoint to build this feature.
Recommended filters sorted by importance:
| Order | Filter | Description | API Field |
|---|---|---|---|
| 1 | Company website | Website of the company you want to get the technology list | company_domain |
| 2 | Confidence level | Return only technologies with a confidence level of high, medium or low. | confidence_level |
| 3 | Technologies used | Show logo, name, short description (one_liner), category, and number of companies. | company_technology_slug_or, company_technology_slug_and, company_technology_slug_not |
Marketing content to help your users understand this action:
Get all jobs posted by a company
Use Job Search API endpoint to build this feature.
Same filters as the Find jobs action but excluding the company_domain filter.
Marketing content to help your users understand this action:
Datasets
When your product needs the whole dataset rather than per-request lookups — backfilling your own database, running matching or analytics across every record, or training models — use Datasets instead of the API. We deliver flat files (CSV or Parquet) through S3. Between roughly 2M and 5M records/month, a flat subscription may become more cost-effective than per-record API credits, depending on how broad your coverage is and where filtering happens. Contact us to compare both routes.
Three datasets are available, mirroring the API:
| Dataset | Contents | Docs |
|---|---|---|
| Jobs | Every job posting since 2021 across 355k sources: title, description, salary, location, company, and the embedded company_object. | Job dataset |
| Companies | Company profiles: domain, name, industry, headcount, revenue, location. | Company dataset |
| Technographics | Company ↔ technology associations with confidence score, number of jobs, and first/last seen dates. | Technographic dataset |
Update cadence — pick one when you subscribe:
- Historical — a one-time download of everything available at purchase time.
- Recurring updates — fresh download links on the cadence you pick. Jobs and Jobs Closed ship incremental files, so you only ingest what is new; Companies, Technographics and Technologies ship a full snapshot that replaces the previous delivery.
- Complete — historical backfill plus the ongoing updates.
How you access it: browse and download directly from the Datasets page, or pull programmatically by requesting temporary S3 credentials (POST /v1/datasets/credentials) and reading the files with boto3, the AWS CLI, or ClickHouse. Full walkthrough: Accessing datasets.
Integration page
Most sales intelligence software have a page where they list all data sources they have. This is the content we recommend you to add to this page to help your users understand what TheirStack is and how it can help them.
How is this guide?
Last updated on