TheirStack API Reference
Introduction Welcome to the TheirStack API - the largest database of jobs and technographics. You can use this API to access all our API endpoints, such as…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Introduction
Welcome to the TheirStack API - the largest database of jobs and technographics.
You can use this API to access all our API endpoints, such as the Jobs endpoint to get real-time and historical jobs from more than 100 countries, the Companies endpoint to get a list of companies by the technology they use or by the roles they are hiring for, or
the Technographics endpoint to get a list of technologies used by a company.
The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.
A Swagger UI of these docs is also available at /openapi.
Authentication
Authentication is done via the API key which you can find in your account settings.
When making a call, you'll have to specify this API key with the Authorization header. Here's an example:
Authorization: BearerPagination
Responses that return a list of items are paginated. We offer two different pagination strategies:
- Page-based: This method allows you to navigate through paginated data by specifying the
pageandlimitparameters. Thepageparameter indicates the page number you wish to retrieve, while thelimitparameter specifies the maximum number of items to return per page. For POST requests, include these parameters in the request body. For GET requests, use them as query parameters. - Offset-based: This method allows you to navigate through paginated data by specifying the
offsetandlimitparameters. Theoffsetparameter indicates the starting point within the collection of results, while thelimitparameter specifies the maximum number of items to return. For POST requests, include these parameters in the request body. For GET requests, use them as query parameters.
Some of these endpoints also support the include_total_results body or query parameter. If you set it to false, the responses will be faster, and the field total_results of the response will be null.
Rate Limit
All API endpoints are rate limited to ensure reliability and fair usage. When a limit is exceeded, the API returns HTTP 429 Too Many Requests. Limits are applied per user (or per API key) with sliding windows; multiple windows may apply simultaneously.
Tiered endpoints and limits
Endpoints covered by tier-based limits:
- POST
/v1/jobs/search(Jobs Search) - POST
/v1/companies/search(Companies Search) - POST
/v1/companies/technologies(Technographics)
Shared limits across all three endpoints:
| Tier | API limits |
|---|---|
| Free | 4/second, 10/minute, 50/hour, 400/day |
| Paid | 4/second |
- Paid tier applies to users who have made at least one payment.
- Free tier applies to all other users (users who have never paid or users without any payments done).
Multiple limits are applied simultaneously. A request is rejected if it exceeds any active window.
Rate limit headers
The API returns rate limit information in every response. We follow the IETF HTTPAPI draft for RateLimit headers: RateLimit header fields for HTTP. When multiple rate limits apply, header items are comma-separated and ordered consistently across headers.
IETF compliant headers
RateLimit: Current quota status per policy. Format:" "; r= ; t= ; pk=.RateLimit-Policy: Applied policy definition. Format:" "; q= ; w=.
Other headers
These are included for client convenience:
RateLimit-Limit: Total allowed requests for each windowRateLimit-Remaining: Requests remaining in each windowRateLimit-Reset: Seconds until the current window resets
The order of values in legacy headers matches the order of RateLimit items.
Example response headers:
RateLimit: "per-second";r=3;t=1;pk="dXNlcjoxMjM0", "per-minute";r=9;t=60;pk="dXNlcjoxMjM0", "per-hour";r=49;t=3600;pk="dXNlcjoxMjM0", "per-day";r=399;t=86400;pk="dXNlcjoxMjM0"
RateLimit-Policy: "per-second";q=4;w=1, "per-minute";q=10;w=60, "per-hour";q=50;w=3600, "per-day";q=400;w=86400
RateLimit-Limit: 4, 10, 50, 400
RateLimit-Remaining: 3, 9, 49, 399
RateLimit-Reset: 1, 60, 3600, 86400Exceeding limits and best practices
- Retry with exponential backoff on HTTP 429 responses.
- Monitor
RateLimitorRateLimit-RemainingandRateLimit-Resetto avoid hitting limits. - Prefer batching and caching to reduce request counts.
- Avoid concurrent bursts that violate per-second limits.
Endpoints 60
Jobs
- POSTSearch Jobs
/v1/jobs/searchSearch and filter job postings collected from company career sites and job boards. Filter by job title, keywords in the job description, company (name, domain…
Companies
- POSTSearch Companies
/v1/companies/searchSearch and filter companies by firmographics (industry, country, employee count, revenue), funding, the technologies they use (technographics) and hiring… - POSTGet Company Technographics
/v1/companies/technologiesList the technologies a company uses. For each technology, it returns the confidence level (low, medium, high), the number of jobs that mention the… - POSTGet Company Buying Intents
/v1/companies/buying_intentsList 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…
Saved Searches
- GETList Saved Searches
/v0/saved_searchesRetrieve all active saved searches of the current team, including search filters, type, and creation date. Archived searches are left out, and so are the ones… - POSTCreate Saved Search
/v0/saved_searchesSave a job or company search so you can run it again, open it in the app or attach a webhook to it. The body takes the same filters as the job or company… - GETGet Saved Search
/v0/saved_searches/:search_idGet one of the team's saved searches by ID: its name, type, filters, email alert settings and whether a webhook is active on it. - PATCHUpdate Saved Search
/v0/saved_searches/:search_idChange a saved search's name, filters, type or email alert. Only the fields you send change. New filters also change what any webhook on this saved search… - PATCHArchive Saved Search
/v0/saved_searches/:search_id/archiveArchive a saved search by its ID to remove it from the active list. Archived searches are hidden from the default listing but can still be referenced.… - GETUnsubscribe From A Saved Search Alert
/v0/saved_searches/alerts/unsubscribe?token=stringThe page an alert email's unsubscribe link opens. It asks the person to confirm before turning off that saved search's alert, because mail security scanners… - POSTOne-Click Unsubscribe From A Saved Search Alert (Rfc 8058)
/v0/saved_searches/alerts/unsubscribe?token=stringTurn off the email alert of the saved search the signed token names. Answers both the one-click unsubscribe mail clients send (RFC 8058) and the button on the…
Catalog
- GETFind Technologies And Topics
/v0/catalog/keywordsList all keywords tracked by TheirStack, including both technologies and buying intent topics. Search for any keyword and filter by one or more categories.… - GETCount Jobs By Country
/v0/catalog/jobs_companies_per_job_country_codeList every country code with the number of jobs located in that country and the number of companies hiring there. Search by country name in English. Free: it… - GETCount Companies By Country
/v0/catalog/companies_per_company_country_codeList every ISO country code with the number of companies headquartered in that country, for geographic distribution analysis. Free: it doesn't consume credits. - GETFind Locations
/v0/catalog/locationsSearch for geographic locations by name or ID to retrieve standardized location data including city, region, and country. Use the location IDs in the… - GETList Industries
/v0/catalog/industriesList the industries and their IDs, with how many jobs and companies we have in each, and search them by name. Use the IDs in the industry filters of a job or… - GETList Keyword Categories
/v1/catalog/keywords/categoriesReturns a list of main keyword categories (technologies and buying intents) with the number of keywords and companies in each. Optionally filters to return a… - GETList Keyword Subcategories
/v1/catalog/keywords/subcategoriesReturns a list of keyword subcategories with their keywords. Behavior: returns all subcategories if no parameters are provided; returns all subcategories for…
Datasets
- GETList Datasets
/v1/datasetsList the datasets available to your team (jobs, companies and technographics), updated daily in Parquet format, with the latest download URLs for bulk data… - POSTGenerate Dataset Credentials
/v1/datasets/credentialsGenerate temporary S3 credentials to directly access and download dataset files from cloud storage. Credentials are valid for 7 days by default and provide…
Company Lists
- GETList Company Lists
/v0/company_listsRetrieve all company lists for the current team including list name, company count, and creation date. Use it to find a list's ID before reading its… - POSTCreate Company List
/v0/company_listsCreate an empty company list for the team. Add companies to it afterwards by their company IDs. - GETGet Company List
/v0/company_lists/:list_idGet one of the team's company lists by ID: its name, owner, type, creation date and number of companies. The companies themselves are not included. - DELETEDelete Company List
/v0/company_lists/:list_idPermanently delete a company list by ID. Only the list goes: the companies in it, and any other list that holds them, are not affected. Only the list's owner… - PATCHRename Company List
/v0/company_lists/:list_idGive one of the team's company lists a new name. The 'Companies seen' list can't be renamed. - GETGet Companies In A List
/v0/company_lists/:list_id/companiesList the companies in one of the team's company lists, each with its company profile and the dates it was added and revealed. Paginated; sort by reveal date… - POSTAdd Companies To List
/v0/company_lists/:list_id/add_companiesDeprecated. Add companies to one of the team's company lists by their company IDs, the id of each company in a company search result. Returns the list with… - POSTDuplicate Company List
/v0/company_lists/:list_id/duplicateCopy one of the team's company lists, with all its companies, into a new list owned by you and named like the original with ' (copy)' added. - POSTRemove Companies From List
/v0/company_lists/:list_id/remove_companiesRemove companies from one of the team's company lists by their company IDs. Only their place in this list goes: the companies, and any other list that holds… - POSTAdd Companies To Multiple Lists
/v0/company_lists/add_companiesAdd the same companies to several of the team's company lists in one call, by their company IDs, the id of each company in a company search result. Nothing is… - GETExport Companies From List
/v0/company_lists/:list_id/companies/exportDeprecated. Export companies from a saved list to a downloadable CSV or XLSX file. The export includes company details such as domain, industry, size,… - POSTAdd Companies To List
/v1/company_lists/:list_id/add_companiesAdd companies to one of the team's company lists by their company IDs, the id of each company in a company search result. Returns the list with its new…
Webhooks
- GETList Webhook Event Types
/v0/webhooks/event-typesReturns supported webhook event types with their metadata. Pass search_type=jobs or search_type=companies to get only the events relevant to that search type. - GETList Webhooks
/v0/webhooksRetrieve all webhooks configured for your team including their status, target URL, event type, and linked saved search. Archived webhooks are excluded unless… - POSTCreate Webhook
/v0/webhooksCreate a webhook on a saved search: each new record the search matches is sent as an HTTP POST to the URL you give, and every record sent consumes credits.… - GETEstimate A Saved Search'S Daily Volume
/v0/webhooks/volume-estimate?search_id=123Returns how many records a saved search matched per day over the last 7 days, and what they would cost. Use it to size max_events_per_day: a cap below… - POSTTest A Webhook Url
/v0/webhooks/testSend a test event to verify connectivity and payload handling. Either provide a webhook_id to test an existing webhook (with optional url/secret overrides),… - GETGet Webhook
/v0/webhooks/:webhook_idRetrieve the full details of a specific webhook by its ID including configuration, status, target URL, event type, linked saved search, and creation… - PATCHUpdate Webhook
/v0/webhooks/:webhook_idReplace a webhook's settings: target URL, saved search, description, one event per company, and daily event limit. Send every setting you want to keep,… - PATCHPause Or Resume A Webhook
/v0/webhooks/:webhook_id/statusPause or resume a webhook. A disabled webhook sends nothing. When you enable it again, by default it delivers every record matched while it was disabled. Pass… - PATCHArchive Webhook
/v0/webhooks/:webhook_id/archiveArchive a webhook by its ID to permanently stop event delivery and remove it from the active webhook list. Archived webhooks and their event history are… - GETList Webhook Events
/v0/webhooks/:webhook_id/eventsRetrieve a paginated list of all events triggered for a specific webhook including delivery status, payload, and timestamps. Filter by event status to find… - GETCount Webhook Events
/v0/webhooks/:webhook_id/events/countCount the events a webhook has triggered, optionally only those with a given delivery status. Use it when the number is all you need, such as how many… - GETCount Webhook Events Per Day
/v0/webhooks/events/countCount the team's webhook events per day over a date range (the last 30 days by default), with the credits they consumed, for one webhook or all of them.… - POSTRetry Webhook Events
/v0/webhooks/events/retrySend failed webhook events again, by their event IDs, to recover from a temporary failure such as a timeout or a server error at the receiving URL. Find the…
Email Preferences
- GETGet Email Preferences
/v0/email-preferencesGet which optional emails the current user receives, grouped by category (usage, alerts, onboarding): form_data holds each preference as true or false, and… - PUTUpdate Email Preferences
/v0/email-preferencesTurn the current user's optional emails on or off. Send only the preferences to change, grouped by category, as true (send) or false (don't send); the rest… - GETUnsubscribe From Email
/v0/email-preferences/unsubscribe/:preference_key?token=stringThe page an email's unsubscribe link opens. It asks the person to confirm before turning off that kind of email, because mail security scanners open every… - POSTOne-Click Unsubscribe (Rfc 8058)
/v0/email-preferences/unsubscribe/:preference_key?token=stringTurn off one kind of email for the person the signed token belongs to. Answers both the one-click unsubscribe mail clients send (RFC 8058) and the button on…
Requests
- GETList Requests
/v0/requests/List your team's individual API and app requests in a time range. Each request reports how many credits it consumed (api_credits, ui_credits), its response… - GETGet Daily Request Analytics
/v0/requests/analyticsDaily request activity with one optional breakdown. Counts and actual ledger credits refer to requests that ran in the selected window, bucketed by request… - GETList Request Filter Values
/v0/requests/facetsObserved filter values from this team's requests in the selected window, intersected with filters on the other dimensions (a facet ignores its own selection… - GETGet Usage Per Request Filter Value
/v0/requests/facets/metricsRequests and credits consumed per observed filter value, plus the search patterns of the selected window. Companion to /v0/requests/facets, which returns the… - GETGet Request Count
/v0/requests/countRetrieve the daily count of API requests made by your team within a specified date range. Filter by types, exact endpoint path, origin, API key or…
Credit Consumption
- GETGet Daily Credit Usage
/v0/teams/credits_consumptionRetrieve daily API and UI credit consumption for your team, by charge date. Set group_by=search_pattern to group each day's credits by search patterns with… - GETList Credit Usage Sources
/v0/teams/credits_consumption/facetsList the endpoints and origins that charged credits to the team in a date range (the last 30 days by default). Use it to pick values for the endpoint and…
App URLs
- POSTGenerate App Url
/v0/app-urlsBuild a deep link into the TheirStack app for a given resource and return it as {"url": ...}. Pick the resource with the type field: company_list (view a…
API Keys
- GETList Api Keys
/v0/api-keys/usageEvery active key of the current team, with the calls it made over the usage window and whether the member who created it still belongs to the workspace. Key… - GETList One Member'S Api Keys Before Removing Them
/v0/api-keys/usage/member/:user_idThe active keys this member created for the current team, with the calls each made over the usage window. An empty list means removing them breaks no…
Billing
- GETGet Credit Balance
/v0/billing/credit-balanceRetrieve your team's current credit balance including remaining credits available for API calls, searches, and data exports across all endpoints.
API details
- Base URL
https://api.theirstack.com- Authentication
- A bearer token in the Authorization header
- Operations
- 60 operations on 50 pathsGET 34POST 18PATCH 6PUT 1DELETE 1
2 marked deprecated - Main resources
- Webhooks 13Company Lists 12Catalog 7Saved Searches 7Requests 5Email Preferences 4Companies 3API Keys 2App URLs 2Credit Consumption 2
- Response formats
application/jsontext/html- Webhooks
- 3 described
- Description format
- OpenAPI 3.1.0, API version
1.0.0 - Links
- OpenAPI document
- Listed from
- Theirstack's published OpenAPI description
How to test the TheirStack API Reference in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the TheirStack API Reference collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Search Jobs” (POST /v1/jobs/search), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the TheirStack API Reference?
Introduction Welcome to the TheirStack API - the largest database of jobs and technographics. You can use this API to access all our API endpoints, such as… It is listed under Data & analytics and has 60 endpoints.
Who publishes the TheirStack API Reference?
It is listed from TheirStack.com's public API description (an OpenAPI document), not published by TheirStack.com on Swastik Codes. Anyone who controls theirstack.com can claim the profile by adding a DNS TXT record.
What is the base URL of the TheirStack API Reference?
Requests go to https://api.theirstack.com. Endpoint paths are added to this base URL.
How do I authenticate with the TheirStack API Reference?
With A bearer token in the Authorization header.
How many endpoints does the TheirStack API Reference have?
60 operations on 50 paths (34 GET, 18 POST, 6 PATCH, 1 PUT, 1 DELETE). The largest groups are Webhooks, Company Lists, Catalog, Saved Searches.
Is forking the TheirStack API Reference free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.