# Airschool full documentation
> Airscale product guides, integration workflows, MCP documentation, and public API reference.
> This is the full public, navigable Airscale documentation corpus.
## AirSchool — Airscale documentation
Source: https://docs.airscale.io/index.md
Description: Master list building, data enrichment, and modern GTM systems with Airscale guides, API references, and best practices.
Master list building, data enrichment, and modern GTM systems
Welcome to AirSchool
Clear, structured documentation to help you get started faster. Explore guides, API references, and best practices.
---
## Scrape a Sales Navigator search
Source: https://docs.airscale.io/docs/sales-navigator.md
Description: Turn your Sales Navigator searches (people only) into actionable prospect lists in Airscale. This feature extracts profiles directly from any Sales Navigator search results, eliminating manual copy-pasting and building targeted lists in minutes
**Note:**
- You can only export **2,500 leads** per search
- We recommend not scraping more than **2,500 leads every 12 hours**
## 0. Prerequisites
- An active LinkedIn Sales Navigator subscription
- A completed search in Sales Navigator with your target prospects
- Airscale Chrome [extension](https://chromewebstore.google.com/detail/airscale-cookie-importer/hklojeelolieobofdgnboacmigmnkbop) installed (for LinkedIn authentication)
## 1. Click on "Scrape Sales Navigator search results"

## 2. Copy the search URL from Sales Navigator
Before scraping, ensure your search is properly configured:
1. Go to Sales Navigator and perform your lead search
2. Apply your target filters (job titles, company size, industry, location, etc.)
3. Review your search results to ensure they match your ideal prospects
4. Copy the search URL from your browser's address bar

## 3. Connect your LinkedIn account
Download the Airscale Chrome extension if you haven't already [here](https://chromewebstore.google.com/detail/airscale-cookie-importer/hklojeelolieobofdgnboacmigmnkbop) or directly with the link on the extraction page
- The extension will automatically extract your LinkedIn session cookie
- Paste your `li_at` cookie into the provided field
- This authenticates your LinkedIn session securely. 2FA adds an extra security layer and is required for Admin roles

```text
# Example cookie value:
AQEFARABAAAAABh3zC8AAAGax5RR6wAAAZsS5x4vTgAAs3wcms4QjA4ZWtWSUZxNDRZQVVJNGdSZHk1bE41a[..]
```
## 4. Launch the extraction
Click **"LAUNCH EXTRACTION"** to begin the scraping process
1. Monitor the progress in real-time on the right panel:
- Validating your LinkedIn session cookie
- Extracting (progress will show here)
- Importing results to a table
2. Wait for completion — most extractions complete within 1–10 minutes

## 5. Access your results
Click **"See your results"** to view your new prospect table:

**Output format:**
| **Field** | **Data level** | Description |
| --- | --- | --- |
| First Name | People | / |
| Last Name | People | / |
| Company Name | Company | / |
| Job title | People | / |
| Location | People | / |
| Linkedin Profile URL | People | / |
| Linkedin Company URL | Company | / |
| Open? | People | / |
| Premium? | People | / |
---
## Extract post likers/commenters
Source: https://docs.airscale.io/docs/likers-commenters.md
Description: Find highly engaged prospects by extracting users who have liked or commented on specific LinkedIn posts. This powerful feature helps you identify people already interested in topics relevant to your business, making them warmer prospects for outreach
**Note:** you can extract up to **3000 post likers/commenters** at once
## 0. Prerequisites
- Access to LinkedIn (personal or Sales Navigator account)
- Specific LinkedIn posts with engagement (likes/comments) to target
## 1. Click on "Extract LinkedIn post likers and commenters"
1. Log into your **Airscale account**
2. Select **"Extract LinkedIn post likers and commenters"** from the available options in the **"Find People"** tab

## 2. Copy the URL of the post
Identify and prepare your target LinkedIn post:
1. **Find a relevant LinkedIn post** with good engagement:
- Industry thought leadership content
- Company announcements from competitors
- Product launches or feature updates
- Industry news or trend discussions
2. **Copy the post URL:**
- Navigate to the specific LinkedIn post
- Click on the post timestamp to open the individual post view
- Copy the full URL from your browser's address bar
- URL should look like: `https://www.linkedin.com/posts/[username]_[post-id]`
3. **Give your extraction a descriptive name:**
- Example: "SaaS CEO Post Engagement | Q1 2024 | Marketing Automation"
- Include the post topic and date for easy reference
4. **Paste the post URL** into the designated field in Airscale
**Pro tip:** choose posts with **50+ engagements** for a meaningful prospect list, but avoid **super viral posts** (3000+ engagements) that may contain less targeted audiences


## 3. Launch the extraction
**Click "LAUNCH EXTRACTION"** to begin the scraping process
1. **Monitor progress in real-time:**
- Validating post access and engagement data
- Extracting user profiles from engagement
- Processing and importing results
2. **Wait for completion** — most extractions complete within 1–5 minutes
**Pro tip:** you can navigate away from this page during extraction
### Recovery and partial results
Airscale saves fetched pages and import progress so an interrupted extraction can resume. If an account becomes unavailable, it can continue with another eligible account and deduplicate saved results. Profile retries reuse the same identity to avoid repeating settled charges. Temporary provider failures and rate limits can delay completion; persistent failures beyond the retry budget require support to resume the extraction.
Check the final counts and any partial-result reason. Provider totals, comment events, and unique authors are different measurements, and a provider cutoff can return fewer results than LinkedIn displays. Recovery does not remove upstream access or pagination limits.
For integrations, use the [Post likers API](/api-reference/post-likers) or [Post commenters API](/api-reference/post-commenters). Their per-page retry keys and cursor rules differ from this background workflow.

## 4. Access your results
**Click "See your results"** to view your engagement-based prospect table:

---
## Single Search
Source: https://docs.airscale.io/docs/single-search.md
Description: Extract people profile information from a LinkedIn URL and find emails and/or phone number
## 1. Click on "Single Search"

## 2. Copy the profile URL of a profile and paste it below

## 3. Specify whether you want to find their professional email and phone numbers
**Note:** you can toggle ON/OFF options to find emails and phone numbers

## 4. Launch the extraction and export the profile to a table
- **Click "EXTRACT PROFILE"** to begin the scraping process
- After a few seconds, we will retrieve the data about the profile, and the results will appear on the right side of the screen

---
## Leads finder
Source: https://docs.airscale.io/docs/leads-finder.md
Description: Export up to 10,000 leads in one search from various filters
**Note**
- You can import up to **10,000 people** per search
- Large searches may take several minutes to complete
- Use specific filters to get the most relevant results within the limit
## 0. Prerequisites
- An active Airscale account with remaining credits
- Clear understanding of your ideal customer profile (ICP)
- Specific criteria for your target prospects (people and company attributes)
## 1. Click on "Leads finder"
1. Log into your **Airscale** dashboard
2. Select **"Leads finder"** from the available modules (look for the Airscale logo icon)
**Note:** the "Leads finder" module is Airscale's native search engine, so you don't need any **external URLs or account connections**

## 2. Apply your search filters
Configure your search criteria using the available filters:
### People Filters
- Current company (you can select an Airscale table containing a list of companies, or use the manual input to enter them manually)
- Job titles
- Seniority level & Experience
- People Location
- Skills
- Language
- Certification
- Keywords in profile
- Profile Badge
### Company Filters
- Company industry
- Company size
- Company headquarter location
- Company type
- Annual revenue
- Keywords in profile
- Founded year range
- Funding
- Employee by department
- Headcount Growth

## 3. Visualize your results
**Click on "Preview search results"** to see a sample of your search results
1. **Review the preview data:**
- Names and current job titles
- Company names
- Geographic locations
- Linkedin URLs
2. **Check the results summary:**
- Total number of matches (e.g., "25 of 558,008 total")
- Quality of matches against your criteria
3. **Refine filters if needed:**
- Add or remove people or company attributes based on preview results
- Modify or refine location targeting for better coverage
**Note:** ensure the preview shows **relevant prospects before importing**. Poor preview results indicate filters need adjustment

## 4. Launch the search
1. **Click "Load all people to a table"** to export the full search to a table
2. **Monitor the import progress:**
- Progress indicator shows "Importing: X/10 000"
- Percentage completion display
- Real-time status updates
3. **Wait for completion:**
- You can navigate away during processing
**Note:** the system **automatically stops at 10,000 results** even if more matches exist. Use more specific filters if you hit this limit and want different prospects

## 5. Access your results
**Click on "Access results"** to view your new prospect table:

---
## Find People
Source: https://docs.airscale.io/docs/find-people.md
Description: Use Airscale's built-in people search to discover prospects based on company, job title, location, and other criteria. This powerful native feature helps you build targeted prospect lists without needing external tools or complex imports
**Note**
- You can import up to **2,500 people** per search
- Large searches may take several minutes to complete
- Use specific filters to get the most relevant results within the limit
## 0. Prerequisites
- An active Airscale account with remaining credits
- Clear understanding of your ideal customer profile (ICP)
- Specific criteria for your target prospects (job titles, company names, locations)
## 1. Click on "Find People"
1. Log into your **Airscale** dashboard
2. **Select "Find people"** from the available modules (look for the Airscale logo icon)
**Note:** the Find People module is Airscale's native search engine, so you don't need any **external URLs or account connections**

## 2. Apply your search filters
Configure your search criteria using the available filters:
### Company Filters
1. **Choose your query method:**
- **Manual input:** type company domains (e.g., `hubspot.com` or `facebook.com`)
- **Airscale table:** select from an existing companies list in your tables, then select the column to use to identify the companies (it’s always best to choose the LinkedIn URL to get more accurate results)
### People Filters
1. **Job titles (required):**
- **Job titles to include:** add specific titles like "Founder," "CEO," "Marketing Director"
- **Job titles to exclude:** remove irrelevant titles to improve targeting
- Use the **"Remove all jobs"** option to reset selections
2. **Location targeting:**
- **Country, city or state to include:** enter geographic filters
- Type locations like "United States," "San Francisco," or "California"
- Multiple locations can be added

## 3. Visualize your results
**Click on "PREVIEW PEOPLE"** to see a sample of your search results.
1. **Review the preview data:**
- Names and current job titles
- Company names and details
- Geographic locations
- Profile completeness
2. **Check the results summary:**
- Total number of matches (e.g., "25 of 558,008 total")
- Quality of matches against your criteria
- Geographic and title distribution
3. **Refine filters if needed:**
- Add or remove job titles based on preview results
- Adjust company size or industry filters
- Modify location targeting for better coverage
**Note:** ensure the preview shows **relevant prospects before importing**. Poor preview results indicate filters need adjustment

## 4. Launch the search
1. **Click "Load all people to a table"** to export the full search
2. **Monitor the import progress:**
- Progress indicator shows "Importing: X/2500"
- Percentage completion display
- Real-time status updates
3. **Wait for completion:**
- You can navigate away during processing
**Note:** the system **automatically stops at 2,500 results** even if more matches exist. Use more specific filters if you hit this limit and want different prospects

## 5. Access your results
**Click on "See your results"** to view your new prospect table:

---
## Find Companies
Source: https://docs.airscale.io/docs/find-companies.md
Description: Use Airscale's built-in company search to discover target businesses based on size, industry, location, and other firmographic criteria. This native feature helps you build comprehensive company lists for account-based prospecting and market research
**Note:**
- You can import up to **10,000 companies** per search
- Large searches may take several minutes to complete
- Use specific filters to get the most relevant companies within the limit
## 0. Prerequisites
- An active Airscale account with remaining credits
- Clear understanding of your ideal customer profile (ICP)
- Specific criteria for your target companies (industry, size, location, etc.)
## 1. Click on "Find Companies"
- Log into your **Airscale** dashboard
- **Select "Find companies"** from the available modules (look for the Airscale icon)
**Note:** the Find Companies module is Airscale's native search engine, so you don't need any external URLs or account connections

## 2. Apply your search filters
Configure your search criteria using the comprehensive filter system:
### Basic company filters
**Company industry:**
- Select from dropdown of industry categories
- Multiple industries can be selected
- Focus on industries where your solution has proven success
**Company size:**
- Choose from predefined ranges: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000
- Select multiple ranges for broader targeting
- Consider your product's sweet spot for company size
**Headquarter location targeting:**
- Include country, state, or city: Enter geographic filters like "United States," "California," or "San Francisco"
- Multiple locations can be added for broader coverage
- Use specific cities for territory-based targeting
**Company number of locations & company age:**
- Set minimum and maximum number of office locations as well as company age in years
- Target single-site startups or multi-location enterprises depending on your ideal customer profile
- Align outreach with companies at the right maturity and operational complexity for your solution

### Advanced growth filters & signals
**Company recent events:**
- Select multiple recent events simultaneously:
- *Hiring in a specific department*
- *Increase in a specific department*
- *Decrease in a specific department*
- *Company award*
- *New product*
- *Employee joined company*
- *Merger and acquisitions*
- *Lawsuit and legal issues*
- *Outages and security breaches*
- *Closing office*
- *New investment*
- *New office*
- *New partnership*
- *Cost cutting*
- *New funding round*
- *Award*
- *IPO announcement*
- Identify companies going through strategic shifts or growth phases
- Prioritize outreach based on timely, contextual triggers
- Filter by last occurrence : 30, 60, or 90 days
**Company revenue:**
- Set minimum and maximum revenue in millions
- Target companies within specific revenue ranges
- Align with your solution's typical customer spend capacity
**Topics recently searched:**
- Select specific topics or keywords recently searched by target companies
- Identify businesses actively researching solutions in your space
- Prioritize outreach based on real-time intent signals to reach prospects at the right moment in their buying journey
**Company tech stack:**
- Select specific technologies used by target companies (CRM, marketing tools, sales tools, infrastructure, etc.)
- Filter companies based on their current tech stack to identify integration opportunities or competitive displacement
- Target businesses already familiar with similar solutions to reduce onboarding friction

### Advanced keyword targeting
**Keywords in website:**
- Enter specific keywords to target companies whose website content matches your criteria
- Identify businesses operating in niche industries or verticals based on their own messaging
- Reach companies that explicitly address topics relevant to your solution on their public pages
## 3. Visualize your results
**Click "PREVIEW COMPANIES"** to see a sample of your search results.
1. **Review the preview data:**
- Company names
- Company website
- Company location
2. **Check the results summary:**
- Total number of matches
- Quality of matches against your ICP
- Distribution across industries and business models
3. **Refine filters if needed:**
- Adjust keyword combinations based on company descriptions
- Modify industry selections for better targeting
- Update size or revenue ranges based on company profiles
- Fine-tune company events for ideal timing
**Note:** ensure the preview shows **relevant companies before importing**. Poor preview results indicate filters need adjustment

## 4. Click on "Load all companies to a table" to create a new table
**Review your final filter settings** one more time
1. **Click "Load all companies to a table"** to export the full search
2. **Monitor the import progress:**
- Progress indicator shows "Importing: X/10,000"
- Percentage completion display
- Real-time status updates
3. **Wait for completion:**
- You can navigate away during processing
**Note:** the system automatically stops at **10,000 results** even if more matches exist. Use more specific filters if you hit this limit and want different prospects

## 5. See your results
**Click on "Access results"** to view your new company table:

You can now start enriching!
---
## Find Companies (Linkedin)
Source: https://docs.airscale.io/docs/find-companies-linkedin.md
Description: Use Airscale’s real-time LinkedIn scraping module to discover target companies based on size, industry, location, and other firmographic criteria. This powerful add-on continuously extracts fresh company data from LinkedIn, helping you build accurate prospecting lists for account-based sales and market research.
**Note:**
- You can import up to **1,000 companies** per search
- Large searches may take several minutes to complete
- Use specific filters to get the most relevant companies within the limit
## 0. Prerequisites
- An active Airscale account with remaining credits
- Clear understanding of your ideal customer profile (ICP)
- Specific criteria for your target companies (industry, size, location, etc.)
## 1. Click on "Find Companies (LinkedIn)"
- Log into your **Airscale** dashboard
- **Select "Find companies (LinkedIn)"** from the available modules (look for the LinkedIn logo)

## 2. Apply your search filters
Configure your search criteria using the comprehensive filter system:
### Basic company filters
**Location targeting:**
- **Include country, state, or city:** Enter geographic filters like "United States," "California," or "San Francisco"
- Multiple locations can be added for broader coverage
- Use specific cities for territory-based targeting
**Company industries:**
- Select from dropdown of industry categories
- Multiple industries can be selected
- Focus on industries where your solution has proven success
**Company size:**
- Choose from predefined ranges: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000
- Select multiple ranges for broader targeting
- Consider your product's sweet spot for company size
### Advanced growth and financial filters
**Company size growth:**
- Set minimum and maximum growth percentages
- Target companies experiencing specific growth rates
- Filter for rapidly expanding businesses or stable enterprises
**Company signals:**
- Select from dropdown of buying intent and behavioral signals
- Target companies showing signs of growth, hiring, or technology adoption
- Focus on businesses likely to be in market for your solution
**Company revenue:**
- Set minimum and maximum revenue in millions
- Target companies within specific revenue ranges
- Align with your solution's typical customer spend capacity
### Department-specific filters
**Company department count:**
- Select specific departments (Sales, Marketing, Engineering, etc.)
- Set minimum and maximum employee counts within those departments
- Target companies with mature departments in your focus area
**Company department growth:**
- Choose specific departments experiencing growth
- Set minimum and maximum growth percentages for those departments
- Identify companies actively hiring in relevant areas
**Company followers count:**
- Select a specific range of follower count on LinkedIn
- Target companies with strong brand presence or niche audiences
- Filter by growth stage based on community size
### Advanced keyword targeting
**Keywords filter:** Use sophisticated keyword combinations to find companies with specific business models or strategies.
**Business model examples:**
- `freemium AND self-serve AND PLG` (Product-Led Growth companies)
- `subscription AND SaaS AND upselling` (SaaS businesses)
- `shopify AND DTC AND ecommerce` (Direct-to-consumer brands)
**Go-to-Market strategy examples:**
- `(cold email OR cold call) AND B2B AND outbound` (Outbound sales focus)
- `(ABM OR demand gen) AND enterprise` (Account-based marketing)
**Technology focus examples:**
- `AI AND chatbot AND customer support` (AI customer service)
- `fintech AND KYC AND compliance` (Financial technology)
- `logistics AND warehouse AND last mile` (Supply chain/logistics)
**Sustainability examples:**
- `sustainability AND green energy AND carbon` (Green technology)
**Pro Tip:** you don't need to press enter when typing keyword combinations. Just type the keywords and Boolean operators directly (AND/OR)

## 3. Visualize your results
**Click "PREVIEW COMPANIES"** to see a sample of your search results.
1. **Review the preview data:**
- Company names: check if businesses match your target market
- Industry classifications: verify industry relevance to your solution
- Company descriptions: review business models and focus areas
- LinkedIn profile URLs: validate company authenticity and presence
2. **Check the results summary:**
- Total number of matches
- Quality of matches against your ICP
- Distribution across industries and business models
3. **Refine filters if needed:**
- Adjust keyword combinations based on company descriptions
- Modify industry selections for better targeting
- Update size or revenue ranges based on company profiles
- Fine-tune growth criteria for ideal timing
**Note:** ensure the preview shows **relevant companies before importing**. Poor preview results indicate filters need adjustment

## 4. Click on "Load all companies to a table" to create a new table
**Review your final filter settings** one more time
1. **Click "Load all companies to a table"** to export the full search
2. **Monitor the import progress:**
- Progress indicator shows "Importing: X/1000"
- Percentage completion display
- Real-time status updates
3. **Wait for completion:**
- You can navigate away during processing
**Note:** the system automatically stops at **1,000 results** even if more matches exist. Use more specific filters if you hit this limit and want different prospects

## 5. See your results
**Click on "Access results"** to view your new company table:

You can now start enriching!
---
## Find local businesses with Google Maps
Source: https://docs.airscale.io/docs/google-maps.md
Description: Find local businesses with Google Maps directly in Airscale. Extract names, addresses, phones and emails in one click to fuel your prospecting lists.
**Note:** you can only import **500 local businesses** per search
## 1. Click on "Find local businesses with Google Maps"

## 2. Add the search filters
- **Apply your target filters:** location and business type
- **Optionally**, you can also ask to find the contact information of the businesses. When toggled ON, we will scrape each company’s website and return any available contact details (emails, phone numbers)

## 3. Launch the extraction and access your results

---
## Find companies hiring for specific positions
Source: https://docs.airscale.io/docs/companies-hiring.md
Description: Find companies hiring for specific positions using Airscale. Target the right accounts at the right time and reach out when hiring intent is highest.
**Note:** you can only import up to **1,000 companies** per search
## 1. Click on "Find companies hiring for a specific position"

## 2. Add your search filters
Use the following filters to refine your search:
- **Query:** "Head of Growth", "Data Analyst", etc.
- **Company Headcount:** filter by size to match your ICP (e.g., 11–50, 51–200)
- **Industry:** target relevant industries (e.g., Health, Consumer Services, etc.)
- **Location:** focus on specific countries, regions, or cities
- etc.

## 3. Preview your search results

## 4. Launch the extraction and access your results
Click on **"Load companies to a table"** to begin the scraping process and load the companies to an Airscale table

---
## Import a file as a CSV
Source: https://docs.airscale.io/docs/import-csv.md
Description: Import a CSV file into Airscale in seconds. Enrich, clean and push your contact lists directly into your CRM or sales workflows - no manual work.
**Note:** you can only import a maximum of **10,000 rows**
## 1. Click on "Import as a CSV"

## 2. Select the file to import
Before importing your file, ensure:
1. **Your file is a CSV file**
2. **Your file does not contain more than 10,000 rows**
## 3. Map your columns to Airscale columns
- Map the column names of your CSV file to Airscale's columns
- Alternatively, you can use **custom fields** if Airscale does not have a pre-built column for your data

## 4. Click on "Upload Now" to create a table

---
## Find phone numbers
Source: https://docs.airscale.io/docs/phone-numbers.md
Description: Find verified phone numbers via Airscale's waterfall enrichment
**Note:**
- The required input to find a phone number is a **LinkedIn profile URL**
- If you don't have the LinkedIn profile URL but have a list with first name, last name, and company name, you can use Airscale’s **"Find a LinkedIn profile URL"** or **"Use AI"** enrichments first to retrieve the LinkedIn profile URL
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results
Once the enrichment is complete, you can see which provider returned the phone number by clicking the icon on the right

If you notice that the phone number returned is invalid, you can click on **"Continue enrichment"**
The workflow will restart from the provider that returned the first phone number to check whether another provider can find a different one. Any phone numbers found after the first one are **free of charge**
---
## Find professional emails
Source: https://docs.airscale.io/docs/professional-emails.md
Description: Find verified emails via Airscale's waterfall enrichment
**Note:** the required input to find an email is the combination of:
- First name
- Last name
- Company name **or** company domain
**OR**
- People LinkedIn URL
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results
Once the enrichment is complete, you can see which provider returned the verified email by clicking on **"Details"**
**Note:**
**Email status indicators:**
- **Deliverable:** email exists and is safe to contact
- **Not found:** no email address could be found
- **Risky:** email found but deliverability uncertain (often catch-all domains)
- **Found:** email address discovered and verified
**Deliverability classifications:**
- **Deliverable:** high confidence — safe for outreach campaigns
- **Risky (Catch-All):** use with caution: this domain accepts all emails, but the specific address may be invalid
- **Not Deliverable:** remove from campaigns to protect sender reputation

---
## Find personal emails
Source: https://docs.airscale.io/docs/personal-emails.md
Description: Find personal emails via Airscale's waterfall enrichment
**Note:**
- The required input to find a personal email is a **LinkedIn profile URL**
- If you don't have the LinkedIn profile URL but have a list with first name, last name, and company name, you can use Airscale’s **"Find a LinkedIn profile URL"** or **"Use AI"** enrichments first to retrieve the LinkedIn profile URL
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

---
## Verify if an email is deliverable
Source: https://docs.airscale.io/docs/verify-email.md
Description: Verify email deliverability in real time with Airscale. Reduce bounce rates, protect your sender score and reach more prospects in the inbox.
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results
**Deliverability classifications:**
- **Deliverable:** high confidence — safe for outreach campaigns
- **Risky (Catch-All):** use with caution — this domain accepts all emails, but the specific address may be invalid
- **Not Deliverable:** remove from campaigns to protect sender reputation

---
## Enrich people profile from LinkedIn
Source: https://docs.airscale.io/docs/enrich-people-linkedin.md
Description: Enrich people profiles from LinkedIn with Airscale. Get verified emails, phone numbers and job details from any LinkedIn profile - instantly.
**Note**: the required input to enrich a profile is a **LinkedIn profile URL**
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

## 5. Add columns for any data points you want about the profile

---
## Enrich company profile from LinkedIn
Source: https://docs.airscale.io/docs/enrich-company-linkedin.md
Description: Enrich company profiles from LinkedIn with Airscale. Extract firmographics, headcount, industry and decision-makers data to power your outbound.
**Note**: the required input to enrich a company is a **LinkedIn company URL**
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

## 5. Add columns for any data points you want about the company

---
## Fetch company insights
Source: https://docs.airscale.io/docs/fetch-company-insights.md
Description: Find some company insights from Linkedin : description, headcount growth (overall and by function), hiring trends, job openings, etc.
**Note**: the required input to fetch company insights is a **LinkedIn company URL**
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

## 5. Add columns for any data points you want about the company

---
## Find current job openings on LinkedIn
Source: https://docs.airscale.io/docs/job-openings-linkedin.md
Description: Find current job openings on LinkedIn with Airscale. Identify hiring companies, target the right contacts and time your outreach with buying intent.
**Note**: the required input to enrich a company with open roles is a **LinkedIn company URL**
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

## 5. Add columns for any data points about the jobs retrieved

---
## Find the latest posts of a company / person
Source: https://docs.airscale.io/docs/linkedin-posts-scraper.md
Description: Retrieve the latest posts published by a company or an individual on LinkedIn
**Note**: the required input to retrieve the latest posts written is a **LinkedIn URL (people or company)**
## 1. Select the enrichment (People or company posts)

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

## 5. Add columns for any data points about the posts retrieved

---
## Find LinkedIn profile data from a phone number
Source: https://docs.airscale.io/docs/reverse-phone.md
Description: Retrieve a LinkedIn profile URL and data from any phone number using Airscale's Reverse Phone enrichment
**Note**: the required input to leverage this enrichment is a **phone number**
## 1. Select the enrichment

## 2. Choose which rows to enrich

## 3. Select the right input

## 4. Run the workflow

## 5. Access the results

## 6. Add columns for any data points you want about the profile

---
## Find LinkedIn profile data from an email
Source: https://docs.airscale.io/docs/reverse-email.md
Description: Retrieve a LinkedIn profile URL and data from any email using Airscale's Reverse Email enrichment
**Note**: the required input to leverage this enrichment is an email
## 1. Select the enrichment

## 2. Choose which rows to enrich

## 3. Select the right input

## 4. Run the workflow

## 5. Access the results

## 6. Add columns for any data points you want about the profile

---
## AI custom prompts
Source: https://docs.airscale.io/docs/ai-custom-prompts.md
Description: Run AI with the best LLMs using custom prompts
## 1. Select the enrichment called "Use AI"

## 2. Select the rows to enrich

## 3. Select the mode (web access vs non web access)

**Note**:
- **No web access:** Best to edit, format, or clean your data. Use this mode when your prompt only needs data already existing in your table and doesn’t need to browse the web to provide the expected output
- **Web access:** Use this mode if you want to find data on the web and want AI to have web browsing capabilities. Useful to research data online about a company or a prospect by visiting website pages (*this mode will select Airsearch 1.0 as the LLM to use)*
## 4. Select an LLM

## 5. Write or import your prompt

**Note**: to use dynamically the content of a column existing in your table, **use the key "/" on your keyboard**
## 6. Run the workflow
When the workflow is launched, **a new column will be created with the output**

---
## AI agent (AirSearch)
Source: https://docs.airscale.io/docs/ai-agent-airsearch.md
Description: Use Airscale’s AI agent to browse the web and find any information about a company or a prospect
## 1. Select the enrichment called "Use AI"

## 2. Select the rows to enrich

## 3. Select the mode "Web access"

**Note**: selecting **“Web access”** mode will automatically choose **“Airsearch 1.0”**, the model required for web access, including browsing and scraping capabilities
## 4. Write or import your prompt

**Note**: to dynamically use the content of an existing column in your table, **press the “/” key on your keyboard**
## 5. Run the workflow

## 6. Access the results
**Note**: after launching the enrichment, **two columns will be automatically created** on the right side of the spreadsheet
**In the first column that is created,** you’ll find details about the AI’s reasoning behind the answer. If you click on **“Click to expand,”** you can view the full enrichment details
The enrichment will return 4 keys:
- **Response**: the output for your prompt
- **Reasoning**: the steps taken by the agent to return the output
- **Sources**: the web pages visited in order to gather the data to return the output
- **Confidence score**: a score of confidence to understand how reliable and accurate the output is


**In the second column**, you’ll see the result with the output requested in your promp :

---
## Create custom Google searches
Source: https://docs.airscale.io/docs/google-searches.md
Description: Create custom Google searches in Airscale. Build targeted queries to find any prospect or company and extract results straight into your lists.
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Create your SERP query

**Note**: to dynamically use the content of an existing column in your table, **press the “/” key on your keyboard**
## 4. Run the workflow

## 5. Access the results
**A new column is created automatically.** If you click on **“Click to expand”** you can access the detail of the enrichment

## 6. Add columns for any data points retrieved

---
## Find a LinkedIn profile URL
Source: https://docs.airscale.io/docs/linkedin-profile-url.md
Description: Find any LinkedIn profile URL with Airscale. Locate prospects from their name and company to fuel your outreach and enrichment workflows.
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

---
## Find a LinkedIn company URL
Source: https://docs.airscale.io/docs/linkedin-company-url.md
Description: Find any LinkedIn company URL with Airscale. Identify company pages to enrich accounts and target decision-makers faster.
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

---
## Find a Linkedin company URL from a domain
Source: https://docs.airscale.io/docs/linkedin-company-url-from-a-domain.md
Description: Find a LinkedIn company URL from a domain with Airscale. Turn any website into a LinkedIn company page instantly - no manual search needed.
**Note**: the required input to fetch company insights is a **company domain**
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

---
## Fetch a company's Meta ads
Source: https://docs.airscale.io/docs/meta-ads.md
Description: Retrieve all active Meta ads running for any company directly from Airscale's Meta Ads enrichment
**Note**: the required input to leverage this enrichment is a **company domain**
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Select the correct input

## 4. Run the workflow

## 5. Access the results
**A new column is created automatically with the number of active ads.** If you click on **“Click to expand”** you can access the detail of the enrichment

## 6. Add columns for any data points retrieved

---
## Fetch a company's Google ads
Source: https://docs.airscale.io/docs/google-ads.md
Description: Retrieve all active Google ads running for any company directly from Airscale's Google Ads enrichment
**Note**: the required input to leverage this enrichment is a **company domain**
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Select the correct input

## 4. Run the workflow

## 5. Access the results
**A new column is created automatically with the number of active ads.** If you click on **“Click to expand”** you can access the detail of the enrichment

## 6. Add columns for any data points retrieved

---
## Find a company domain
Source: https://docs.airscale.io/docs/company-domain.md
Description: Find any company domain with Airscale. Turn a company name into a verified website URL to enrich contacts and launch outbound campaigns faster.
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

---
## Find company technologies
Source: https://docs.airscale.io/docs/company-technologies.md
Description: Find company technologies used by any account with Airscale. Identify tech stacks to qualify prospects, personalize outreach and prioritize the right leads.
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

---
## Find company funding data
Source: https://docs.airscale.io/docs/funding-data.md
Description: Find company funding data with Airscale. Access funding rounds and investors to target high-growth accounts and time your outreach perfectly.
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results
**A new column is created automatically.** If you click on "**Click to expand"** you can access the detail of the enrichment

## 5. Add columns for any data points retrieved

---
## Extract website content with Zenrows
Source: https://docs.airscale.io/docs/website-content.md
Description: Scrape and extract the text content from any website using Airscale's Zenrows integration. This powerful enrichment tool converts websites into LLM-ready markdown data, perfect for research, competitor analysis, and content gathering from your prospects' company websites
## 1. Select the enrichment


## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results
Once the enrichment completes:
1. **Review the new "Website text content" column** added to your table
2. **Analyze the scraped data** for research and personalization opportunities


---
## Fetch business intent topics
Source: https://docs.airscale.io/docs/fetch-business-intent-topics.md
Description: Find what topics a company’s employees are researching from its LinkedIn URL
**Note**: the required input to fetch company insights is a **LinkedIn company URL**
## 1. Select the enrichment

## 2. Select rows & the correct input
Select the rows you would like to include in the enrichment and select the **"Company Linkedin URL"** column as an input.

## 3. Enter the business topics
Type the business topics you would like to inquire and make sure to **press** **Enter** ↩︎ after typing so the suggestions appear.
Click on **"Add +"** to select the topics.

## 4. Run the workflow
As soon as you're done selecting the business topics, you can run the workflow.

## 5. Access the results
Acess you results once the enrichment has finished running. Click on **"Click to expand"** for more details about the search and add any field as a column by clicking on **"Add as a column".**

---
## Find company website traffic data
Source: https://docs.airscale.io/docs/website-traffic.md
Description: Retrieve the website traffic count, evolution, source using Similarweb. The required input is a company domain
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results
**A new column is created automatically**. If you click on "**Click to expand**" you can access the detail of the enrichment

## 5. Add columns for any data points retrieved

---
## Lookup contacts in Hubspot
Source: https://docs.airscale.io/docs/lookup-hubspot.md
Description: Check if a contact already exists in your CRM
## 1. Select the enrichment

## 2. Select the rows to enrich

## 3. Run the workflow

## 4. Access the results

---
## Export your data as CSV
Source: https://docs.airscale.io/docs/export-csv.md
Description: Export your prospect lists from Airscale as CSV files for use in email marketing tools, CRMs, or further analysis. This feature lets you download all enriched data while giving you full control over which contacts and columns to include
##### When to export as CSV
- To launch **email campaigns** in external tools
- To **import data into CRMs** not directly integrated with Airscale
- To **analyze data** in Excel, Google Sheets, or analytics tools
- To **keep local backups** of your prospect data
- To **share prospect lists** across teams and departments
## 1. Click on "Export"

## 2. Select "Download as csv"

## 3. Select the rows to extract

## 4. Select a file extension
Note:
**CSV (recommended):**
- Universal compatibility with most email tools and CRMs
- Smaller file size for large datasets
- Easy to open in Excel, Google Sheets, or text editors
- Best for automated imports and integrations
**XLSX:**
- Excel-native format with formatting preservation
- Better for manual data manipulation
- Supports advanced Excel features if needed
- Slightly larger file size

## 5. Download your export

---
## Transfer your data to another table
Source: https://docs.airscale.io/docs/transfer-another-table.md
Description: Move prospects between tables within Airscale to organize your data, create targeted segments, or consolidate lists from multiple sources. This feature helps you keep your prospect database clean and well-organized for different campaigns and initiatives
##### When to export to another table
- Creating campaign segments from a master prospect list
- Organizing prospects by persona (decision makers vs. influencers)
- Separating by geography for territory-based sales teams
- Consolidating data from multiple import sources
- Creating backup tables before running bulk enrichments
- Segmenting by deliverability status for different outreach strategies
## 0. Prerequisites
- A source table containing prospect data in Airscale
- An existing destination table
## 1. Click on "Export"

## 2. Select "Export to another table"

## 3. Select the rows to export

## 4. Select the table you want to export your data to

## 5. Launch your export

---
## Export your leads to HubSpot
Source: https://docs.airscale.io/docs/export-hubspot.md
Description: Export your prospects directly from Airscale to HubSpot CRM to streamline your sales pipeline. This integration pushes enriched prospect data directly into your HubSpot database, allowing you to manage leads, track interactions, and nurture prospects through your established sales processes
## 0. Prerequisites
- An active HubSpot account with CRM access
- A prospect table in Airscale with email addresses
- HubSpot integration permissions (available on most HubSpot plans)
- Understanding of your HubSpot lead lifecycle stages and contact ownership structure
## 1. Click on "Export"

## 2. Select "Create or update a contact in HubSpot"

## 3. Select the rows to export

## 4. Connect your Hubspot account
If this is your first time connecting to HubSpot:
1. **Click "Connect your HubSpot account"** in the workflow panel
2. **You'll be redirected to HubSpot's authorization page**
3. **Log into your HubSpot account** if not already logged in
4. **Grant permissions** for Airscale to access your HubSpot CRM
5. **Return to Airscale** once authorization is complete
**HubSpot integration permissions:**
- **Contact creation and updates** for lead management
- **Company association** for account-based tracking
- **Property access** for data mapping and enrichment
- **Pipeline visibility** for lifecycle stage management
**Note** : HubSpot uses OAuth authentication, so you don't need to share passwords or API keys directly




## 5. Select a contact owner and lead lifecycle stage

## 6. Launch your export

---
## Export your leads to Instantly
Source: https://docs.airscale.io/docs/export-instantly.md
Description: Export your prospects directly from Airscale to Instantly campaigns for automated email outreach. This integration streamlines your workflow by pushing enriched prospect data directly into your email sequences without manual uploads or CSV exports.
## 0. Prerequisites
- An active Instantly account with email campaigns set up
- A prospect table in Airscale with enriched email addresses
- Instantly API access (available on most Instantly plans)
## 1. Click on "Export"

## 2. Select "Add a contact to a campaign in Instantly"

## 3. Select the rows to export

## 4. Connect Your Instantly Account
If this is your first time connecting to Instantly:
1. **Click "Connect your Instantly account"** in the workflow panel
2. **Note that "No account connected"** appears initially
3. **You'll need to create an API key** in your Instantly account first

## 5. Create API Key in Instantly Settings
**Log into your Instantly account**
1. **Click on "Settings"** (usually in the left sidebar or user menu)
2. **Navigate to "Integrations"** tab
3. **Select "API Keys"** from the available options


## 6. Create your API key
**Click "Create API Key"** button
1. **Name your API key:** Enter a descriptive name like "Export Airscale" or "Airscale Integration"
2. **Select scopes:** Choose "all:all" for full access (required for campaign management)
3. **Click "Create"** to generate your API key


## 7. Copy your API key
**Copy the generated API key** from the success popup
1. **Store it securely** - you won't be able to see it again after closing the popup
2. **The API key will be a long string** of characters (similar to: "ZWZIYTA4MTktZmZmYy0DNjFmLTk5ZTEtMWJmOWEyNzY4NTFiOmpzWlJYmlb3p...")
**Warning** : copy the API key **immediately** as Instantly won't show it again for security reasons

## 8. Paste API key in Airscale and connect
**Return to Airscale** and the export workflow
1. **Paste your Instantly API key** in the provided field
2. **Click "Connect"** to establish the integration
3. **Wait for confirmation** that the connection was successful

## 9. Select a campaign

## 10. Launch your export
Configure how Airscale data maps to Instantly fields:
- **Email address** ↔ Instantly email field
- **First name** ↔ Instantly first name field
- **Last name** ↔ Instantly last name field
- **Phone** ↔ Instantly phone field
- **Company Name** ↔ Instantly company name field
- **Website** ↔ Instantly website field
- **Additional custom fields** as needed

---
## Export your leads to Smartlead
Source: https://docs.airscale.io/docs/export-smartlead.md
Description: Export your prospects directly from Airscale to Smartlead campaigns for automated email outreach. This integration streamlines your workflow by pushing enriched prospect data directly into your email sequences without manual uploads or CSV exports.
## 0. Prerequisites
- An active Smartlead account with email campaigns set up
- A prospect table in Airscale with enriched email addresses
- Smartlead API access (available on most Smartlead plans)
## 1. Click on "Export"

## 2. Select "Add a contact to a campaign in Smartlead"

## 3. Select the rows to export

## 4. Connect your Smartlead account
If this is your first time connecting to SmartLead:
1. **Click "Connect your Smartlead account"** in the workflow panel
2. **Note that "No account connected"** appears initially
3. **You'll need to create an API key** in your Smartlead account first

## 5. Create API key in Smartlead settings
**Log into your Smartlead account:**
1. **Click on "Settings"** (usually in the top right corner)
2. **Navigate to the "Smartlead API Key"** section
3. **Copy the generated API key** from Smartlead


## 6. Paste API key in Airscale and connect
**Return to Airscale** and the export workflow
1. **Paste your Smartlead API key** in the provided field
2. **Click "Connect"** to establish the integration
3. **Wait for confirmation** that the connection was successful

## 7. Select a campaign

## 8. Launch your export
Configure how Airscale data maps to SmartLead fields:
- **Email address** ↔ Smartlead email field
- **First name** ↔ Smartlead first name field
- **Last name** ↔ Smartlead last name field
- **Phone** ↔ Smartlead phone field
- **Company Name** ↔ Smartlead company name field
- **Website** ↔ Smartlead website field
- **Linkedin Profile URL** ↔ Smartlead linkedin profile field
- **Additional custom fields** as needed

---
## Export your leads to Lemlist
Source: https://docs.airscale.io/docs/export-lemlist.md
Description: Export your prospects directly from Airscale to Lemlist campaigns for automated email outreach. This integration streamlines your workflow by pushing enriched prospect data directly into your email sequences without manual uploads or CSV exports
## 0. Prerequisites
- An active Lemlist account with email campaigns set up
- A prospect table in Airscale with enriched email addresses
- Lemlist API access (available on most Lemlist plans)
## 1. Click on "Export"

## 2. Select "Add a contact to a campaign in Lemlist"

## 3. Select the rows to export

## 4. Connect your Lemlist account
If this is your first time connecting to Lemlist:
1. **Click "Connect your Lemlist account"** in the workflow panel
2. **Note that "No account connected"** appears initially
3. **You'll need to create an API key** in your Lemlist account first

## 5. Create API Key in Lemlist settings
**Log into your Lemlist account:**
1. **Click on "Settings"**
2. **Navigate to the "Lemlist API Key"** section
3. **Copy the generated API key** from Lemlist




## 6. Paste API key in Lemlist and connect
**Return to Airscale** and the export workflow
1. **Paste your Lemlist API key** in the provided field
2. **Click "Connect"** to establish the integration
3. **Wait for confirmation** that the connection was successful

## 7. Select a campaign

## 8. Launch your export
Configure how Airscale data maps to Lemlist fields:
- **Email address** ↔ Lemlist email field
- **First name** ↔ Lemlist first name field
- **Last name** ↔ Lemlist last name field
- **Phone** ↔ Lemlist phone field
- **Company Name** ↔ Lemlist company name field
- **Linkedin Profile URL** ↔ Lemlist linkedin profile field
- **Additional custom fields** as needed

---
## Import contacts from Hubspot
Source: https://docs.airscale.io/docs/import-hubspot.md
Description: Pull contacts from Hubspot lists
**Note:**
- You can only export **10,000 contacts** at once
## 0. Prerequisites
- An active HubSpot account with CRM access
- HubSpot integration permissions (available on most HubSpot plans)
## 1. Click on "Import contacts from Hubspot"

## 2. Connect your Hubspot account to Airscale
If this is your first time connecting to HubSpot:
1. **Click "Connect your HubSpot account"** in the workflow panel
2. **You'll be redirected to HubSpot's authorization page**
3. **Log into your HubSpot account** if not already logged in
4. **Grant permissions** for Airscale to access your HubSpot CRM
5. **Return to Airscale** once authorization is complete
**HubSpot integration permissions:**
- **Contact creation and updates** for lead management
- **Company association** for account-based tracking
- **Property access** for data mapping and enrichment
- **Pipeline visibility** for lifecycle stage management
**Note** : HubSpot uses OAuth authentication, so you don't need to share passwords or API keys directly





## 3. Select a list from your Hubspot account

## 4. Click on "Import" to create a table

## 5. You can now enrich your table

---
## Airscale for HubSpot app
Source: https://docs.airscale.io/docs/hubspot-app.md
Description: The complete step-by-step guide to install and use the Airscale enrichment app on your HubSpot account.
**What you'll be able to do after the setup:**
- Enrich any HubSpot contact with a verified email and phone number in one click
- Access the enrichment directly from the contact card sidebar
- Automatically update standard HubSpot properties (email, phone)
- Keep a history of enrichment results on each contact
## 0. Prerequisites
- A HubSpot account (any paid plan - Sales Hub Starter or above)
- HubSpot admin rights (to install the app)
- An Airscale account with an active API key - [sign up here](https://app.airscale.io/) if you don't have one
## 1. Install the Airscale app on your HubSpot account
1. Click the button below to launch the secure OAuth installation flow.
[Click here to install Airscale for Hubspot](https://airscale-hubspot.mathis-0d8.workers.dev/oauth/install)
2. On the landing page, click **Connect HubSpot**. If your HubSpot account is hosted in the EU, click the EU link instead.

3. **Select your HubSpot account: y**ou'll be redirected to HubSpot. Select the HubSpot account where you want to install Airscale.

4. Review and approve the permissions requested (read/write contacts and companies) and click **Connect app**.

**✔️ Installation successful.** At this point, Airscale has automatically created a **Airscale Enrichment** property group on your contact records and added the custom properties needed (`airscale_found_email`, `airscale_found_phone`, `airscale_enrichment_date`, `airscale_email_status`).
## 2. Add your Airscale API key
1. Open any contact record in HubSpot : go to Contacts → select a contact.
2. Locate the Airscale Enrichment card : in the right sidebar, scroll down until you see the **Airscale Enrichment** card. *If you don't see it, go to step 3 to pin it properly.*

3. Open the Settings modal : inside the Airscale card, click **Actions → Settings**.

4. A modal opens : **paste your Airscale API key into the input field**. You can find your API key at [app.airscale.io/dashboard?page=settings&tab=key](https://app.airscale.io/dashboard?page=settings&tab=key).

5. Click **Save API Key**. You'll see a green confirmation: *"API key saved successfully."* Close the modal. Setup is complete.
*To remove or replace your API key later: open the Settings modal again, then click Remove API Key (you'll have to click twice within 5 seconds to confirm).*
## 3. Pin the Airscale card to the top (recommended)
By default, HubSpot may place the Airscale card at the bottom of the sidebar. For faster access, pin it to the top.
1. Open any contact record : navigate to contacts and open any contact.
2. At the top of the contact record, click **Customize** (or **Personnaliser** in French). No need to scroll, the button is in the top nav bar.

3. You'll be redirected to a page listing the available views. Click on the **default view** (or the specific view you want to customize).
4. In the sidebar customization panel, locate the **Airscale Enrichment** card and drag it to the top (or just below "About this contact").

5. Click **Save** at the top right, then refresh the contact page. The Airscale card is now pinned at the top.
***Tip:** This layout applies to all contacts for your user. If you want to apply it team-wide, ask your HubSpot admin to update the default contact record view.*
## 4. Run your first enrichment
1. Open a contact with sufficient data
Make sure the contact has at least one of the following:
- **First name + Last name + Company name** (or company domain), OR
- A **LinkedIn URL** in the field "URL LinkedIn"
2. In the Airscale card, click **Actions**. You have four options:
| **Action** | **What it does** |
| --- | --- |
| **Enrich all** | Finds both email + phone (recommended default) |
| **Find Email** | Finds verified email only |
| **Find Phone** | Finds mobile phone only (requires LinkedIn URL) |
| **Settings** | Opens the API key configuration modal |

3. **Click Enrich All** (a modal opens with a spinner: *"Enriching contact..."*).

4. After a few seconds, you'll see:
- ✅ **Enrichment complete!** meaning the enrichment request was successfully launched
- ❌ An error message if something went wrong (e.g. missing input, API key not configured)

5. Refresh to see the new data : close the modal and press **Cmd+R** (Mac) or **Ctrl+R** (Windows) to refresh the page. The new data appears:
- In the Airscale card: *Found email*, *Found phone*, *Status*, *Enrichment date*
- In the left sidebar: the standard HubSpot **Email** and **Phone** fields are automatically filled if they were empty

#### How the data is written in Hubspot
When Airscale finds an email or phone, the app writes:
**Always, to Airscale custom properties**
- `airscale_found_email`
- `airscale_found_phone`
- `airscale_email_status` (Valid / Risky / Invalid)
- `airscale_enrichment_date`
**Only if empty, to standard HubSpot properties**
- `email` (Email)
- `phone` (Phone number — "Numéro de téléphone")
This means your existing data is **never overwritten**. To force an update of the standard field, use **Actions → Override Email** or **Override Phone** once enrichment has run.
## 5. Automate enrichment with Workflows
Once the Airscale app is installed and your API key is configured, you can automate enrichment at scale using HubSpot Workflows. Instead of enriching contacts one by one, you can set up workflows that automatically enrich contacts based on triggers you define.
**Requirement:** HubSpot Workflows with custom actions require **Sales Hub Pro/Enterprise**, **Marketing Hub Pro/Enterprise**, or **Operations Hub Pro/Enterprise**. This feature is not available on Starter plans.
#### Available workflow actions
Airscale adds three actions to the HubSpot workflow builder:
| **Action** | **What it does** |
| --- | --- |
| **Airscale - Enrich All** | Finds both email + phone (recommended) |
| **Airscale - Find Email** | Finds verified email only |
| **Airscale - Find Phone** | Finds mobile phone only (requires LinkedIn URL on the contact) |
#### How to create an enrichment workflow
1. Create a new workflow: go to **Automation → Workflows → Create workflow**. Select **Contact-based** as the object type.
2. Choose a trigger: select the condition that will start the enrichment. Common examples:
- **Contact is added to a list**: enrich a batch of imported contacts
- **Contact fills out a form**: enrich inbound leads automatically
- **Contact property changes**: e.g., when a LinkedIn URL is added
- **Manual trigger**: enrich contacts on demand by selecting them manually
3. Add the Airscale action: click the **+** button to add an action. In the search bar, type **"Airscale"**. You'll see the three Airscale actions under **Integrated apps → Airscale Data Enrichment**. Select the one you want (we recommend **"Airscale - Enrich All"** for most use cases).
4. Activate the workflow: click **Review and activate** in the top right corner. Review the settings and click **Activate**. Contacts matching your trigger will now be automatically enriched.
#### Example use cases
| **Use case** | **Trigger** | **Action** |
| --- | --- | --- |
| Enrich all new leads from a form | Contact fills out form "Contact Us" | Airscale - Enrich All |
| Enrich imported contact lists | Contact is added to list "New Import" | Airscale - Enrich All |
| Find phone when LinkedIn is added | LinkedIn URL becomes known | Airscale - Find Phone |
| Enrich contacts entering a deal stage | Associated deal moves to "Discovery" | Airscale - Find Email |
**Credit usage:** Each enrichment in a workflow uses credits from your Airscale account, just like manual enrichment. If your credits run out, the workflow action will return an error for remaining contacts but will not block the rest of the workflow. Monitor your balance at [app.airscale.io](https://app.airscale.io/).
## Troubleshooting
#### The Airscale card doesn't appear on the contact page
- On the contact record, click **Customize** in the top nav → select your view → make sure "Airscale Enrichment" is enabled.
- If it's not in the list, the install may have failed. Reinstall via the install link.
#### "API key not configured" error when enriching
- Open the Airscale card → **Actions → Settings** → paste a valid API key from [app.airscale.io/dashboard?page=settings&tab=key](https://app.airscale.io/dashboard?page=settings&tab=key).
#### "Not enough data to find email" error
- The contact is missing required input. Make sure one of the following is filled:
- **First name + Last name + (Company name OR company domain)**
- A **LinkedIn URL** in `hs_linkedin_url` or `linkedin_url`
- Tip: associate a company to the contact in HubSpot. Airscale will use the associated company's domain automatically.
#### "LinkedIn URL is required for phone enrichment"
- Airscale's phone enrichment requires a LinkedIn profile URL to work. Add it to the contact in the **URL LinkedIn** field.
#### The enriched data doesn't show up
- Make sure you refreshed the page (**Cmd+R / Ctrl+R**) after closing the enrichment modal. HubSpot doesn't auto-refresh the sidebar.
#### I don't have enough Airscale credits
- Check your balance at [app.airscale.io](https://app.airscale.io/). Top up via your account settings or contact us.
---
## Add users & switch workspaces
Source: https://docs.airscale.io/docs/users-workspaces.md
Description: Invite new users to your workspace and seamlessly switch between different workspaces based on your needs
## 1. Click on settings

## 2. Click on Workspace & Team
You also have the option to change the workspace name if you wish. By default, the name will be the username of the person who created the account

## 3. Click on "Invite" & "Send invitation"
You can add as many users as you like, it won’t impact the license price, as we do not charge per user (credit-based pricing model)
Only the workspace admin can invite and remove users


**Important**: each invited user will receive an email with a link to access the workspace, whether they already have an account or not
## 4. Switch workspaces to access credits
As soon as a user has been invited to a workspace and clicks the link received by email, they will have access to both their default workspace (created under their name) and the workspace they were invited to
To access the tables and credits of the new workspace, click on the logo in the bottom-left corner of the platform, which displays the first initial of the user’s name:


Whenever you switch workspaces, the credit balance will update to reflect the new workspace. You will also gain access to the tables created in that workspace, and any enrichments launched there will be deducted from the credit balance of the currently active workspace
---
## Deduplicate leads between tables
Source: https://docs.airscale.io/docs/deduplicate-leads-tables.md
Description: Identify and merge duplicate leads between your tables to keep your database clean and accurate
## 0. Prerequisites
- You must have tables with contacts or companies
- Each lead (contact or company) must have a LinkedIn profile URL to be identified, as this is the unique identifier that is used
## 1. Click on "Dedupe" at the bottom left of your table
Launch this workflow and all rows in the current table will be checked for potential duplicates across all your other existing tables. If duplicates are found, the corresponding row in the table will be deleted


It may take a few minutes to run entirely if the current table is large. Once the workflow is launched, you can safely close the pop-up as the workflow will be running in the background
**Note**: the dedupe workflow runs within the same object type, contacts with contacts, and companies with companies only
---
## Filter tables
Source: https://docs.airscale.io/docs/filer-tables.md
Description: Apply filters to your tables to quickly find and analyze the data that matters most
## 1. Click on "Filter"

You will then have the option to select one or several columns from your table:

Once a column is selected, you will have several filtering options available (depending on whether it’s a text field, a numeric field, or an email field):
***Example of filtering emails:***

***Example of filtering text field :***

***Example of filtering a numeric field :***

**Note:** the filters are case sensitive. A filter like "Job title" contains "Ceo" will not return the rows with "CEO" as a job title
You also have the option to apply multiple filters at the same time:

And the option to replace the “AND” field with “OR” by clicking the small arrow on the right:

Once you’ve applied your filters, all you need to do is click on “Apply filters” and the table will update
**Note**: the more rows the table contains, the longer it will take to load and apply the filters
## 2. Another option: use the search bar to filter
You also have the option to use the search bar to look for a specific item within your table (this can be a first name, an email, a numeric field, or anything else):

---
## Transfer column content
Source: https://docs.airscale.io/docs/transfer-content.md
Description: Move or copy data from one column to another to reorganize or update your records efficiently
## 1. Click on the settings of your column

## 2. Click on "Transfer data to another column"

## 3. Select the column to which you want to transfer the data

## 4. Choose the number of rows you want to transfer

**Note:** clicking "Transfer Data" copies the data to the new column without removing it from the original one
---
## API Overview
Source: https://docs.airscale.io/api-reference/api-overview.md
Description: Authenticate with Airscale and make your first API request.
Airscale is the documentation hub for Airscale. Use the Airscale API to search for people and companies and enrich contact data from your application.
Check your workspace's remaining credits with a request that has no body.
Start with people search, then explore company search and enrichment endpoints.
## Make your first request
In Airscale, open **Settings → API key** and create a key for your server-side application.
Store the key in an environment variable and send it as a Bearer token on every request.
```bash
export AIRSCALE_API_KEY="YOUR_API_KEY"
```
Call `POST https://api.airscale.io/v1/credits` with no body.
```bash cURL
curl --request POST \
--url https://api.airscale.io/v1/credits \
--header "Authorization: Bearer $AIRSCALE_API_KEY"
```
A successful request returns the remaining workspace balance as a number:
```json
{
"status": "success",
"response": {
"credits": 1200
}
}
```
## Popular endpoints
Search for people that match professional filters.
Discover companies that match firmographic filters.
Find a professional email address from a person's details.
Run an Airsearch request from your application.
Track up to 10,000 LinkedIn profiles per monitor and receive employer-change events.
Watch up to 10,000 companies, or the whole market, for people who start a matching role.
Follow LinkedIn company pages and profiles and receive the people who engage with their posts.
Before you build a production integration, review [Authentication](/api-reference/authentication) and [Rate limits](/api-reference/rate-limits).
---
## Authentication
Source: https://docs.airscale.io/api-reference/authentication.md
Description: Create, send, protect, and rotate an Airscale API key.
Airscale authenticates API requests with a workspace API key sent as a Bearer token.
## Create an API key
Create the key in **Airscale Settings**: open the [Airscale dashboard](https://app.airscale.io/dashboard), choose **Settings → API key**, and generate a key for your integration.
Store the value in your server's secret manager or environment configuration:
```bash
export AIRSCALE_API_KEY="YOUR_API_KEY"
```
## Send the key
Include this header on every API request:
```text
Authorization: Bearer $AIRSCALE_API_KEY
```
## Job-change monitoring keys
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by the `/v1/job-change-monitors` endpoints. Use the key from your V2 workspace; monitors and monitoring credits belong to that workspace.
New hire monitoring (`/v1/new-hire-monitors`) and post engagement monitoring (`/v1/post-engagement-monitors`) have the same requirement: use a V2 workspace API key. An unknown key returns `401` with `{"error": {"code": "invalid_api_key", "message": "The API key is not valid"}}`.
## Handle unauthorized requests
A missing Bearer token or an invalid API key returns `401 Unauthorized`. Check that the header is present, that it starts with `Bearer`, and that your deployed secret contains the current key before retrying.
Keep API keys server-side. Never commit them to source control, place them in examples, or expose them in browser or mobile client bundles.
## Rotate a compromised key
If a key is exposed, rotate it immediately in **Airscale Settings**. Update the server-side secret, deploy the new value, verify an authenticated request, and stop using the old key.
Next, review [Rate limits](/api-reference/rate-limits) before adding request concurrency or retries.
---
## Rate limits
Source: https://docs.airscale.io/api-reference/rate-limits.md
Description: Understand endpoint-specific request limits and 429 responses.
Airscale rate limits are endpoint-specific. Each endpoint can enforce a different request limit and time window, so use the value documented on the endpoint page you are calling.
## Limits by endpoint
All numeric limits below apply per workspace unless the row names another scope. A shared limit is one combined allowance for the named routes.
| Endpoint | Rate limit |
| --- | --- |
| [Credit count](/api-reference/credit-count) | No endpoint-specific rate limit is documented. |
| [Email finder](/api-reference/email-finder) | 3,000 requests per minute per workspace. |
| [Bulk email finder](/api-reference/email-finder-(bulk)) | 3,000 input items per minute per workspace. |
| [Mobile finder](/api-reference/mobile-finder) | 6,000 requests per minute per workspace. |
| [Personal email](/api-reference/personal-email) | 2,000 requests per minute per workspace. |
| [People URL finder](/api-reference/people-url-finder) | 6 requests per second per workspace. |
| [People profile](/api-reference/extract-people-profile) | 3,000 requests per minute per workspace. |
| [Company profile](/api-reference/extract-company-profile) | 3,000 requests per minute per workspace. |
| [Domain to LinkedIn](/api-reference/domain-to-linkedin) | 180 requests per minute per workspace. |
| [Reverse email](/api-reference/reverse-email) | 25 requests per second per workspace. |
| [Reverse phone](/api-reference/reverse-phone) | 2,000 requests per minute per workspace. |
| [Find people](/api-reference/find-people) | 6 requests per second per workspace. |
| [Count people](/api-reference/find-people/count) | 6 requests per second per workspace. |
| [Find companies](/api-reference/find-companies) | 6 requests per second per workspace. |
| [Company filter values](/api-reference/find-companies/filter-values) | 6 requests per second per workspace. |
| [Business intent topics](/api-reference/business-intent-topics) | 6 requests per second per workspace. |
| [Company lookalikes](/api-reference/company-lookalikes) | 15 requests per rolling minute per workspace. Maximum 5 active searches per workspace. |
| [Airsearch](/api-reference/airsearch) | 300 requests per minute per workspace. |
| [Post likers](/api-reference/post-likers) | 180 requests per fixed minute per workspace, shared by post-likers and post-commenters; pagination requests and retries count. |
| [Post commenters](/api-reference/post-commenters) | 180 requests per fixed minute per workspace, shared by post-likers and post-commenters; pagination requests and retries count. |
| [Post search](/api-reference/post-search) | 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count. |
| [Profile comments](/api-reference/profile-comments) | 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count. |
| [Comment likers](/api-reference/comment-likers) | 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count. |
| [Profile posts](/api-reference/profile-posts) | 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count. |
| [Company posts](/api-reference/company-posts) | 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count. |
| [Create a job-change monitor](/api-reference/job-change-monitors/create) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [List job-change monitors](/api-reference/job-change-monitors/list) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [Get a job-change monitor](/api-reference/job-change-monitors/get) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [Update a job-change monitor](/api-reference/job-change-monitors/update) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [Delete a job-change monitor](/api-reference/job-change-monitors/delete) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [Add profiles to a job-change monitor](/api-reference/job-change-monitors/profiles/add) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [Remove a profile from a job-change monitor](/api-reference/job-change-monitors/profiles/remove) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [List job-change events](/api-reference/job-change-monitors/events) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [Mark a job-change event as read](/api-reference/job-change-monitors/events/read) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [Redeliver a job-change webhook](/api-reference/job-change-monitors/events/redeliver) | 120 requests per fixed minute per API key, shared by all job-change monitor endpoints. |
| [Create a new hire monitor](/api-reference/new-hire-monitors/create) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [List new hire monitors](/api-reference/new-hire-monitors/list) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [Get a new hire monitor](/api-reference/new-hire-monitors/get) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [Update a new hire monitor](/api-reference/new-hire-monitors/update) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [Delete a new hire monitor](/api-reference/new-hire-monitors/delete) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [Add companies to a new hire monitor](/api-reference/new-hire-monitors/companies/add) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [Remove a company from a new hire monitor](/api-reference/new-hire-monitors/companies/remove) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [List new hire events](/api-reference/new-hire-monitors/events) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [Mark a new hire event as read](/api-reference/new-hire-monitors/events/read) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [Redeliver a new hire webhook](/api-reference/new-hire-monitors/events/redeliver) | 120 requests per fixed minute per API key, shared by all new hire monitor endpoints. |
| [Create a post engagement monitor](/api-reference/post-engagement-monitors/create) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [List post engagement monitors](/api-reference/post-engagement-monitors/list) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [Get a post engagement monitor](/api-reference/post-engagement-monitors/get) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [Update a post engagement monitor](/api-reference/post-engagement-monitors/update) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [Delete a post engagement monitor](/api-reference/post-engagement-monitors/delete) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [Add sources to a post engagement monitor](/api-reference/post-engagement-monitors/sources/add) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [Remove a source from a post engagement monitor](/api-reference/post-engagement-monitors/sources/remove) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [List post engagers](/api-reference/post-engagement-monitors/engagers) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [List post engagements](/api-reference/post-engagement-monitors/engagements) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [Mark a post engager as read](/api-reference/post-engagement-monitors/engagers/read) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [Redeliver a post engager webhook](/api-reference/post-engagement-monitors/engagers/redeliver) | 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints. |
| [Website Technologies](/api-reference/miscellaneous/website-technologies) | 10 requests per second per workspace. |
| [WhatsApp checker](/api-reference/miscellaneous/whatsapp-check) | 60 requests per minute per workspace for POST, including replays. |
| [WhatsApp check status](/api-reference/miscellaneous/whatsapp-check/status) | No endpoint-specific GET throttle. |
| [Meta Ads](/api-reference/miscellaneous/meta-ads) | 60 requests per minute per workspace. |
| [Google Maps](/api-reference/miscellaneous/google-maps) | 15 admitted searches per rolling minute and five active searches per workspace, shared across API keys and MCP. |
| [Google Ads](/api-reference/miscellaneous/google-ads) | 2 requests per rolling second and 120 per rolling minute per workspace. |
| [Email verifier](/api-reference/miscellaneous/email-verifier) | No endpoint-specific throttle. |
| [Leads Finder](/api-reference/leads-finder) | 5 requests per second per workspace. |
| [US DNC Checker](/api-reference/dnc-checker) | 5 requests per second per workspace. |
| [UK DNC Checker](/api-reference/uk-dnc-checker) | 5 requests per rolling second per workspace. |
| [Find hashed emails](/api-reference/hashed-emails) | 60 requests per rolling second per workspace. |
Find people shares its **6 requests per second** with Count people. Find companies shares its **6 requests per second** with Company filter values and Business intent topics. These are separate limits for the two endpoint families. Post search, Profile comments, Comment likers, Profile posts, and Company posts each have their own 180-request allowance; they do not share it with each other or with Post likers and Post commenters.
Company lookalikes returns `429` when its rate or concurrency limit is reached. Honor `Retry-After` when present. Repeating a search can cause another charge; see the [endpoint guidance](/api-reference/company-lookalikes).
The job-change monitor endpoints share one allowance of **120 requests per fixed minute**, counted per API key across all ten endpoints, and return `Retry-After: 60` with `429`.
The new hire monitor endpoints and the post engagement monitor endpoints each have their own allowance of **120 requests per fixed minute** per API key, shared across the endpoints of that API, and return `Retry-After: 60` with `429`.
For bulk email, the allowance counts **input items**, not HTTP requests. An endpoint without a documented numeric limit should not be treated as unlimited; use bounded concurrency and handle `429` responses.
## Handle rate-limit responses
When a request exceeds an endpoint's limit, the API returns `429 Too Many Requests`. Treat the status code as the rate-limit signal; do not depend on an error field or response header unless that endpoint page documents it.
Only retry when the endpoint page says the operation is safe to retry. Use bounded exponential backoff: cap both the maximum delay and the total number of attempts, then surface a persistent `429` to your application.
## Check an endpoint's limit
Review the request limit on the endpoint page before setting concurrency:
People search limits and request contract.
Company search limits and request contract.
Professional email lookup limits and request contract.
Airsearch limits and request contract.
---
## Credit count
Source: https://docs.airscale.io/api-reference/credit-count.md
Description: Check the remaining credit balance for your Airscale workspace. Rate limit: No endpoint-specific rate limit is documented.
Read the remaining credit balance for the workspace associated with your API key before starting paid enrichment work.
Send no request body. Checking the balance is free and does not debit Airscale credits.
An invalid or missing key returns `401 Unauthorized`. Confirm the current key in the Airscale dashboard and update your server-side secret; rotate it only if it was exposed.
## Next step
Use your authenticated client to [find people](/api-reference/find-people), or review [Authentication](/api-reference/authentication) before sending requests.
---
## Find people
Source: https://docs.airscale.io/api-reference/find-people.md
Description: Search people using person, role, and company filters. Rate limit: 6 requests per second per workspace.
Search for people using person, role, current-company, and past-experience filters, then page through the matching lead records.
The Search and [Count people](#count-matching-people) operations share a limit of 6 requests per second per workspace. Search costs 0.1 credits per returned lead; empty result pages are not charged. Count accepts the same `query` for free.
Search returns at most 100 leads per request. When `next_cursor` is not `null`, send it unchanged as `cursor` with the same `query`. Do not derive or edit cursor contents.
After a `429`, wait for the next second and retry with bounded exponential backoff. Failed searches do not return charged leads. For temporary `502` or `503` responses, use a limited number of retries with increasing delays; contact support if errors persist.
## Count matching people
Use `POST https://api.airscale.io/v1/find-people/count` to estimate this audience before retrieving leads. Send the same `query` object and Bearer authorization as Find people, with `Content-Type: application/json`. Omit `size` and `cursor`: Count has no pagination fields.
Count is free. It neither reserves nor debits credits and returns only `total`, the number of matching people. It shares the search rate limit above; after a `429`, retry with bounded backoff.
```json Count request
{
"query": {
"jobTitle": {
"include": ["Founder"]
}
}
}
```
```json Count response
{
"total": 1250
}
```
## Combining past-experience filters
All past-experience filters apply to the same prior role. For example, combining `pastJobTitle.include: ["Engineer"]` with `pastCompanyName.include: ["Example Company"]` finds people who worked as an engineer at that company. It does not match someone who was an engineer at another company and held a different role at Example Company.
`pastCompany.location` accepts country names and ISO alpha-2 country codes, just like `location` and `currentCompany.location`.
## Lead fields
`leads` contains public person records. The following fields are common, not a guarantee that every field is present or non-null. Preserve additional public fields your integration needs and tolerate missing values.
| Field | Meaning |
| --- | --- |
| `firstname`, `lastname` | Person's first and last names. |
| `headline`, `description` | Profile headline and description. |
| `profileUrl` | LinkedIn person profile URL. |
| `jobTitle` | Current role title. |
| `jobStartDate` | Current-role start date, for example `03-2024`. |
| `address` | Person location. |
| `companyName` | Current employer name. |
| `companyUrl`, `companyWebsite` | Employer LinkedIn URL and website. |
| `companySize` | Available company headcount. |
| `companyIndustry`, `companyAddress` | Employer industry and location. |
Use `next_cursor` from the response envelope for pagination. Do not construct a cursor from a lead's fields.
## Next step
Use the same `query` to retrieve the counted audience, [Find companies](/api-reference/find-companies) to discover organizations, or [Rate limits](/api-reference/rate-limits) before adding concurrency.
---
## Leads Finder
Source: https://docs.airscale.io/api-reference/leads-finder.md
Description: Search people with Leads Finder filters and page-based pagination. Rate limit: 5 requests per second per workspace.
Search for people using person and company filters. This operation uses a `filters` object and zero-based `page` pagination. [Find people](/api-reference/find-people) uses a different `query` model and cursor pagination; their request bodies are not interchangeable.
The limit is 5 requests per second per workspace. Each returned lead costs 0.1 credits; empty pages cost zero credits. At least 0.1 credits must be available before searching; credit admission can reserve up to `size × 0.1` credits before the request runs.
## Choose filters
At least one non-empty filter other than `searchMode` is required. Include only the criteria you need. The OpenAPI request schema below lists the supported fields.
| Criteria | Fields |
| --- | --- |
| Job titles | `job`, `jobExclude` |
| Companies | `company`, `companyUrl` |
| Person locations | `peopleLocation`, `peopleLocationExclude` |
| Seniority and functions | `seniority`, `seniorityExclude`, `jobFunction`, `jobFunctionExclude` |
| Tenure and experience | `yearsCurrentRole`, `yearsCurrentCompany`, `yearsWorkExperience`, `duration` |
| Skills, languages, certifications | `skills`, `language`, `certification`, and their `Exclude` fields |
| Profile text and badges | `profileKeywords`, `profileKeywordsExclude`, `profileBadge` |
| Company industry, locations, type | `industry`, `hq`, `type`, and their `Exclude` fields |
| Company size, revenue, founding year | `size`, `revenue`, `founded` |
| Company text | `companyKeywords`, `companyKeywordsExclude` |
| Funding | `funding`, `fundingAmount`, `fundingDateMonths` |
| Department metrics | `department`, `growth` |
| Person name | `fullName`, `fullNameExclude` |
| Past roles | `pastJob`, `pastCompany`, and their `Exclude` fields |
| Education | `educationSchool`, `educationDegree`, `educationFieldOfStudy` |
Use strings or arrays for `job`, `jobExclude`, `company`, `companyUrl`, person locations, job functions, and the name, past-role and education fields. Other text filters accept strings; separate multiple values with newlines. Each job-function include/exclude input allows at most 300 non-empty values. `company` and `companyUrl` together allow at most 300 domains or LinkedIn company URLs per search, and `company` at most 300 company names; split larger lists into batches of 300. `searchMode` supports `SMART`, `WORD`, and `STRICT`, defaulting to `SMART`.
Textual tenure examples include `1 to 2 years`, `Less than 1 year`, and `More than 10 years`. Structured `duration` accepts `latestCompany`, `currentCompany`, `previousCompany`, `latestJob`, `currentJob`, `previousJob`, and `total`. Each contains `min`, `max`, or both, with non-negative integer `year` and/or `month` values; months must be 0–11 and the minimum must not exceed the maximum. Structured bounds override the corresponding textual tenure field.
```json Structured tenure example
{
"filters": {
"job": ["Founder"],
"duration": {
"currentCompany": { "min": { "year": 1 }, "max": { "year": 3 } }
}
},
"page": 0,
"size": 25
}
```
## Name, past roles and education
- `fullName` matches the person's full name, for example `Sylvain Coindre`.
- `pastJob` matches any previous job title. It works alongside `job`, which matches the current title.
- `pastCompany` matches companies from previous jobs, and `educationSchool` matches schools the person attended. Each accepts a name, a website domain (`google.com`, `hec.edu`) or a LinkedIn URL (`https://www.linkedin.com/company/google`, `https://www.linkedin.com/school/hec-paris`), with at most 25 values per field. A domain or LinkedIn URL is the most reliable; names must match exactly. If a value cannot be matched, the request returns `422` with the unmatched values and no credits are charged.
- `educationDegree` and `educationFieldOfStudy` match degree and field-of-study text, for example `Master` and `Finance`.
- Education filters are include-only. Excluding schools, degrees or fields of study is not supported yet, and `educationSchoolExclude`, `educationDegreeExclude` and `educationFieldOfStudyExclude` return `400`.
In strings, separate names, companies and schools with newlines only, so values such as `Acme, Inc.` stay intact. Arrays are never split.
```json Past role and education example
{
"filters": {
"pastJob": ["Sales Director"],
"pastCompany": ["google.com", "https://www.linkedin.com/company/microsoft"],
"educationSchool": ["https://www.linkedin.com/school/hec-paris"],
"educationFieldOfStudy": ["Finance"]
},
"page": 0,
"size": 25
}
```
## Expected filter values
These values apply to `POST /v1/leads-finder` and the `airscale_leads_finder` MCP tool. [Find Companies filter values](/api-reference/find-companies/filter-values) belongs to a different search and does not list Leads Finder values.
Use the identifiers below for preset filters. Include and exclude fields use the same vocabulary. For string fields, separate multiple values with a newline (`\n` in JSON). `jobFunction` and `jobFunctionExclude` also accept arrays, with at most 300 values in each field. Use exact job-function identifiers, such as `business_development`, rather than display labels such as `Business Development`.
Some unsupported legacy values can be ignored instead of rejected. A successful response does not confirm that every supplied filter value was applied. Use the values and formats documented here.
### Seniority
For `seniority` and `seniorityExclude`, use these 12 values:
```text
founder
owner
partner
c_suite
vp
director
head
manager
senior
mid-level
entry
intern
```
Example: `"seniority": "c_suite\nvp\ndirector"`.
### Job function
For `jobFunction` and `jobFunctionExclude`, use an identifier from the full list below. Common examples are `sales`, `business_development`, `software_development`, `demand_generation`, `human_resources`, and `accounting`.
```json Job-function example
{
"filters": {
"jobFunction": ["sales", "business_development"],
"jobFunctionExclude": ["sales_operations"],
"seniority": "c_suite\nvp"
},
"page": 0,
"size": 10
}
```
```text
accounting
accounting_management
accounts_payable
accounts_receivable
bookkeeping
consolidation_accounting
cost_accounting
external_audit_and_assurance
financial_reporting
fixed_asset_accounting
general_ledger_and_close
other_accounting
payroll_accounting
revenue_accounting
tax_accounting
administrative
administrative_assistant
calendar_travel_coordination
data_entry_and_clerical
document_and_mail_services
executive_assistant
facility_administration
front_desk_reception
meeting_and_event_coordination
office_management
other_administrative
personal_assistance
records_management
virtual_assistant_remote_admin
agriculture_forestry_and_animal_care
agricultural_operations
crop_production
environmental_and_natural_resource_management
farming_and_ranching
fisheries_and_aquaculture
forestry_and_conservation
livestock_and_animal_care
other_agriculture_forestry_and_animal_care
arts_entertainment_and_performance
acting_and_performance
cultural_and_museum_programming
dance_and_choreography
directing_and_producing
film_and_screen_production
live_entertainment_production
music_and_singing
other_arts_entertainment_and_performance
talent_and_casting
theatre_and_stage_production
beauty_and_personal_care
barbering
cosmetology_general
esthetics_and_skin_care
hair_styling
makeup_artistry
massage_and_bodywork
nail_care
other_beauty_and_personal_care
salon_and_spa_management
business_development
bids_proposals_and_capture_management
channel_development
corporate_development
corporate_strategy
country_management
franchise_development
international_expansion
market_development
new_ventures_and_corporate_innovation
other_business_development
partnerships_and_alliances
strategic_business_development
community_and_social_services
advocacy_public_policy
case_management
child_family_services
community_health_services
community_outreach
counseling
crisis_intervention
family_caregiving
fundraising_development
grants_management
nonprofit_program_management
other_community_and_social_services
philanthropy_and_foundation_relations
rehabilitation_services
religious_spiritual_services
social_work
volunteer_coordination
consulting
financial_consulting
human_capital_consulting
implementation_consulting
it_consulting
management_consulting
marketing_and_sales_consulting
operations_consulting
other_consulting
risk_consulting
solutions_consulting
strategy_consulting
supply_chain_consulting
sustainability_esg_consulting
transformation_consulting
customer_success_and_support
call_center
customer_community_management
customer_education
customer_experience
customer_onboarding
customer_retention
customer_success
customer_success_operations
customer_support
customer_support_operations
implementation_services
other_customer_success_and_support
professional_services_and_customer_delivery
renewals_management
technical_support
design
brand_design
design_management
design_operations
fashion_and_apparel_design
fine_arts_illustration
floristry
graphic_design
industrial_design
interaction_design
interior_and_environmental_design
lighting_design
motion_design
other_design
photography_visual_storytelling
product_design
service_design
ui_ux
web_design
education
academic_affairs
admissions_enrollment
adult_and_continuing_education
alumni_development
assessment_and_accreditation
career_services
corporate_training_enablement
curriculum_development
early_childhood_education
education_policy
education_technology
higher_education_faculty
instructional_design
k12_instruction
library_services
online_learning_and_elearning
other_education
school_leadership_and_administration
special_education
student_affairs
tutoring_and_test_preparation
vocational_and_technical_education
energy_mining_and_utilities
energy_and_utilities_operations
grid_transmission_and_distribution_operations
mining_and_extractive_operations
oil_and_gas_operations
other_energy_mining_and_utilities
power_generation_operations
water_and_waste_operations
engineering_technical
aerospace_engineering
artificial_intelligence_machine_learning
bioengineering
business_intelligence
cad_and_drafting
chemical_engineering
civil_and_structural_engineering
data_engineering
data_science
devops
electrical_engineering
embedded_and_firmware_engineering
engineering_management
engineering_ops_sre
engineering_technician
environmental_engineering
geospatial_and_gis
hardware_engineering_electronics
industrial_engineering
manufacturing_and_process_engineering
marine_and_naval_engineering
materials_engineering
mechanical_engineering
mobile_development
other_engineering_technical
platform_engineering
robotics_and_automation
software_development
surveying_and_geomatics
systems_engineering
finance
asset_and_wealth_management
commercial_banking
corporate_finance
credit_and_lending
financial_planning_analysis
financial_risk_management
financial_strategy
financial_systems
fraud_and_financial_crime
insurance_actuarial_and_underwriting
internal_audit_control
investment_banking_and_capital_markets
investor_relations
mergers_acquisitions
other_finance
pricing_and_revenue_management
project_finance
real_estate_finance
securities_and_commodities_trading
tax_strategy_and_planning
treasury
general_management
executive_leadership_and_general_management
hospitality_food_and_guest_services
casino_and_gaming_operations
culinary_and_kitchen_operations
event_hospitality_and_catering
food_and_beverage_service
guest_services_and_concierge
hospitality_management
hospitality_revenue_management
hotel_and_lodging_operations
housekeeping_and_accommodation_services
other_hospitality_food_and_guest_services
restaurant_operations
travel_and_tourism_services
human_resources
compensation_benefits
diversity_equity_inclusion
employee_experience
employee_labor_relations
employee_wellbeing
employer_branding
global_mobility
hr_business_partner
hr_compliance
hr_generalist_and_administration
human_resource_information_system
leadership_development
learning_development
organizational_development
other_human_resources
people_analytics
people_operations
recruiting_talent_acquisition
succession_planning
talent_management
workforce_management
workforce_planning
information_technology
business_continuity_disaster_recovery
business_service_management_itsm
cloud_engineering
cybersecurity
cybersecurity_operations
data_center
data_governance
data_warehouse
database_administration
digital_transformation
emerging_technology_innovation
end_user_support
enterprise_applications_erp_crm
enterprise_architecture
identity_and_access_management
infrastructure
integration_and_middleware
it_asset_management
it_governance_risk_and_compliance
it_strategy
it_training
it_vendor_management
network_operations_center
networking
observability_and_monitoring
other_information_technology
retail_store_systems
solution_architecture
technology_operations
telecommunications
virtualization
legal
antitrust_and_competition
claims_and_disputes
commercial_transactions
compliance
contracts
corporate_and_securities_law
corporate_secretary
ediscovery
ethics_and_investigations
governance
immigration_law
intellectual_property_patent
judiciary_and_courts
labor_and_employment_law
legal_counsel
legal_operations
legal_support_and_paralegal
litigation
other_legal
privacy
regulatory_affairs
regulatory_law
manufacturing_and_production
food_and_beverage_production
industrial_production_management
manufacturing_and_plant_operations
materials_and_fabrication
other_manufacturing_and_production
process_and_machine_operations
production_and_assembly
marketing
account_based_marketing
advertising
affiliate_marketing
brand_management
community_marketing
content_marketing
conversion_rate_optimization
customer_marketing
demand_generation
digital_marketing
ecommerce_marketing
event_marketing
field_marketing
growth_marketing
influencer_creator_marketing
lead_generation
lifecycle_and_crm_marketing
marketing_analytics_insights
marketing_automation
marketing_communications
marketing_management
marketing_operations
other_marketing
paid_search_and_performance_marketing
partner_and_channel_marketing
product_marketing
search_engine_optimization
social_media_marketing
technical_marketing
media_and_communication
broadcast_production
content_strategy
copywriting
corporate_communications
creative_writing_authoring
crisis_communications
digital_content_production
editorial
foreign_affairs
government_affairs
internal_communications
journalism_reporting
media_relations
multimedia_audiovisual
other_media_and_communication
podcast_and_audio_production
public_affairs
public_relations
publishing
speechwriting
technical_writing
translation_localization
medical_health
anesthesiology
athletic_training
audiology
behavioral_and_mental_health
cardiology
chiropractics
clinical_systems
complementary_and_alternative_medicine
dentistry
dermatology
emergency_medicine
epidemiology
exercise_physiology
gastroenterology
health_information_management_and_medical_coding
health_promotion_and_clinical_wellness
healthcare_operations
home_health_and_long_term_care
infectious_disease
laboratory_and_diagnostics
medical_administration
medical_education_training
neurology
nursing
nutrition_dietetics
obstetrics_gynecology
occupational_health
occupational_therapy
oncology
ophthalmology
optometry
orthopedics
other_medical_health
pathology
patient_care_support
pediatrics
pharmacy
physical_therapy
physicians_and_general_medicine
primary_care_family_and_internal_medicine
psychiatry
psychology
public_health
radiology
respiratory_therapy
speech_language_pathology
sports_medicine
surgery
urology
veterinary_medicine
military_and_protective_services
corrections
customs_and_border_security
emergency_management
emergency_response
enlisted_operations
fire_and_rescue
intelligence_security
investigations
law_enforcement
loss_prevention
officer_command
other_military_and_protective_services
private_security
protective_intelligence
security_operations
operations
business_operations
event_management_production
field_operations
health_safety_and_environment
inventory_and_materials_management
operational_excellence_and_process_improvement
other_operations
service_delivery
shared_services
store_operations
supply_chain
product_management
general_product_management
growth_product_management
other_product_management
platform_product_management
product_analytics
product_development
product_discovery
product_operations
product_owner
product_portfolio_management
product_strategy
technical_product_management
program_and_project_management
change_management
construction_project_management
delivery_management
implementation_project_management
monitoring_evaluation_and_learning
other_program_and_project_management
pmo
portfolio_management
program_management
project_controls_and_planning
project_management
scrum_master_agile_coach
technical_program_management
transformation_program_management
public_administration_and_government
defense_policy
diplomacy_and_foreign_service
elected_office_and_legislative_affairs
government_program_administration
other_public_administration_and_government
public_administration_and_civil_service
public_finance_and_tax_administration
public_policy_and_policy_analysis
regulatory_and_inspection_services
urban_and_regional_planning
purchasing
category_management
contract_management
direct_materials_procurement
indirect_procurement
other_purchasing
procurement
procurement_analytics
purchasing_operations
spend_analysis
strategic_sourcing
supplier_relationship_management
vendor_management
quality_assurance
manufacturing_quality
other_quality_assurance
quality_audit
quality_control
quality_management
regulatory_quality
software_testing
supplier_quality
test_automation
test_engineering
validation
real_estate
acquisitions_and_dispositions
brokerage_and_real_estate_sales
commercial_real_estate
leasing
other_real_estate
property_management
real_estate_asset_management
real_estate_development
real_estate_investment
real_estate_operations
residential_real_estate
tenant_relations
valuation_and_appraisal
workplace_real_estate
research
academic_research
clinical_research
clinical_trials
competitive_intelligence
consumer_insights
economic_affairs
laboratory_research
market_research
medical_research
operations_research
other_research
policy_research
qualitative_research
quantitative_research
research_development
research_operations
scientific_research
social_and_behavioral_research
user_research
sales
account_executive_and_new_business_sales
account_management
channel_sales
commercial_operations
enterprise_sales
field_outside_sales
inside_sales
insurance_sales_and_brokerage
other_sales
partner_sales
retail_merchandising
retail_sales
revenue_operations
sales_compensation_and_planning
sales_development
sales_enablement
sales_engineering
sales_management
sales_operations
sales_training
strategic_and_key_accounts
territory_sales
skilled_trades_construction_and_maintenance
automotive_service_and_repair
building_and_grounds_services
construction_estimating
construction_operations
construction_trades
electrical_trades
facilities_management
field_service_technical
heavy_equipment_operation
installation_and_repair
maintenance_reliability_and_mro
mechanical_and_hvac_trades
other_skilled_trades_construction_and_maintenance
plumbing_and_pipefitting
sports_and_recreation
fitness_and_personal_training
other_sports_and_recreation
professional_athletes
recreation_and_leisure_services
sports_coaching
sports_management_and_operations
sports_officiating
sports_science_and_performance_coaching
transportation_and_logistics
cabin_crew_and_inflight_services
dispatch_and_transport_coordination
fleet_management
flight_operations_and_pilots
import_export_and_customs
logistics
maritime_and_deck_operations
order_management_and_fulfillment
other_transportation_and_logistics
road_and_rail_transport
transportation_operations
warehouse_operations
unknown
```
### Funding round
For `funding`, use these 30 values:
```text
PRE_SEED
SEED
SERIES_A
SERIES_B
SERIES_C
SERIES_D
SERIES_E
SERIES_F
SERIES_G
SERIES_H
SERIES_I
SERIES_J
VENTURE_ROUND
ANGEL
PRIVATE_EQUITY
DEBT_FINANCING
CONVERTIBLE_NOTE
GRANT
CORPORATE_ROUND
EQUITY_CROWDFUNDING
PRODUCT_CROWDFUNDING
SECONDARY_MARKET
POST_IPO_EQUITY
POST_IPO_DEBT
POST_IPO_SECONDARY
NON_EQUITY_ASSISTANCE
INITIAL_COIN_OFFERING
UNDISCLOSED
SERIES_UNKNOWN
FUNDING_ROUND
```
Example: `"funding": "SEED\nSERIES_A"`. Use `fundingAmount` for a last-funding amount range and `fundingDateMonths` for the lookback period; these are separate fields described below.
### Company type
For `type` and `typeExclude`, use:
```text
PRIVATELY_HELD
SELF_OWNED
SELF_EMPLOYED
PARTNERSHIP
PUBLIC_COMPANY
NON_PROFIT
EDUCATIONAL
GOVERNMENT_AGENCY
```
### Profile badge
For `profileBadge`, use:
```text
VERIFIED
PREMIUM
OPEN_TO_WORK
INFLUENCER
CREATOR
HIRING
```
### Search mode
For `searchMode`, use `SMART`, `WORD`, or `STRICT`. The default is `SMART`. This controls text matching; it does not turn arbitrary text into a supported preset identifier.
### Department headcount and growth
`department` combines a department identifier and a headcount range on separate lines. `growth` combines a department identifier, a percentage range, and a lookback period on separate lines.
| Field | Example JSON value | Meaning |
| --- | --- | --- |
| `department` | `"sales\n10-100"` | Between 10 and 100 employees in sales |
| `growth` | `"sales\n20-80\n3 months"` | Sales headcount growth between 20% and 80% over three months |
Use `1 month`, `3 months`, `6 months`, or `12 months` for the growth period. The default is three months; other periods currently fall back to three months.
These metrics use the following 27 department identifiers, a smaller list than the person job-function catalogue:
```text
sales
marketing
engineering
finance
human_resources
information_technology
operations
business_development
customer_success_and_support
product_management
accounting
legal
consulting
education
research
purchasing
real_estate
media_and_communication
quality_assurance
arts_and_design
healthcare_services
entrepreneurship
community_and_social_services
administrative
military_and_protective_services
program_and_project_management
support
```
### Ranges and dates
These fields take strings rather than preset identifiers. Use plain numbers without currency symbols or thousands separators.
| Field | Expected value | Examples |
| --- | --- | --- |
| `size` | Company headcount range; newline-separated ranges are supported | `"11-50"`, `"10000+"` |
| `revenue` | Annual revenue range in USD; newline-separated ranges are supported | `"1000000-10000000"` |
| `founded` | One founding-year range | `"2015-2022"` |
| `fundingAmount` | One last-funding amount range in USD | `"1000000-5000000"` |
| `fundingDateMonths` | Positive integer number of months as a string | `"3"`, `"6"`, `"12"`, `"24"` |
| `yearsCurrentRole` | Current-role tenure in years | `"1 to 2 years"` |
| `yearsCurrentCompany` | Current-company tenure in years | `"3 to 5 years"` |
| `yearsWorkExperience` | Total work experience in years | `"More than 10 years"` |
The tenure presets are `Less than 1 year`, `1 to 2 years`, `3 to 5 years`, `6 to 10 years`, and `More than 10 years`. Custom continuous ranges such as `"2 to 4 years"` are also supported. If you combine tenure ranges, use adjacent ranges without gaps. For month-level bounds, use the structured `duration` fields described above.
The company-size presets are `1-10`, `11-20`, `21-50`, `51-100`, `101-200`, `201-500`, `501-1000`, `1001-2000`, `2001-5000`, `5001-10000`, and `10000+`. Custom numeric ranges are also supported.
### Text and location filters
These fields accept search text rather than a closed preset list. The examples are starting points, not the only accepted values.
| Fields | Expected input | Example |
| --- | --- | --- |
| `job`, `jobExclude` | Job titles; use arrays | `["VP Sales", "Head of Sales"]` |
| `company` | Company names, domains, or LinkedIn company URLs | `["Example Company", "example.com"]` |
| `companyUrl` | Company domains or LinkedIn company URLs | `["example.com", "https://www.linkedin.com/company/example-company"]` |
| `peopleLocation`, `peopleLocationExclude` | Country, state, or city names | `["United States", "California"]` |
| `hq`, `hqExclude` | Company locations; matches any office, not only headquarters | `"United States\nCanada"` |
| `industry`, `industryExclude` | Industry names, as a string | `"software development\nfinancial services"` |
| `skills`, `skillsExclude` | Skill names, as a string | `"negotiation\naccount management"` |
| `language`, `languageExclude` | Language names, as a string | `"English\nFrench"` |
| `certification`, `certificationExclude` | Certification names, as a string | `"PMP"` |
| `profileKeywords`, `profileKeywordsExclude` | Person-profile search terms, as a string | `"revenue operations"` |
| `companyKeywords`, `companyKeywordsExclude` | Company-profile search terms, as a string | `"cybersecurity"` |
```json Preset-filter example
{
"filters": {
"seniority": "c_suite\nvp",
"jobFunction": ["sales", "business_development"],
"funding": "SEED\nSERIES_A",
"type": "PRIVATELY_HELD",
"size": "11-50",
"fundingDateMonths": "12",
"searchMode": "SMART"
},
"page": 0,
"size": 10
}
```
## Read results and paginate
The response contains `rows`, `total`, `page`, and `size`. Each row is a nested person record with **snake_case** keys: the name is under `profile` (`profile.first_name`, `profile.last_name`, `profile.headline`), the LinkedIn URL is `link.linkedin`, work history is `position_groups`, and the current employer is `company` (`company.summary.name`, `company.link.domain`). Fields depend on available data, can be `null` or absent, and rows can include fields not listed in the schema. `total` can be `null` when a reliable count is unavailable or company/title correlation removes rows.
`size` defaults to 50 and accepts 1–100. Start at `page: 0` and increment the page while keeping the same filters and size. This operation does not return `next_cursor`. When company and title filters are combined, returned rows are checked for a matching title at the identified company; a page can contain fewer rows after that check, and a short page alone does not establish exhaustion.
After `429`, retry in a later second with bounded exponential backoff. For `503` (a service is temporarily unavailable; honor `Retry-After`) and `504` (the search timed out), retry with increasing delays and a fixed retry limit; contact support if errors persist. A `400` also covers lists over 300 values and pages past the deepest page a search can return; the `message` field says which. Correct invalid filters before retrying `400` responses. Requests larger than 256 KiB return `413`.
## Next step
Use [Find people](/api-reference/find-people) if you need its person/current-company/past-experience filter model and free count operation. Existing Leads Finder integrations can continue using their documented route and request model.
---
## Find companies
Source: https://docs.airscale.io/api-reference/find-companies.md
Description: Search companies using firmographic, location, event, intent, and technology filters. Rate limit: 6 requests per second per workspace.
Search companies by firmographic, location, event, intent, and technology filters, then page through the matching organizations.
Search shares a limit of 6 requests per second per workspace with [Company filter values](/api-reference/find-companies/filter-values). It costs 0.1 credits per returned company; zero returned rows cost zero credits. At least 0.1 credits must be available before Search begins.
When `next_cursor` is not `null`, send the exact value unchanged as `cursor` with the same filters. Do not decode, construct, or edit the cursor. Cursor pagination preserves the original page size and can traverse up to 10,000 companies for one search.
After a `429`, wait for the next second and retry with bounded exponential backoff. For temporary `502` or `503` responses, retry with increasing delays and a fixed retry limit. If errors persist, stop retrying and contact support.
## Company fields
`rows` contains public company records. Fields vary with available data; the following list is illustrative, not a set of required fields.
| Field | Meaning |
| --- | --- |
| `name`, `description` | Company name and description. |
| `domain`, `website` | Company domain and website URL. |
| `linkedinProfile` | LinkedIn company profile URL when available. |
| `logo` | Company logo URL when available. |
| `countryName`, `cityName` | Company location. |
| `employeeRange`, `revenueRange` | Available headcount and revenue ranges. |
The response does not guarantee a stable company ID. Use the available domain or LinkedIn URL to help match records, and handle missing fields.
## Discover filter values
Use [Company filter values](/api-reference/find-companies/filter-values#discovery-examples) to discover city, region, industry, intent-topic, and technology values, then send the returned `value` unchanged. Industry and topic values come from canonical lookup lists; `keywords` and `companyName` accept free text.
Use JSON booleans for `hasWebsite` and `isPublicCompany`, not strings such as `"true"`. The largest fixed buckets are `10001+` for employee size, `10T+` for revenue, `20+` for company age, and `1001+` for location count.
## Next step
Use [Company filter values](/api-reference/find-companies/filter-values) to discover accepted values, [Find people](/api-reference/find-people) to search for roles at identified companies, or [Authentication](/api-reference/authentication) before integrating.
---
## Company filter values
Source: https://docs.airscale.io/api-reference/find-companies/filter-values.md
Description: Search supported values for Find Companies filters. Rate limit: 6 requests per second per workspace.
Discover accepted values before adding a city, region, industry, topic, or technology filter to [Find companies](/api-reference/find-companies).
Filter-values is free and has no request body. It does not reserve or debit Airscale credits.
## Choose useful context
Use `country` and `region` to narrow location suggestions. A bare region name needs country context. The `q` parameter takes precedence when both `q` and its `query` alias are present; a blank `q` still suppresses `query` and returns `400 Bad Request`.
The operation shares a limit of 6 requests per second per workspace with Find companies. After a `429 Too Many Requests` response, wait for the next second and retry with bounded exponential backoff.
This page renders non-executing examples. It does not send a request or ask for an API key.
## Discovery examples
These examples only discover filter values; the endpoint is free. Set `AIRSCALE_API_KEY` in your server environment before running a command.
```bash Region suggestions
curl --get 'https://api.airscale.io/v1/find-companies/filter-values' \
-H "Authorization: Bearer $AIRSCALE_API_KEY" \
--data-urlencode 'filter=region' \
--data-urlencode 'q=california' \
--data-urlencode 'country=US'
```
```bash City suggestions
curl --get 'https://api.airscale.io/v1/find-companies/filter-values' \
-H "Authorization: Bearer $AIRSCALE_API_KEY" \
--data-urlencode 'filter=city' \
--data-urlencode 'q=san' \
--data-urlencode 'country=US' \
--data-urlencode 'region=us-ca'
```
```bash Technology suggestions
curl --get 'https://api.airscale.io/v1/find-companies/filter-values' \
-H "Authorization: Bearer $AIRSCALE_API_KEY" \
--data-urlencode 'filter=techStack' \
--data-urlencode 'q=hubspot'
```
```bash Industry suggestions
curl --get 'https://api.airscale.io/v1/find-companies/filter-values' \
-H "Authorization: Bearer $AIRSCALE_API_KEY" \
--data-urlencode 'filter=industry' \
--data-urlencode 'q=software'
```
```bash Business intent topic suggestions
curl --get 'https://api.airscale.io/v1/find-companies/filter-values' \
-H "Authorization: Bearer $AIRSCALE_API_KEY" \
--data-urlencode 'filter=topics' \
--data-urlencode 'q=customer relationship'
```
Each result has a display `label` and a request `value`. Copy `value` into the corresponding search filter. For locations, preserve the returned country/region context instead of assembling a city value from its display label. Search accepts recognized pipe-form and comma-form city values; autocomplete supplies the value to reuse.
`q` or its `query` alias must contain 2–120 characters after trimming. `q` takes precedence even when blank. The optional `limit` defaults to 20; integer values are clamped to 1–100, while non-numeric or non-integer values use the default.
## Next step
Copy the returned `value` into the matching filter on [Find companies](/api-reference/find-companies), or into `topics` on [Business intent topics](/api-reference/business-intent-topics).
---
## Company lookalikes
Source: https://docs.airscale.io/api-reference/company-lookalikes.md
Description: Find companies similar to your reference domains. Rate limit: 15 requests per rolling minute per workspace. Maximum 5 active searches per workspace.
Find companies similar to one or more reference companies. The request waits for the search to finish and returns company data directly.
Costs **0.5 credits per unique returned company**. Before searching, the API reserves `limit × 0.5` credits and refunds the unused amount afterward. Zero results cost zero credits. Each workspace can start **15 searches per rolling minute** and have **5 active searches** at a time.
Authenticate with your workspace API key. See [Authentication](/api-reference/authentication).
## Reference domains and result limits
Send 1–10 company websites in `domains`. Domains and website URLs are normalized and deduplicated. LinkedIn URLs and IP addresses are not accepted. Reference companies and domains listed in `exclude.domains` are omitted from results.
`limit` defaults to **2,000** and applies to the **entire response**:
| Distinct reference domains | Maximum total results |
| --- | --- |
| 1 | 2,000 |
| 2 | 4,000 |
| 3–10 | 5,000 |
For example, ten reference domains with `limit: 5000` request at most 5,000 unique companies in total. Results are deduplicated across references and may be fewer than requested. All results are returned in a single response.
## Filters
Use `include` and `exclude` to filter by country, city, and employee size. Country filters accept country names or ISO alpha-2 codes. A location filter that cannot be resolved can return `422`.
Each country or city list accepts up to 100 values. Supported size bands are `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, and `10001+`. Use `exclude.domains` to omit up to 900 company websites.
Use `founded.min` and `founded.max` for founding-year bounds from 1000 through 9999; the minimum cannot exceed the maximum.
## Company fields
The response contains `status`, `total_results`, `credits_used`, `data`, and `warnings`. Every company in `data` includes all of these fields:
| Field | Meaning |
| --- | --- |
| `domain` | Normalized company domain. |
| `name` | Company name; falls back to the domain when missing. |
| `description` | Company description. |
| `employee_count` | String, commonly an employee range rather than an exact headcount. |
| `country`, `city` | Company location. |
| `founded_year` | Integer founding year, or `null`. |
| `linkedin_url` | LinkedIn company profile URL. |
| `relevance_score` | Number or `null`; not a confidence percentage or guaranteed to be between 0 and 1. |
| `matched_domains` | Normalized reference domains that matched this company. |
Missing text fields are empty strings. Companies matching more reference domains appear first.
Check `warnings` for any reference companies that could not be searched. No matches returns an empty `data` array and costs zero credits.
## Credits
A request with `limit: 10` requires 5 available credits; `limit: 5000` requires 2,500. Insufficient available credits returns `402`. The final charge is based on the unique companies returned, and `credits_used` reports that amount.
Do not automatically retry this request. A search may complete even when you receive an error or no response, and repeating it can cause another charge.
## Timing and errors
Allow at least **100 seconds** for your client timeout. If a search times out, try fewer reference companies or a lower result limit.
A rate or concurrency limit returns `429`. Wait for the number of seconds in `Retry-After` when present. See [Rate limits](/api-reference/rate-limits).
## Next step
Use [Find people](/api-reference/find-people) to search for roles at matching companies, or [Find companies](/api-reference/find-companies) to search using firmographic filters instead of reference domains.
---
## Airsearch
Source: https://docs.airscale.io/api-reference/airsearch.md
Description: Research the web and return structured answers with Airsearch. Rate limit: 300 requests per minute per workspace.
Ask a research question and receive a sourced answer, with optional output fields shaped for your application.
The limit is 300 requests per minute per workspace. A `success` result costs 0.5 credits for every workspace; `not_found` and `timeout` are not charged. Credits reserved for a completed `not_found` or `timeout` result are returned.
Requested schema keys are optional and nullable. Structured numeric and boolean values are returned as strings when present, so parse them explicitly when your application requires native scalar types.
A timeout can return `200 OK` with `status: "timeout"` or `504 Gateway Timeout`. Narrow the prompt before retrying. For temporary `502` or `503` errors, retry with increasing delays and a fixed retry limit; contact support if errors persist.
## Next step
Use [Find companies](/api-reference/find-companies) when the research target should come from structured firmographic filters, or review [Rate limits](/api-reference/rate-limits) before adding parallel requests.
---
## Email finder
Source: https://docs.airscale.io/api-reference/email-finder.md
Description: Find a professional email address for one person. Rate limit: 3,000 requests per minute per workspace.
Identify one person by LinkedIn profile URL or by name and company, then return a verified professional email when one is found.
The limit is 3,000 requests per minute per workspace. A successful result costs 2 credits; `not_found` is not charged.
## Which inputs can I send?
All five fields belong to the same request. **You can send them together.** The examples describe minimum information, not mutually exclusive options.
| Information available | Fields to send |
| --- | --- |
| LinkedIn profile URL only | `linkedin_profile_url` |
| Person's name and company name | `first_name`, `last_name`, `company_name` |
| Person's name and company domain | `first_name`, `last_name`, `domain` |
| All of the above | Send all five fields together. |
Send a person's name as `first_name` and `last_name`; `full_name` is not a supported request field. Without a LinkedIn profile URL, both name fields and a company name or domain are required. Company name alone or a person's name alone does not meet the current API's minimum input requirement.
The success example includes all documented response fields. `provider` and `verifier` use placeholder labels; optional fields may be absent from a result.
For temporary `502` or `503` responses, use a limited number of retries with increasing delays. If errors persist, stop retrying and contact support. A client timeout does not confirm whether the request completed or was charged.
## Next step
Use [Bulk email finder](/api-reference/email-finder-(bulk)) when you need asynchronous results for up to 100 people.
---
## Bulk email finder
Source: https://docs.airscale.io/api-reference/email-finder-(bulk).md
Description: Find professional email addresses for a batch of people. Rate limit: 3,000 input items per minute per workspace.
Submit up to 100 people and receive one asynchronous professional-email result per item at your webhook.
The limit is 3,000 input items per minute per workspace. Each item with `status: "success"` costs 2 credits; misses and timeouts are not charged.
The acceptance response only confirms that the batch was queued. Processing continues after that response, and each item is delivered separately to `webhook_url`.
## Webhook callbacks
Every callback echoes `custom_id`. When the submitted value is omitted or `null`, Airscale uses that item's zero-based input index.
- A found email has `status: "success"`, the resolved `email`, `email_status: "valid"`, and the public `provider` and `verifier` labels.
- An item skipped after the remaining batch balance drops below 2 credits has `status: "error"`, `error: "insufficient_credits"`, and `email: null`.
- A miss or exhausted lookup has `status: "not_found"` or `status: "timeout"`, respectively, with `email: null`.
Return a `2xx` response promptly for every callback. Automatic webhook retries are not part of this operation's contract, so persist callbacks and use `custom_id` to reconcile expected and received results.
Add credits before submitting skipped items again.
## Next step
Use [Email finder](/api-reference/email-finder) for a synchronous single-person lookup, or review [Rate limits](/api-reference/rate-limits) before batching requests.
---
## Mobile finder
Source: https://docs.airscale.io/api-reference/mobile-finder.md
Description: Find a mobile phone number from a professional profile. Rate limit: 6,000 requests per minute per workspace.
Submit a LinkedIn person profile URL and return a mobile phone number when one is found.
The limit is 6,000 requests per minute per workspace. A successful result costs 40 credits; `not_found` is not charged.
## Phone numbers in the response
- `phone_numbers` is the primary phone number as a single string.
- `all_phone_numbers` is an array of normalized international phone numbers, with duplicates removed and the primary number first. It can contain just the primary number when no additional numbers are available.
- A `not_found` result returns `phone_numbers: null` and `all_phone_numbers: []`.
For temporary `502` or `503` responses, use a limited number of retries with increasing delays. If errors persist, stop retrying and contact support. A client timeout does not confirm whether the request completed or was charged.
## Next step
Use [Personal email](/api-reference/personal-email) to look for a personal address from the same profile, or [Reverse phone](/api-reference/reverse-phone) when the phone number is your starting point.
---
## Personal email
Source: https://docs.airscale.io/api-reference/personal-email.md
Description: Find a personal email address from a professional profile. Rate limit: 2,000 requests per minute per workspace.
Submit a LinkedIn person profile URL and return a personal email address when one is found.
The limit is 2,000 requests per minute per workspace. The minimum balance required to start is 3 credits. A successful result costs between 3 and 12 credits, depending on its source; `not_found` costs 0 credits.
A `502 Bad Gateway` response can occur after credits were charged. Check your balance before retrying that input to avoid paying again for the same result.
After checking your balance for a `502`, or for a temporary `503` response, use a limited number of retries with increasing delays. If errors persist, stop retrying and contact support. A client timeout does not confirm whether the request completed or was charged.
## Next step
Use [People URL finder](/api-reference/people-url-finder) when you have a name and company but no profile URL.
---
## Find hashed emails
Source: https://docs.airscale.io/api-reference/hashed-emails.md
Description: Turn a LinkedIn profile URL or a work email into SHA-256 hashed emails for ad audiences. Rate limit: 60 requests per rolling second per workspace.
Send a LinkedIn profile URL, a work email, or both. The operation returns the person's emails as SHA-256 hashes, ready to upload to Meta, Google, LinkedIn or TikTok as a customer list or matched audience. Raw email addresses are never returned.
A lookup costs 5 credits when at least one hashed email is found. Not found, validation failures, and lookup failures are not charged. The limit is 60 requests per rolling second per workspace.
## Send a person
| Field | Format |
| --- | --- |
| `linkedin_url` | A LinkedIn profile URL such as `https://www.linkedin.com/in/jane-doe-example`. Country subdomains, a missing `https://`, query strings and a trailing slash are accepted. Company pages are rejected. |
| `work_email` | The person's work email. It is trimmed and lowercased. |
At least one field is required. When both are sent, both are used to find the person. Any other body field returns `400` with `code: "invalid_input"`.
## Read a successful result
| Field | Meaning |
| --- | --- |
| `status` | `success` when at least one hashed email was found. |
| `linkedin_url` / `work_email` | The normalized inputs that were looked up. |
| `hashed_email` | The best-matching hash. Use it when you need one value per person. |
| `hashed_emails` | Every hashed email found, best match first. Each entry has `normalized_hash` (use this for ad uploads) and `original_hash`. |
| `hash_algorithm` | Always `sha256`. |
| `credits_used` | Always `5`. |
| `credits_remaining` | Remaining workspace credit balance. |
`normalized_hash` is the SHA-256 of the trimmed, lowercased email, which is the format ad platforms expect for hashed customer lists.
## Errors and retries
| Status | Meaning | Charged |
| --- | --- | --- |
| `400` | Invalid JSON, a body that is not an object, or an unsupported field. | No |
| `401` | Missing or invalid API key. | No |
| `403` | Insufficient credits. At least 5 credits are required before a lookup starts. | No |
| `404` | `status: "not_found"`: no hashed email was found for this person. | No |
| `413` | JSON body larger than 16 KiB. | No |
| `422` | `code: "invalid_input"`: no field sent, a LinkedIn URL that is not a profile URL, or an invalid email. | No |
| `429` | Workspace rate limit exceeded. | No |
| `502` | The lookup failed or returned an invalid result. | No |
| `503` | A service the lookup depends on is temporarily unavailable. | No result is returned |
| `504` | The lookup timed out. | No |
Correct the input before retrying a `400` or `422`. After `429`, retry in a later second. For temporary `502`, `503` or `504` responses, retry with increasing delays and a fixed retry limit.
## In the Airscale app
The same lookup is available as the **Find hashed emails** enrichment in your tables (Enrich & clean, under Enrich contact data). It costs 5 credits per row when a hash is found; the cell shows the best-matching hash and keeps every hash in its details.
## Next step
Review [Authentication](/api-reference/authentication) and [rate limits](/api-reference/rate-limits) before sending lookups in bulk.
---
## People URL finder
Source: https://docs.airscale.io/api-reference/people-url-finder.md
Description: Find a professional profile URL from person and company details. Rate limit: 6 requests per second per workspace.
Identify a person by first name, last name, and company, then return a matching professional profile URL when one is found.
The limit is 6 requests per second per workspace. A successful result costs 0.5 credits; `not_found` is not charged.
After a `429 Too Many Requests` response, retry in a later second with bounded exponential backoff. For temporary `502` or `503` responses, retry the same input with increasing delays and a fixed retry limit; contact support if errors persist.
## Next step
Pass the matched URL to [Email finder](/api-reference/email-finder) for professional email enrichment.
---
## People profile
Source: https://docs.airscale.io/api-reference/extract-people-profile.md
Description: Extract a structured person profile from a professional profile URL. Rate limit: 3,000 requests per minute per workspace.
Extract a structured person profile from a recognized LinkedIn URL, normally an `/in/` profile.
The limit is 3,000 requests per minute per workspace. The submitted URL selects the response schema and successful-call credit cost: `/in/` successes cost 1 credit by default, while `/company/` and `/school/` successes cost 0.5 credits. Workspace-specific pricing can differ, and unsuccessful requests are not charged.
## Request and response
Send a JSON body containing `linkedin_profile_url`. No other extraction settings are needed.
The response contains the available profile data. Fields may be missing or `null`, and their types can vary. The example illustrates one possible result; check the fields your integration uses before reading them.
## Errors and retries
A `404` means no profile was found. Check the URL before trying again. Correct the input for `400`, check your API key for `401`, and check access and credits for `403`.
For `429`, wait until the next minute before retrying. For temporary `502` or `503` responses, use a limited number of retries with increasing delays. If the errors persist, stop retrying and contact support. Unsuccessful requests are not charged; a lost response or client timeout does not confirm that the request failed.
## Next step
Use [Company profile](/api-reference/extract-company-profile) for the organization-focused guidance, or [Email finder](/api-reference/email-finder) to enrich a person profile.
---
## Company profile
Source: https://docs.airscale.io/api-reference/extract-company-profile.md
Description: Extract a structured company profile from a company profile URL. Rate limit: 3,000 requests per minute per workspace.
Extract a structured organization profile from a recognized LinkedIn `/company/` or `/school/` URL.
The limit is 3,000 requests per minute per workspace. The submitted URL selects the response schema and successful-call credit cost: `/company/` and `/school/` successes cost 0.5 credits, while `/in/` successes cost 1 credit by default. Workspace-specific pricing can differ, and unsuccessful requests are not charged.
## Request and response
Send a JSON body containing `linkedin_profile_url`. No other extraction settings are needed.
The response contains the available profile data. Fields may be missing or `null`, and their types can vary. The example illustrates one possible result; check the fields your integration uses before reading them.
## Errors and retries
A `404` means no profile was found. Check the URL before trying again. Correct the input for `400`, check your API key for `401`, and check access and credits for `403`.
For `429`, wait until the next minute before retrying. For temporary `502` or `503` responses, use a limited number of retries with increasing delays. If the errors persist, stop retrying and contact support. Unsuccessful requests are not charged; a lost response or client timeout does not confirm that the request failed.
## Next step
Use [People profile](/api-reference/extract-people-profile) for the person-focused guidance, or [Find companies](/api-reference/find-companies) to discover organizations first.
---
## Domain to LinkedIn
Source: https://docs.airscale.io/api-reference/domain-to-linkedin.md
Description: Find a LinkedIn company URL from a company domain. Rate limit: 180 requests per minute per workspace.
Submit one company domain and receive its LinkedIn company URL. The response contains only `linkedin_company_url`.
A successful lookup costs **0.5 credits**, charged after the lookup. No-result and failed lookups cost zero. The charge may appear later, including after a top-up if your balance is insufficient. The limit is **180 requests per minute per workspace**.
Use a current workspace API key from [Settings → API key](/api-reference/authentication). Keys from the previous dashboard are not supported by this endpoint; generate a current key before calling it.
## Domain input
Send only `domain`: a hostname such as `example.org`, without a scheme, path, or port. Uppercase and a leading `www.` are normalized. Extra body fields are rejected; the body limit is 4 KiB.
## Timeouts and retries
The lookup has a **120-second deadline**. Allow **130 seconds** in your client. Personal profile and school URLs are not returned.
Reuse the same `Idempotency-Key` for transport retries of the same domain. Keys are scoped to your workspace and this endpoint; responses replay for seven days without another lookup or charge. Without a key, every request is a new operation.
An in-flight duplicate returns `409` with `Retry-After: 2`; wait and retry with the same key. A key reused for a different domain, or an expired key, also returns `409` and needs a new key. After a completed transient failure, use a new key to start a fresh lookup. New operations can incur a new charge if successful.
Errors contain an `error` field. A `404` means no match was found; a `504` means the lookup timed out. Neither is charged. For `503`, follow the retry guidance above.
## Next step
Use [Extract company profile](/api-reference/extract-company-profile) to retrieve company details from the returned LinkedIn URL. That is a separate request with its own credit cost.
---
## Reverse email
Source: https://docs.airscale.io/api-reference/reverse-email.md
Description: Find a person profile from an email address. Rate limit: 25 requests per second per workspace.
Submit an email address and receive the matching person profile when one can be resolved.
The limit is 25 requests per second per workspace. A returned profile costs 2 credits. A miss returns the JSON string `"not found"`, not an object with a status field, and is not charged.
After a `429 Too Many Requests` response, retry in a later second with bounded exponential backoff. A `503` response is not charged. Retry the same email with increasing delays and a fixed retry limit; contact support if errors persist.
## Read the profile
A match returns a nested person record with **camelCase** keys. The name is under `profile` (`profile.firstName`, `profile.lastName`, `profile.headline`), not at the top level. The LinkedIn URL is in `url` and `link.linkedin`, work history is `positionGroups`, and the current employer is `company` (`company.summary.name`, `company.link.domain`). Fields can be `null` or absent. When the match comes from a fallback lookup, the record uses the flat fields of [People profile](/api-reference/extract-people-profile) instead, or contains only `url` and `identifier`.
## Next step
Use [Reverse phone](/api-reference/reverse-phone) when a phone number is the identifier you have for a person.
---
## Reverse phone
Source: https://docs.airscale.io/api-reference/reverse-phone.md
Description: Find a person profile from a phone number. Rate limit: 2,000 requests per minute per workspace.
Submit a phone number and receive the matching person profile when one can be resolved.
The limit is 2,000 requests per minute per workspace. A returned profile costs 10 credits; `not_found` and errors are not charged.
A `not_found` result can represent a true miss or lookup paths that were exhausted or failed. When a match is expected, make one bounded-backoff retry. If it persists, verify that you sent the intended normalized number before retrying again.
For temporary `502` or `503` responses, use a limited number of retries with increasing delays. If errors persist, stop retrying and contact support. A client timeout does not confirm whether the request completed or was charged.
## Read the profile
A match returns the same nested person record as [Reverse email](/api-reference/reverse-email), with **camelCase** keys such as `profile.firstName`, `link.linkedin`, and `positionGroups`. The response also has a `body` field holding a copy of the same record; read either one. When the match comes from a fallback lookup, the record uses the flat fields of [People profile](/api-reference/extract-people-profile) instead.
## Next step
Use [People profile](/api-reference/extract-people-profile) when you already have a professional profile URL and want the structured profile directly.
---
## Post likers
Source: https://docs.airscale.io/api-reference/post-likers.md
Description: Retrieve and enrich people who liked a LinkedIn post. Rate limit: 180 requests per fixed minute per workspace, shared by post-likers and post-commenters; pagination requests and retries count.
Retrieve one synchronous page of people who liked a LinkedIn post, with public profile fields enriched for each returned engagement.
With `enrich_profiles` omitted or `true`, reserve `limit × 0.2` credits and charge **0.2 credits per successfully enriched profile**. Unused slots and definitive `not_found` or `error` outcomes are refunded. Uncertain work keeps its reservation until the identical request is reconciled.
## Extraction-only mode
Set `enrich_profiles: false` to return available engagement fields without profile lookups. Rows use `profile_status: "not_enriched"`. This works with V1 and V2 workspace keys.
Extraction-only costs **1 credit per fresh native provider page**, including valid empty terminal pages. `limit` controls returned people; one response can consume several native pages. Cached remainder slices and identical same-key retries are free. Read `billing.credits_consumed` for the actual charge. V1 balances update asynchronously through its billing queue.
Keep `enrich_profiles: false` and the returned cursor for continuation; use a new key for the next page. A response can preserve paid rows with `retrieval.status: "partial"` and `stop_reason: "insufficient_credits"` or `"provider_failure"`. Keep those rows, billing and cursor. An uncertain `page_attempt_pending` outcome must retain the original body and key for reconciliation; starting fresh can repeat work and charges.
## Rate limit
The limit is **180 requests per minute per workspace**, shared by Post likers and [Post commenters](/api-reference/post-commenters), including different API keys for the same workspace. Pagination requests and retries each count toward this limit.
The counter uses a fixed minute window and resets at the next minute boundary. Requests above the limit receive HTTP `429` without starting the page or charging credits. Wait until the next minute, then retry the identical page with the same `Idempotency-Key` using bounded backoff. This is a request limit, not a guarantee of enrichment throughput; the maximum page size remains 25.
## Pagination
Omit `cursor` on the first request. When `pagination.next_cursor` is not `null`, send it unchanged with the same post URL, `limit`, and `enrich_profiles` mode to fetch the next page. The page size is 1–25 (default 25). New cursors expire after 10 minutes and are bound to the workspace, post, engagement type, page size, and enrichment mode.
Optional `retrieval` metadata contains `reported_total`, `returned_count`, `status`, and `stop_reason`, and can include `retrieved_total`. A `partial` status with `stop_reason: "provider_total_mismatch"` means fewer engagements could be retrieved than the post reports. A `provider_exhausted` status means there are no more pages available for this request; it does not guarantee that every LinkedIn engagement was accessible. Reported totals can change, and comment events are not the same count as unique authors. Public pagination does not promise every reply returned by the dashboard's background extraction.
## Safe retries
Supply an optional UUID in the `Idempotency-Key` header. Save that key together with the endpoint and exact request body before sending the request. Reuse the same key with the identical `post_url`, `limit`, `cursor`, and `enrich_profiles` mode if the response is lost or processing is uncertain. Use a new key for the next page.
The code examples read `AIRSCALE_PAGE_KEY` from your environment. Set it to a UUID once for each new page, and keep that value for every retry of that page. Replace the synthetic post URL and cursor with your own values.
Omitting the header remains supported. However, an independent retry without the original key can reserve credits again. When a pending or uncertain response includes `idempotency_key`, retain and send that returned key even if your first request omitted the header.
Completed enriched results remain replayable for 24 hours after completion, including after the input cursor expires. An expired cursor cannot fetch a new extraction-only page; an exact saved retry can finish an outstanding refund before returning `invalid_cursor`. A reservation for unresolved work does not automatically become a refund after 24 hours.
## Pending and error responses
A `202` response with `status: "pending"` and `code: "page_pending"` means the request did not finish within 90 seconds. The outcome is unconfirmed; processing may still be running or may not have started. Wait for `Retry-After` (15 seconds for this response), then resend the identical page with the returned `idempotency_key`. The body also supplies `retry_after_ms`.
| Response | Next action |
| --- | --- |
| `409 replay_in_progress` | Wait, then retry the identical page with the same key. |
| `409 replay_request_mismatch` | Restore the original request fields for that key. Use a new key only for intentionally different work. |
| `503 account_busy`, `rate_limited`, or `provider_unavailable` | Keep the page and key unchanged. Wait for the supplied delay and retry with bounded backoff. |
| `503 provider_page_unavailable` | Wait for the supplied delay, then retry the same cursor and key. |
| `503 account_restart_required` | Start again without a cursor and with a new key. Deduplicate results already received. |
| Other `502` or `503` responses carrying `idempotency_key` | Preserve the original body and returned key. Retry with bounded backoff; do not assume that an unconfirmed request was refunded. |
| `429 Too Many Requests` | Wait and retry the same page and key with bounded exponential backoff. |
If a cooldown outlasts an unfetched cursor, wait for the cooldown, then begin a fresh traversal without the cursor and with a new key. Deduplicate earlier results. A fresh traversal is new billable work. Saved work and completed replay results can still be recovered under the rules above.
## Avoid duplicate charges
Retry the same page with the same key to resume it without charging again for profiles already paid for. Keep that key until you receive a final result. Starting again with a new key is a new billable request.
## Next step
Use [Post commenters](/api-reference/post-commenters) for the other engagement type, or read the [post engagement workflow](/docs/likers-commenters) for the dashboard flow.
---
## Post commenters
Source: https://docs.airscale.io/api-reference/post-commenters.md
Description: Retrieve and enrich people who commented on a LinkedIn post. Rate limit: 180 requests per fixed minute per workspace, shared by post-likers and post-commenters; pagination requests and retries count.
Retrieve one synchronous page of people who commented on a LinkedIn post, with public profile fields enriched for each returned engagement.
With `enrich_profiles` omitted or `true`, reserve `limit × 0.2` credits and charge **0.2 credits per successfully enriched profile**. Unused slots and definitive `not_found` or `error` outcomes are refunded. Uncertain work keeps its reservation until the identical request is reconciled.
## Extraction-only mode
Set `enrich_profiles: false` to return available engagement fields without profile lookups. Rows use `profile_status: "not_enriched"`. This works with V1 and V2 workspace keys.
Extraction-only costs **1 credit per fresh native provider page**, including valid empty terminal pages. `limit` controls returned people; one response can consume several native pages. Cached remainder slices and identical same-key retries are free. Read `billing.credits_consumed` for the actual charge. V1 balances update asynchronously through its billing queue.
Keep `enrich_profiles: false` and the returned cursor for continuation; use a new key for the next page. A response can preserve paid rows with `retrieval.status: "partial"` and `stop_reason: "insufficient_credits"` or `"provider_failure"`. Keep those rows, billing and cursor. An uncertain `page_attempt_pending` outcome must retain the original body and key for reconciliation; starting fresh can repeat work and charges.
## Rate limit
The limit is **180 requests per minute per workspace**, shared by [Post likers](/api-reference/post-likers) and Post commenters, including different API keys for the same workspace. Pagination requests and retries each count toward this limit.
The counter uses a fixed minute window and resets at the next minute boundary. Requests above the limit receive HTTP `429` without starting the page or charging credits. Wait until the next minute, then retry the identical page with the same `Idempotency-Key` using bounded backoff. This is a request limit, not a guarantee of enrichment throughput; the maximum page size remains 25.
## Pagination
Omit `cursor` on the first request. When `pagination.next_cursor` is not `null`, send it unchanged with the same post URL, `limit`, and `enrich_profiles` mode to fetch the next page. The page size is 1–25 (default 25). New cursors expire after 10 minutes and are bound to the workspace, post, engagement type, page size, and enrichment mode.
Optional `retrieval` metadata contains `reported_total`, `returned_count`, `status`, and `stop_reason`, and can include `retrieved_total`. A `partial` status with `stop_reason: "provider_total_mismatch"` means fewer engagements could be retrieved than the post reports. A `provider_exhausted` status means there are no more pages available for this request; it does not guarantee that every LinkedIn engagement was accessible. Reported totals can change, and comment events are not the same count as unique authors. Public pagination does not promise every reply returned by the dashboard's background extraction.
## Safe retries
Supply an optional UUID in the `Idempotency-Key` header. Save that key together with the endpoint and exact request body before sending the request. Reuse the same key with the identical `post_url`, `limit`, `cursor`, and `enrich_profiles` mode if the response is lost or processing is uncertain. Use a new key for the next page.
The code examples read `AIRSCALE_PAGE_KEY` from your environment. Set it to a UUID once for each new page, and keep that value for every retry of that page. Replace the synthetic post URL and cursor with your own values.
Omitting the header remains supported. However, an independent retry without the original key can reserve credits again. When a pending or uncertain response includes `idempotency_key`, retain and send that returned key even if your first request omitted the header.
Completed enriched results remain replayable for 24 hours after completion, including after the input cursor expires. An expired cursor cannot fetch a new extraction-only page; an exact saved retry can finish an outstanding refund before returning `invalid_cursor`. A reservation for unresolved work does not automatically become a refund after 24 hours.
## Pending and error responses
A `202` response with `status: "pending"` and `code: "page_pending"` means the request did not finish within 90 seconds. The outcome is unconfirmed; processing may still be running or may not have started. Wait for `Retry-After` (15 seconds for this response), then resend the identical page with the returned `idempotency_key`. The body also supplies `retry_after_ms`.
| Response | Next action |
| --- | --- |
| `409 replay_in_progress` | Wait, then retry the identical page with the same key. |
| `409 replay_request_mismatch` | Restore the original request fields for that key. Use a new key only for intentionally different work. |
| `503 account_busy`, `rate_limited`, or `provider_unavailable` | Keep the page and key unchanged. Wait for the supplied delay and retry with bounded backoff. |
| `503 provider_page_unavailable` | Wait for the supplied delay, then retry the same cursor and key. |
| `503 account_restart_required` | Start again without a cursor and with a new key. Deduplicate results already received. |
| Other `502` or `503` responses carrying `idempotency_key` | Preserve the original body and returned key. Retry with bounded backoff; do not assume that an unconfirmed request was refunded. |
| `429 Too Many Requests` | Wait and retry the same page and key with bounded exponential backoff. |
If a cooldown outlasts an unfetched cursor, wait for the cooldown, then begin a fresh traversal without the cursor and with a new key. Deduplicate earlier results. A fresh traversal is new billable work. Saved work and completed replay results can still be recovered under the rules above.
## Avoid duplicate charges
Retry the same page with the same key to resume it without charging again for profiles already paid for. Keep that key until you receive a final result. Starting again with a new key is a new billable request.
## Next step
Use [Post likers](/api-reference/post-likers) for the other engagement type, or read the [post engagement workflow](/docs/likers-commenters) for the dashboard flow.
---
## Post search
Source: https://docs.airscale.io/api-reference/post-search.md
Description: Search LinkedIn posts by keywords, authors, companies, mentions, groups, content type, and date. Rate limit: 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.
Search LinkedIn posts and retrieve one synchronous page of up to 50 posts, each with its author, content, publication date, engagement counts, and image URLs. Rows are returned as found on LinkedIn, without profile enrichment.
Each successful non-empty request costs **1 credit**, whatever the number of posts returned. A successful empty page is not charged. Invalid input and failed requests are not charged. The workspace needs at least 1 credit to start a request.
## Authentication
Send your Airscale workspace API key as a Bearer token. Both V1 and V2 workspace API keys are accepted.
## Filters
Provide `keywords` (up to 200 characters) or at least one author, mention, or group filter. All filters you send combine, so a post must match every one of them.
| Field | Matches |
| --- | --- |
| `keywords` | Words in the post. |
| `author_keywords` | Words in the authors' profiles (up to 200 characters). |
| `author_profile_urls` | Posts written by these profiles (`linkedin.com/in/...`). |
| `author_company_urls` | Posts published by these company pages (URL or numeric ID). |
| `author_employer_company_urls` | Posts whose authors work at these companies (URL or numeric ID). |
| `author_industry_ids` | Authors' company industry, as numeric LinkedIn industry IDs. |
| `mentioning_profile_urls` | Posts that mention these profiles. |
| `mentioning_company_urls` | Posts that mention these companies (URL or numeric ID). |
| `group_url` | Posts inside one LinkedIn group (`linkedin.com/groups/...` or numeric ID). |
| `content_type` | `videos`, `images`, `live_videos`, `documents`, `collaborative_articles`, or `jobs`. |
| `sort_by` | `date` (default) or `relevance`. |
| `posted_within` | `24h`, `week`, or `month`, filtered by LinkedIn; or `1h`, `3months`, `6months`, or `year`, which require `sort_by: "date"`. |
List filters accept a string or an array of up to 10 values. Unknown fields are rejected with `400`. With `posted_within` set to `1h`, `3months`, `6months`, or `year`, the period is applied to each fetched page, so a page can hold fewer than 50 posts. LinkedIn search can return fewer posts per author than that author's full feed; use [Profile posts](/api-reference/profile-posts) or [Company posts](/api-reference/company-posts) to read one author's feed.
Each post row includes `feed_context`, LinkedIn's feed label when the row is not a plain post by the author, such as `"Example Person reposted this"` or `"Example Company collaborated on this"`. It is `null` for a plain post.
`content_type` names the kind of post: `text`, `image`, `multi_image`, `video`, `document` (a PDF carousel), `poll`, `article` (an article or link preview), or `repost` (a repost with the reposter's own commentary). `media` holds the details: `video_url` and `thumbnail_url` for a video; `title`, `page_count`, `cover_image_urls`, and `document_url` for a document; `question`, `options` with `votes`, `total_votes`, and `closed` for a poll; `url`, `title`, `subtitle`, `description`, and `thumbnail_url` for an article. It is `null` for text, picture, and repost rows; pictures are in `image_urls`. For a `repost` row, `reposted_post` holds the shared post's `post_url`, `post_id`, `content_type`, `media`, and `image_urls`. Media links are signed LinkedIn links that expire, so download them soon after the request.
## Rate limit
The limit is **180 requests per minute per workspace** for Post search, including requests made with different API keys for the same workspace. [Profile comments](/api-reference/profile-comments), [Comment likers](/api-reference/comment-likers), [Profile posts](/api-reference/profile-posts), and [Company posts](/api-reference/company-posts) each have their own separate 180-request allowance. Pagination requests and retries count toward the limit.
The counter uses a fixed minute window and resets at the next minute boundary. Requests above the limit receive HTTP `429` and are not charged. When LinkedIn content capacity is busy for all workspaces, the response is a free `503` with `Retry-After: 5`.
## Pagination
Omit `cursor` on the first request. When `pagination.next_cursor` is not `null`, send it unchanged together with the same filters to fetch the next page. A cursor sent with different filters, or to another endpoint, returns `400`. `pagination.total` is the number of matching posts reported by LinkedIn, or `null` when unavailable.
## Retries
This endpoint does not accept an idempotency key. Retrying a request fetches the page again; a non-empty page is charged again. Retry only responses that were not charged:
| Response | Next action |
| --- | --- |
| `400 Bad Request` | Correct the body or cursor. The `message` field names the problem. |
| `403 Forbidden` | Add credits to the workspace before retrying. |
| `413 Payload Too Large` | Keep the JSON body under 16 KiB. |
| `429 Too Many Requests` | Wait for the next minute boundary, then retry with bounded exponential backoff. |
| `502 Bad Gateway` or `504 Gateway Timeout` | Retry with increasing delays and a fixed retry limit. |
| `503 Service Unavailable` | Wait for `Retry-After` when present, then retry with bounded backoff. |
## Next step
Use [Profile comments](/api-reference/profile-comments) to see what a post author comments on, or [Post likers](/api-reference/post-likers) to retrieve enriched people who liked a post.
---
## Profile comments
Source: https://docs.airscale.io/api-reference/profile-comments.md
Description: Retrieve the comments a LinkedIn profile wrote, each with the post it was left on. Rate limit: 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.
Retrieve one synchronous page of comments written by a LinkedIn profile, with each comment's text, date, like and reply counts, and the post it was left on. Rows are returned as found on LinkedIn, without profile enrichment.
Each successful non-empty request costs **1 credit**, whatever the number of comments returned. A successful empty page is not charged. Invalid input and failed requests are not charged. The workspace needs at least 1 credit to start a request.
## Authentication
Send your Airscale workspace API key as a Bearer token. Both V1 and V2 workspace API keys are accepted.
## Request fields
Send `profile_url` as a LinkedIn profile URL (`linkedin.com/in/...`). Optionally set `posted_within` to `24h`, `week`, or `month` to return only recent comments. Unknown fields are rejected with `400`.
## Rate limit
The limit is **180 requests per minute per workspace** for Profile comments, including requests made with different API keys for the same workspace. [Post search](/api-reference/post-search), [Comment likers](/api-reference/comment-likers), [Profile posts](/api-reference/profile-posts), and [Company posts](/api-reference/company-posts) each have their own separate 180-request allowance. Pagination requests and retries count toward the limit.
The counter uses a fixed minute window and resets at the next minute boundary. Requests above the limit receive HTTP `429` and are not charged. When LinkedIn content capacity is busy for all workspaces, the response is a free `503` with `Retry-After: 5`.
## Pagination
A page holds up to about 100 comments. Omit `cursor` on the first request. When `pagination.next_cursor` is not `null`, send it unchanged together with the same `profile_url` and `posted_within` to fetch the next page. A cursor sent with different fields, or to another endpoint, returns `400`.
`pagination.total` is always `null` for this endpoint because no reliable total is reported. Use `has_more` and `next_cursor` to decide whether to continue.
## Retries
This endpoint does not accept an idempotency key. Retrying a request fetches the page again; a non-empty page is charged again. Retry only responses that were not charged:
| Response | Next action |
| --- | --- |
| `400 Bad Request` | Correct the body or cursor. The `message` field names the problem. |
| `403 Forbidden` | Add credits to the workspace before retrying. |
| `413 Payload Too Large` | Keep the JSON body under 16 KiB. |
| `429 Too Many Requests` | Wait for the next minute boundary, then retry with bounded exponential backoff. |
| `502 Bad Gateway` or `504 Gateway Timeout` | Retry with increasing delays and a fixed retry limit. |
| `503 Service Unavailable` | Wait for `Retry-After` when present, then retry with bounded backoff. |
## Next step
Send a returned `comment_url` to [Comment likers](/api-reference/comment-likers) to see who reacted to that comment.
---
## Comment likers
Source: https://docs.airscale.io/api-reference/comment-likers.md
Description: Retrieve the people who reacted to one LinkedIn comment. Rate limit: 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.
Retrieve one synchronous page of up to 100 people who reacted to a LinkedIn comment, with their name, headline, profile picture, and reaction type. Rows are returned as found on LinkedIn, without profile enrichment.
Each successful non-empty request costs **1 credit**, whatever the number of people returned. A successful empty page is not charged. Invalid input and failed requests are not charged. The workspace needs at least 1 credit to start a request.
## Authentication
Send your Airscale workspace API key as a Bearer token. Both V1 and V2 workspace API keys are accepted.
## Request fields
Send `comment_url` as a LinkedIn URL that identifies one comment: it must contain a `urn:li:comment:(...)` reference, for example in a `commentUrn` query parameter. The `comment_url` values returned by [Profile comments](/api-reference/profile-comments) can be sent unchanged. Unknown fields are rejected with `400`.
Each person's `linkedin_url` can be a member-ID URL (`/in/ACoAA...`) rather than a vanity URL. Both forms identify the same LinkedIn profile.
## Rate limit
The limit is **180 requests per minute per workspace** for Comment likers, including requests made with different API keys for the same workspace. [Post search](/api-reference/post-search), [Profile comments](/api-reference/profile-comments), [Profile posts](/api-reference/profile-posts), and [Company posts](/api-reference/company-posts) each have their own separate 180-request allowance. Pagination requests and retries count toward the limit.
The counter uses a fixed minute window and resets at the next minute boundary. Requests above the limit receive HTTP `429` and are not charged. When LinkedIn content capacity is busy for all workspaces, the response is a free `503` with `Retry-After: 5`.
## Pagination
Omit `cursor` on the first request. When `pagination.next_cursor` is not `null`, send it unchanged together with the same `comment_url` to fetch the next page. A cursor sent with a different comment, or to another endpoint, returns `400`. `pagination.total` is the number of reactions reported by LinkedIn, or `null` when unavailable.
## Retries
This endpoint does not accept an idempotency key. Retrying a request fetches the page again; a non-empty page is charged again. Retry only responses that were not charged:
| Response | Next action |
| --- | --- |
| `400 Bad Request` | Correct the body or cursor. The `message` field names the problem. |
| `403 Forbidden` | Add credits to the workspace before retrying. |
| `413 Payload Too Large` | Keep the JSON body under 16 KiB. |
| `429 Too Many Requests` | Wait for the next minute boundary, then retry with bounded exponential backoff. |
| `502 Bad Gateway` or `504 Gateway Timeout` | Retry with increasing delays and a fixed retry limit. |
| `503 Service Unavailable` | Wait for `Retry-After` when present, then retry with bounded backoff. |
## Next step
Use [Post likers](/api-reference/post-likers) or [Post commenters](/api-reference/post-commenters) to retrieve enriched people who engaged with a whole post.
---
## Profile posts
Source: https://docs.airscale.io/api-reference/profile-posts.md
Description: Retrieve a LinkedIn profile's feed, newest first, including the person's posts and reposts. Rate limit: 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.
Retrieve one synchronous page of up to 50 posts from a LinkedIn profile's feed, newest first, including the person's own posts and their reposts. Each post carries its author, content, publication date, engagement counts, and image URLs. Rows are returned as found on LinkedIn, without profile enrichment.
Each successful non-empty request costs **1 credit**, whatever the number of posts returned. A successful empty page is not charged. Invalid input and failed requests are not charged. The workspace needs at least 1 credit to start a request.
## Authentication
Send your Airscale workspace API key as a Bearer token. Both V1 and V2 workspace API keys are accepted.
## Request fields
Send `profile_url` as a LinkedIn profile URL (`linkedin.com/in/...`). Optionally set `posted_within` to `1h`, `24h`, `week`, `month`, `3months`, `6months`, or `year` to return only recent posts. Unknown fields are rejected with `400`.
The period is applied to each fetched page, so a page can hold fewer than 50 posts. Pagination stops at the first page with no post inside the period.
Rows use the same post fields as [Post search](/api-reference/post-search). A repost keeps the original post's `author`; `feed_context` then holds LinkedIn's feed label, such as `"Example Person reposted this"`. It is `null` for a plain post by the profile.
## Rate limit
The limit is **180 requests per minute per workspace** for Profile posts, including requests made with different API keys for the same workspace. [Company posts](/api-reference/company-posts), [Post search](/api-reference/post-search), [Profile comments](/api-reference/profile-comments), and [Comment likers](/api-reference/comment-likers) each have their own separate 180-request allowance. Pagination requests and retries count toward the limit.
The counter uses a fixed minute window and resets at the next minute boundary. Requests above the limit receive HTTP `429` and are not charged. When LinkedIn content capacity is busy for all workspaces, the response is a free `503` with `Retry-After: 5`.
## Pagination
Omit `cursor` on the first request. When `pagination.next_cursor` is not `null`, send it unchanged together with the same `profile_url` and `posted_within` to fetch the next page. A cursor sent with different fields, or to another endpoint, returns `400`.
`pagination.total` is always `null` for this endpoint because no reliable total is reported. Use `has_more` and `next_cursor` to decide whether to continue.
## Retries
This endpoint does not accept an idempotency key. Retrying a request fetches the page again; a non-empty page is charged again. Retry only responses that were not charged:
| Response | Next action |
| --- | --- |
| `400 Bad Request` | Correct the body or cursor. The `message` field names the problem. |
| `403 Forbidden` | Add credits to the workspace before retrying. |
| `413 Payload Too Large` | Keep the JSON body under 16 KiB. |
| `429 Too Many Requests` | Wait for the next minute boundary, then retry with bounded exponential backoff. |
| `502 Bad Gateway` or `504 Gateway Timeout` | Retry with increasing delays and a fixed retry limit. |
| `503 Service Unavailable` | Wait for `Retry-After` when present, then retry with bounded backoff. |
## Next step
Use [Profile comments](/api-reference/profile-comments) to see what the same profile comments on, or [Post likers](/api-reference/post-likers) to retrieve enriched people who liked one of the returned posts.
---
## Company posts
Source: https://docs.airscale.io/api-reference/company-posts.md
Description: Retrieve a LinkedIn company page's feed, newest first. Rate limit: 180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.
Retrieve one synchronous page of up to 50 posts from a LinkedIn company page's feed, newest first. Each post carries its author, content, publication date, engagement counts, and image URLs. Rows are returned as found on LinkedIn, without profile enrichment.
Each successful non-empty request costs **1 credit**, whatever the number of posts returned. A successful empty page is not charged. Invalid input and failed requests are not charged. The workspace needs at least 1 credit to start a request.
## Authentication
Send your Airscale workspace API key as a Bearer token. Both V1 and V2 workspace API keys are accepted.
## Request fields
Send `company_url` as a LinkedIn company URL (`linkedin.com/company/...`) or a numeric LinkedIn company ID. Optionally set `posted_within` to `1h`, `24h`, `week`, `month`, `3months`, `6months`, or `year` to return only recent posts. Unknown fields are rejected with `400`.
The period is applied to each fetched page, so a page can hold fewer than 50 posts. Pagination stops at the first page with no post inside the period.
Rows use the same post fields as [Post search](/api-reference/post-search). When a row is not a plain post by the company, `feed_context` holds LinkedIn's feed label, such as `"Example Company collaborated on this"`; otherwise it is `null`.
## Rate limit
The limit is **180 requests per minute per workspace** for Company posts, including requests made with different API keys for the same workspace. [Profile posts](/api-reference/profile-posts), [Post search](/api-reference/post-search), [Profile comments](/api-reference/profile-comments), and [Comment likers](/api-reference/comment-likers) each have their own separate 180-request allowance. Pagination requests and retries count toward the limit.
The counter uses a fixed minute window and resets at the next minute boundary. Requests above the limit receive HTTP `429` and are not charged. When LinkedIn content capacity is busy for all workspaces, the response is a free `503` with `Retry-After: 5`.
## Pagination
Omit `cursor` on the first request. When `pagination.next_cursor` is not `null`, send it unchanged together with the same `company_url` and `posted_within` to fetch the next page. A cursor sent with different fields, or to another endpoint, returns `400`. `pagination.total` is the number of posts reported by LinkedIn for the company page, or `null` when unavailable.
## Retries
This endpoint does not accept an idempotency key. Retrying a request fetches the page again; a non-empty page is charged again. Retry only responses that were not charged:
| Response | Next action |
| --- | --- |
| `400 Bad Request` | Correct the body or cursor. The `message` field names the problem. |
| `403 Forbidden` | Add credits to the workspace before retrying. |
| `413 Payload Too Large` | Keep the JSON body under 16 KiB. |
| `429 Too Many Requests` | Wait for the next minute boundary, then retry with bounded exponential backoff. |
| `502 Bad Gateway` or `504 Gateway Timeout` | Retry with increasing delays and a fixed retry limit. |
| `503 Service Unavailable` | Wait for `Retry-After` when present, then retry with bounded backoff. |
## Next step
Use [Post likers](/api-reference/post-likers) or [Post commenters](/api-reference/post-commenters) to retrieve enriched people who engaged with one of the returned posts.
---
## Create a job-change monitor
Source: https://docs.airscale.io/api-reference/job-change-monitors/create.md
Description: Monitor up to 10,000 personal LinkedIn profiles for employer changes with one schedule, one results table and an optional webhook. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
Create an active monitor for one to 10,000 personal LinkedIn profiles with [Bearer authentication](/api-reference/authentication). All profiles belong to one monitor ID, with one frequency, one results table and an optional webhook. Each successful request creates a new monitor, and creation has no idempotency key. If a network failure leaves the result unknown, [list your monitors](/api-reference/job-change-monitors/list) and reconcile before retrying; blindly retrying can create a second monitor with separate charges.
The `frequency` can be `weekly`, `every_30_days`, or `every_90_days` (default `weekly`). If you provide `webhook_url`, store the returned `signing_secret` immediately; it is returned only once. If you lose it, [rotate it](/api-reference/job-change-monitors/update) on the existing monitor instead of creating a new one.
Airscale canonicalizes LinkedIn URLs, which must identify a personal `/in/` profile, and preserves each profile's optional `external_id` in later events. Monitoring admission checks that job-change monitoring is available and that the workspace can pay for a full check before accepting the monitor.
## Monitor 10,000 profiles
1. Prepare a JSON request with `name`, your chosen `frequency`, an optional `webhook_url`, and a `profiles` array containing up to 10,000 personal LinkedIn URLs. Each entry can include an `external_id` from your CRM.
2. Send it to `POST /v1/job-change-monitors`. The `202 Accepted` response contains `monitor`, `profiles`, `duplicates`, `skipped_duplicate_count`, `signing_secret`, and `signing_secret_warning`. Save `monitor.id` and, if a webhook is configured, the one-time `signing_secret`.
3. Use that same ID with [Get a monitor](/api-reference/job-change-monitors/get) to inspect profile statuses and the monitor's check timestamps. Checks run asynchronously and a large check can take time; `202` confirms acceptance, not completion.
4. After a profile's first successful check establishes its baseline, later employer changes appear in [List job-change events](/api-reference/job-change-monitors/events), are appended to the monitor's results table, and are sent to the configured webhook. The first baseline does not emit a job-change event.
Monitoring costs **0.1 credit per profile per check**. A full check of 10,000 profiles costs up to 1,000 credits. Failed, not-found, and no-current-employer lookups are refunded. A check the workspace cannot pay for in full is not started: the monitor then reports `run_block_reason: "insufficient_credits"` with `run_block_detail` until a later check starts.
## Results table
Each monitor owns a regular Airscale results table. Every new job-change event appends a row; the initial baseline does not. The monitor reports `results_table_id`, `results_status` (`pending`, `ready`, or `blocked`) and `results_error`. If the table is deleted or full, new rows stay pending and `results_error` explains why. Deleting the monitor keeps its results table.
## Profiles already watched by another monitor
`duplicates` lists profiles that another monitor in the workspace already watches, with `linkedin_url`, `monitor_id`, and `monitor_name`. Each monitor checks and charges its profiles separately. Send `"skip_duplicates": true` to leave them out; `skipped_duplicate_count` reports how many were skipped. A request whose every profile is a duplicate is rejected with `422 all_profiles_duplicated`.
## Request size and profile limits
One monitor supports at most **10,000 active profiles**. Create and [Add profiles](/api-reference/job-change-monitors/profiles/add) each accept up to **10,000 profile entries per request**, while the monitor's resulting active count must stay within 10,000.
The complete JSON request body must be at most **8 MiB (8,388,608 bytes)** in UTF-8. A larger body returns `413`. Long URLs, `external_id` values, and JSON formatting all count toward this limit. If your payload is too large, create the monitor with a smaller set, then add the remaining profiles in smaller requests to the same `monitor.id`.
## Webhook URL rules
`webhook_url` must be a public HTTPS URL without embedded credentials. Other protocols, internal hostnames, and private or reserved addresses are rejected with `422 invalid_monitor` before the monitor is created. Destinations are checked again when sending; a hostname that later resolves to a blocked address cannot receive deliveries.
## Verify webhook signatures
Airscale sends each event as a JSON `POST` to `webhook_url`. The body has `type: "job_change.detected"` plus the same fields as an event from [List job-change events](/api-reference/job-change-monitors/events) without `read_at` or `webhook`: `id`, `monitor_id`, `profile_id`, `linkedin_url`, `external_id`, `detected_at`, `previous_employer`, and `new_employer` (each with `identity` and `name`).
The request includes `X-Airscale-Event: job_change.detected`, `X-Airscale-Event-Id`, `X-Airscale-Timestamp`, and `X-Airscale-Signature: sha256=`. Compute HMAC-SHA256 with the `signing_secret` over `.`, compare it in constant time, and reject timestamps more than five minutes from the current time. Return a 2xx response only after durable handling.
Airscale makes up to five attempts with exponential backoff. `408`, `425`, `429`, and `5xx` responses are retried; other definitive responses fail permanently, and timeouts or dropped connections are marked `uncertain` because the request may have been received. Retries keep the same event ID and send `Idempotency-Key: job-change-event:`, so process events idempotently. Use [Redeliver a webhook](/api-reference/job-change-monitors/events/redeliver) to send a failed or uncertain event again.
## Next step
Use [List job-change monitors](/api-reference/job-change-monitors/list) to confirm the monitor's status and next check time.
---
## List job-change monitors
Source: https://docs.airscale.io/api-reference/job-change-monitors/list.md
Description: List the monitors in a workspace with their schedule, results table, and active-profile and unread-event counts. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
List every job-change monitor in the authenticated workspace. Each monitor includes its status, schedule, results-table state, webhook state, active profile count, and unread event count.
This operation is read-only and does not change schedules or consume monitoring credits. It never returns a webhook signing secret.
Use the monitor `id` returned here with the detail, update, profile, and event operations. A paused monitor remains in the list so you can resume it later. If a create request's response was lost, list monitors before deciding whether to create another.
## Next step
Open [Get a monitor](/api-reference/job-change-monitors/get) for its profiles and latest events.
---
## Get a job-change monitor
Source: https://docs.airscale.io/api-reference/job-change-monitors/get.md
Description: Retrieve one monitor, its profiles, and its latest events. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
Retrieve one monitor by `monitor_id`. The response contains all profiles, including soft-removed profiles, and up to the latest 200 events ordered newest first.
Use the profile `status` and `removed_at` fields to distinguish an active profile from one removed from future checks. Profile `status` is `pending`, `baseline`, `checked`, `unavailable`, `failed`, or `removed`. Historical events remain available after a profile is removed.
The monitor object reports `next_check_at` and `last_successful_check_at` as ISO 8601 timestamps. A paused monitor has no next check scheduled. When a check could not start or stopped early, `run_block_reason` (for example `insufficient_credits`) and `run_block_detail` explain why; they clear when a later check starts. `results_table_id`, `results_status` and `results_error` describe the results table that receives one row per new event.
A monitor can contain up to 10,000 active profiles under the same schedule and webhook. Checks run asynchronously and large checks can take time. Internally, profiles are processed in batches with durable progress, so a retried check keeps its billing identity and does not charge a profile twice. Profiles added after a check starts join the next check. A profile's first successful check establishes its baseline without emitting a job-change event.
## Next step
Use [List job-change events](/api-reference/job-change-monitors/events) when you need cursor pagination beyond the latest 200 events or webhook delivery receipts.
---
## Update a job-change monitor
Source: https://docs.airscale.io/api-reference/job-change-monitors/update.md
Description: Rename a monitor, change its frequency, pause or resume checks, change its webhook, or rotate the signing secret. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
Update one or more monitor fields with `PATCH`. The body accepts `name`, `frequency`, `action` (`pause` or `resume`), `webhook_url`, and `rotate_signing_secret: true`, and they can be combined in one request, for example `{"name": "CRM champions (Q4)", "action": "pause"}`.
The response returns the complete updated monitor, including its active profile and unread event counts.
## Pause and resume
Pausing stops future checks and clears `next_check_at`. Resuming requires at least one active profile and reruns monitoring admission, including the credit check for the next full check; an empty monitor returns `422 no_active_profiles` and a workspace that cannot pay returns `402 insufficient_credits`.
A resumed monitor that has never completed a check is due immediately. Otherwise its next check is one period after the last completed check, or immediately if that time has already passed.
## Change the frequency
Changing the frequency of an active monitor reschedules the next check from its last completed check, never earlier than now. A monitor that has not completed a check keeps its pending first check, and a paused monitor stays paused until resumed. Recurring checks are anchored on the time the previous check became due, so long checks do not shift the schedule. Renaming a monitor also renames its results table while the table still has its generated ` — Job changes` title.
## Change the webhook or recover a lost signing secret
`webhook_url` accepts a public HTTPS URL without embedded credentials, or `null`. Invalid URLs return `422 invalid_monitor_update`. These fields work independently of name, frequency, and pause or resume.
- Setting or changing the URL generates a fresh signing secret.
- `{"rotate_signing_secret": true}` alone rotates the secret of the current webhook. Rotating without an enabled webhook returns `422 webhook_not_configured`; combining rotation with `webhook_url: null` returns `422 invalid_monitor_update`.
- `{"webhook_url": null}` disables the webhook and clears its stored secret.
- Setting the same URL without rotation keeps the existing secret and returns no secret.
When a new secret is generated, the response includes `signing_secret` and `signing_secret_warning`. Store the secret immediately; list and get never return it. If the response is lost, rotate again and install the newest secret.
Changing the URL, disabling, or rotating cancels pending and retryable deliveries made with the previous configuration (`error_code: "webhook_configuration_changed"`); delivered and failed receipts stay visible. When a send is in flight, the request returns `409 webhook_delivery_in_progress` without changing anything. Wait for the delivery to settle, retry the edit, and make your receiver accept the new secret after rotation.
Webhook changes keep the monitor ID, baselines, history, results table, and schedule. They do not check profiles or spend credits.
## Next step
Use [Add profiles](/api-reference/job-change-monitors/profiles/add) before resuming a monitor with no active profiles.
---
## Delete a job-change monitor
Source: https://docs.airscale.io/api-reference/job-change-monitors/delete.md
Description: Permanently remove a monitor and its stored monitoring data. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
Delete a monitor by `monitor_id`. This permanently removes the monitor, its profile baselines, and its events from the workspace. The monitor's results table is kept.
Deletion cannot be undone. [Pause the monitor](/api-reference/job-change-monitors/update) to stop checks temporarily, or remove individual profiles when you need to stop checking a contact while retaining its event history.
The operation returns `{ "ok": true }` after the monitor and its cascaded data are deleted.
## Next step
Use [List job-change monitors](/api-reference/job-change-monitors/list) to verify the monitor no longer appears.
---
## Add profiles to a job-change monitor
Source: https://docs.airscale.io/api-reference/job-change-monitors/profiles/add.md
Description: Add up to 10,000 personal LinkedIn profiles per request while preserving existing baselines. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
Add one to 10,000 personal LinkedIn profiles per request to an existing monitor. Airscale ignores a URL that is already active in the same monitor and reports how many profiles were actually added. All profiles keep the existing monitor ID, frequency, and webhook.
Adding a URL after it was removed creates a new profile and a new baseline. The previous profile's events remain associated with its original profile ID.
The `201` response includes the profile records, `added_profile_count`, the monitor's resulting `active_profile_count`, `duplicates`, and `skipped_duplicate_count`. `duplicates` lists profiles that another monitor in the workspace already watches; each monitor checks and charges them separately. Send `"skip_duplicates": true` to leave them out. A request whose every profile is a duplicate returns `422 all_profiles_duplicated`.
The 10,000-profile limit applies to the monitor's active profiles after adding new URLs; exceeding it returns `422 profile_limit_reached`. For example, a monitor with 9,000 active profiles can accept 1,000 more distinct active profiles.
The complete JSON request body must fit within **8 MiB (8,388,608 bytes)** in UTF-8; larger bodies return `413`. Split a larger payload into smaller add requests to the same monitor, keeping its total at or below 10,000 active profiles.
Checks run asynchronously. Profiles added while a check is running join the next check. A new profile's first successful check establishes its baseline without emitting a job-change event. Monitoring costs **0.1 credit per profile per check**, using the monitor's weekly, every-30-days, or every-90-days schedule.
## Next step
Use [Get a monitor](/api-reference/job-change-monitors/get) to inspect each profile's baseline and check status.
---
## Remove a profile from a job-change monitor
Source: https://docs.airscale.io/api-reference/job-change-monitors/profiles/remove.md
Description: Stop checking one profile while preserving its event history. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
Soft-remove one profile with its `monitor_id` and `profile_id`. The profile no longer participates in future checks, but its record and event history remain available.
To monitor the same LinkedIn URL again, call [Add profiles](/api-reference/job-change-monitors/profiles/add). Airscale creates a new profile ID and baseline instead of reusing the removed history.
The returned profile has `status: "removed"` and a `removed_at` timestamp. Removing a profile does not pause the monitor or affect its other active profiles. Removing a profile that is already removed returns `404 profile_not_found`.
## Next step
Use [List job-change events](/api-reference/job-change-monitors/events) to review the retained history.
---
## List job-change events
Source: https://docs.airscale.io/api-reference/job-change-monitors/events.md
Description: Read cursor-paginated employer-change events and their webhook delivery receipts for a monitor. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
List job-change events for one monitor, newest first. Set `limit` from 1 to 100 (default 50); when `next_cursor` is not `null`, send that value unchanged as `cursor` on the next request. A malformed cursor returns `422 invalid_event_cursor`.
An event is created only when a checked profile's employer identity changes. The event includes your `external_id` when one was supplied for the profile.
Events include the previous and new employer identities and names, the detection time, and `read_at`. This endpoint is also the durable fallback when webhook delivery is delayed or unavailable.
## Webhook delivery receipts
Each event carries a `webhook` object, or `null` when no delivery receipt exists. `status` is `pending`, `sending`, `retryable`, `sent`, `failed`, `uncertain`, or `cancelled`, with `attempt_count`, `last_attempt_at`, `sent_at`, and `error_code` (for example `webhook_http_410` or `webhook_configuration_changed`). `uncertain` means a timeout or dropped connection: the request may have been received. Use [Redeliver a webhook](/api-reference/job-change-monitors/events/redeliver) to send a `failed` or `uncertain` event again.
## Next step
Use [Mark an event as read](/api-reference/job-change-monitors/events/read) after your application has processed an event.
---
## Mark a job-change event as read
Source: https://docs.airscale.io/api-reference/job-change-monitors/events/read.md
Description: Acknowledge one job-change event after processing it. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
Mark one event as read after your integration has handled it. The response returns the event with its `read_at` timestamp, and the monitor's unread count decreases.
The request accepts an empty body or `{}`. A body that is present but not valid JSON returns `400`.
Treat the event ID as the durable acknowledgement key. Webhook retries use the same event ID, so processing it idempotently prevents duplicate downstream work.
An event can be marked read once. Marking an event that is already read returns `404 event_not_found`, so treat that response as already acknowledged when you know the event exists.
Reading an event does not delete it. You can still retrieve it through [List job-change events](/api-reference/job-change-monitors/events) or the monitor detail response.
## Next step
Review [Create a job-change monitor](/api-reference/job-change-monitors/create) for webhook setup and signature verification.
---
## Redeliver a job-change webhook
Source: https://docs.airscale.io/api-reference/job-change-monitors/events/redeliver.md
Description: Send one event's webhook again after a failed or unconfirmed delivery. Rate limit: 120 requests per fixed minute per API key, shared by all job-change monitor endpoints.
Job-change monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and monitoring credits belong to the V2 workspace associated with the key.
Re-arm one event's webhook after a `failed` or `uncertain` attempt. Airscale resets the attempt count and sends the event again to the monitor's **current** webhook URL, signed with its current signing secret. Redelivery never replays the paid profile check and spends no credits.
The request accepts an empty body or `{}`. The `202` response returns `event_id` and the new `webhook` receipt, normally `pending` with `attempt_count: 0`. If a send for the event is already in flight, its `sending` receipt is returned unchanged.
The event keeps the same ID and `Idempotency-Key: job-change-event:` header. Your receiver may already have processed an `uncertain` delivery, so handle the event idempotently.
A monitor without a webhook returns `422 webhook_not_configured`. Track the outcome through the `webhook` receipt in [List job-change events](/api-reference/job-change-monitors/events).
## Next step
Use [Update a job-change monitor](/api-reference/job-change-monitors/update) to change the webhook URL or rotate its signing secret before redelivering.
---
## Create a new hire monitor
Source: https://docs.airscale.io/api-reference/new-hire-monitors/create.md
Description: Watch a list of up to 10,000 companies, or the whole market, for people who start a role matching your filters, with one results table and an optional webhook. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Create an active monitor with [Bearer authentication](/api-reference/authentication). A monitor watches either a list of companies (`audience: "companies"`) or the whole market (`audience: "market"`) for people who recently started a role matching your filters. Each new hire is written to the monitor's results table and, when configured, posted to your webhook. Each successful request creates a new monitor, and creation has no idempotency key. If a network failure leaves the result unknown, [list your monitors](/api-reference/new-hire-monitors/list) and reconcile before retrying; a blind retry creates a second monitor that reports and charges separately.
The `frequency` can be `daily`, `weekly`, `every_30_days`, or `every_90_days` (default `weekly`). If you provide `webhook_url`, store the returned `signing_secret` immediately; it is encrypted at rest and returned only once. If you lose it, [rotate it](/api-reference/new-hire-monitors/update) on the existing monitor instead of creating a new one.
## Choose an audience
- **Company list.** Send `companies`: 1 to 10,000 `{ "linkedin_url": ... }` LinkedIn company URLs, with a slug or a numeric company ID. URLs are canonicalized to `https://www.linkedin.com/company/`, and two entries for the same company are rejected. `audience` defaults to `companies` when `companies` is sent. An empty `job_titles` list on a company list means every role. The market filters `industries`, `company_size`, `company_location`, and `person_location` are rejected on a company list.
- **Market.** Omit `companies` (or send `audience: "market"`) and send at least one `job_titles` entry. You can narrow it with `industries` (up to 300), `company_size` (`1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`), `company_location` (a place name such as `France`), and `person_location` (such as `Paris`).
Both audiences accept `job_titles` and `excluded_job_titles` (up to 100 each), `title_match` (`strict` matches the titles you list; `loose` also matches related titles in the same function), `seniorities` (`individual_contributor`, `manager`, `director`, `executive`; empty means all), and `hire_types` (`external` for people who joined from another company, `internal` for people who moved into the role inside the company; default both). Unknown fields are rejected with `422 invalid_monitor`.
**Filters are set at creation and cannot be edited.** `PATCH` accepts only the name, frequency, pause or resume, and the webhook. To change titles, seniorities, hire types, or market filters, create a new monitor.
## How monitoring works
Checks run asynchronously. The `201 Created` response contains `monitor`, `companies`, `signing_secret`, and `signing_secret_warning`; save `monitor.id`. The first completed check records a **baseline**: people already in a matching role are not reported. Later checks report people whose matching role started after the baseline. `baseline_completed_at` is `null` until the baseline exists.
When checks cannot progress, `run_block_reason` explains why, for example `unresolved_companies` (a company URL could not be found; the monitor is paused), `audience_needs_review` (the filters match too many people; the monitor is paused, so create a narrower monitor or resume to retry), `unsupported_location`, or a temporary `account_pool_unavailable`.
## Credits
Each reported new hire costs **1 credit**, charged when it is written to the results table. Nothing is charged at creation, for empty checks, for webhook deliveries or redeliveries, or for marking events read. When the workspace has no credits, new hires wait undelivered (`results_status: "blocked"`, `results_error: "insufficient_credits"`) and are delivered and charged after a top-up.
## Results table
Each monitor owns a regular Airscale results table named ` — New hires`. The monitor reports `results_table_id`, `results_status` (`ready`, `pending`, or `blocked`) and `results_error` (for example `insufficient_credits`, `results_table_deleted`, `table_row_limit_reached`, `results_columns_missing`, or a temporary `credit_settlement_busy` or `table_mutation_locked`). Deleting the monitor keeps its results table.
## Request size
The complete JSON request body must be at most **8 MiB (8,388,608 bytes)**; a larger body returns `413`. A missing or malformed body returns `400` with `{"error": "Invalid JSON"}`.
## Webhook URL rules
`webhook_url` must be a public HTTPS URL without embedded credentials. Other protocols, internal hostnames, and private or reserved addresses are rejected with `422 invalid_monitor` before the monitor is created.
## Verify webhook signatures
Airscale sends each new hire as a JSON `POST` to `webhook_url`, within about a minute of delivery to the results table. The body has `"type": "new_hire.detected"` plus the same fields as an event from [List new hire events](/api-reference/new-hire-monitors/events) without `read_at` or `webhook`: `id`, `monitor_id`, `detected_at`, `hire_type`, `person`, `title`, `start_date`, `company`, `previous_title`, and `previous_company_name`.
For example, `"start_date": "2026-10"` is the reported start month, `company.linkedin_url` is built from the numeric `linkedin_company_id`, and any unknown field is `null`.
The request includes `X-Airscale-Event: new_hire.detected`, `X-Airscale-Event-Id: `, `X-Airscale-Timestamp`, `X-Airscale-Signature: sha256=`, and `Idempotency-Key: new-hire-event:`. Compute HMAC-SHA256 with the `signing_secret` over `.`, compare it in constant time, and reject timestamps more than five minutes from the current time. This is the same scheme as job-change monitor webhooks. Deduplicate on the event ID and return a 2xx response only after durable handling.
Airscale makes up to five attempts with exponential backoff. `408`, `425`, `429`, and `5xx` responses are retried; other responses fail permanently (`webhook_http_`), and timeouts or dropped connections are marked `uncertain` because the request may have been received. Use [Redeliver a webhook](/api-reference/new-hire-monitors/events/redeliver) to send a failed or uncertain event again.
## Next step
Use [Get a new hire monitor](/api-reference/new-hire-monitors/get) to follow company resolution and the baseline.
---
## List new hire monitors
Source: https://docs.airscale.io/api-reference/new-hire-monitors/list.md
Description: List the new hire monitors in a workspace with their schedule, filters, results table, and company, new hire and unread-event counts. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
List every new hire monitor in the authenticated workspace, including monitors created in the Airscale app. Each monitor includes its audience, filters, status, schedule, results-table state, webhook state, company count, new hire count, and unread event count.
This operation is read-only and spends no credits. It never returns a webhook signing secret.
Monitors created in the app before role filters existed have `legacy: true` and `filters: null`. They can be read, paused, resumed, and renamed through the API, but their companies can only be edited in the app.
Use the monitor `id` returned here with the detail, update, company, and event operations. A paused monitor stays in the list so you can resume it later. If a create request's response was lost, list monitors before deciding whether to create another.
## Next step
Open [Get a new hire monitor](/api-reference/new-hire-monitors/get) for its companies and latest new hires.
---
## Get a new hire monitor
Source: https://docs.airscale.io/api-reference/new-hire-monitors/get.md
Description: Retrieve one monitor, its company list, and its latest 100 new hires. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Retrieve one monitor by `monitor_id`. The response contains the monitor, its companies sorted by URL, and up to the latest 100 events ordered newest first.
`new_hire_count` and `unread_event_count` cover every event, not only the 100-event preview. Preview events have no `webhook` receipt; use [List new hire events](/api-reference/new-hire-monitors/events) for receipts, filters, and pagination.
Each company has `identifier` (the lower-case slug or numeric ID from its URL), `linkedin_url`, `linkedin_company_id`, `name`, `last_checked_at`, and `status`: `pending` until it is resolved, then `resolved`, or `unresolved` when the company could not be found. An unresolved company pauses the monitor with `run_block_reason: "unresolved_companies"`. A market monitor returns an empty `companies` array.
The monitor reports `baseline_completed_at`, `next_check_at`, and `last_successful_check_at` as ISO 8601 timestamps, or `null`. A paused monitor has no next check scheduled. `run_block_reason` explains why checks are not progressing and `results_status` with `results_error` explains why found new hires are not yet delivered to the results table.
## Next step
Use [Add companies](/api-reference/new-hire-monitors/companies/add) to extend a company-list monitor.
---
## Update a new hire monitor
Source: https://docs.airscale.io/api-reference/new-hire-monitors/update.md
Description: Rename a monitor, change its frequency, pause or resume checks, change its webhook, or rotate the signing secret. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Update one or more monitor fields with `PATCH`. The body accepts `name`, `frequency` (`daily`, `weekly`, `every_30_days`, `every_90_days`), `action` (`pause` or `resume`), `webhook_url`, and `rotate_signing_secret: true`, and they can be combined in one request, for example `{"name": "Target accounts (Q4)", "action": "pause"}`. Any other field returns `422 invalid_monitor_update`.
Filters and the audience cannot be edited: `job_titles`, `seniorities`, `hire_types`, and the market filters are create-only. Create a new monitor to change them. Company lists change through [Add companies](/api-reference/new-hire-monitors/companies/add) and [Remove a company](/api-reference/new-hire-monitors/companies/remove).
The response returns the complete updated monitor.
## Pause and resume
Pausing stops checks and clears `next_check_at`; webhooks queued for a paused monitor are cancelled, so [redeliver](/api-reference/new-hire-monitors/events/redeliver) them after resuming. Resuming schedules a check. Resuming a monitor that was paused because its filters matched too many people (`run_block_reason: "audience_needs_review"`) retries its first check. While new hire monitoring is closed, resuming returns `503 monitoring_not_enabled`.
Renaming renames the results table while it still has its generated ` — New hires` title. Legacy monitors (`legacy: true`) cannot switch to `daily` checks.
## Change the webhook or recover a lost signing secret
`webhook_url` accepts a public HTTPS URL without embedded credentials, or `null`. Invalid URLs return `422 invalid_monitor_update`.
- Setting or changing the URL generates a fresh signing secret.
- `{"rotate_signing_secret": true}` alone rotates the secret of the current webhook. Rotating without a webhook returns `422 webhook_not_configured`; combining rotation with `webhook_url: null` returns `422 invalid_monitor_update`.
- `{"webhook_url": null}` disables the webhook and clears its stored secret.
- Setting the same URL without rotation keeps the existing secret and returns no secret.
When a new secret is generated, the response includes `signing_secret` and `signing_secret_warning`. Store the secret immediately; list and get never return it.
Changing the URL, disabling, or rotating cancels queued deliveries made with the previous configuration (`error_code: "webhook_configuration_changed"`). When a send is in flight, the request returns `409 webhook_delivery_in_progress` and nothing changes; retry after it settles. Webhook changes keep the monitor, its baseline, schedule, and results table, and spend no credits.
## Next step
Use [List new hire events](/api-reference/new-hire-monitors/events) to redeliver events after a webhook change.
---
## Delete a new hire monitor
Source: https://docs.airscale.io/api-reference/new-hire-monitors/delete.md
Description: Permanently remove a monitor, its events, and its webhook receipts. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Delete a monitor by `monitor_id`. This permanently removes the monitor, its events, and its webhook receipts. The monitor's results table and its rows stay in the workspace.
Deletion cannot be undone. [Pause the monitor](/api-reference/new-hire-monitors/update) to stop checks temporarily.
The operation returns `{ "ok": true }`. Deleting spends no credits.
## Next step
Use [List new hire monitors](/api-reference/new-hire-monitors/list) to verify the monitor no longer appears.
---
## Add companies to a new hire monitor
Source: https://docs.airscale.io/api-reference/new-hire-monitors/companies/add.md
Description: Add up to 10,000 LinkedIn companies to a company-list monitor; adding a new company rebuilds the baseline. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Add 1 to 10,000 companies per request to a company-list monitor with `{ "companies": [{ "linkedin_url": ... }] }`. Companies the monitor already watches are ignored, and the `201` response reports the monitor, its complete company list, `added_company_count`, and `baseline_reset`.
**Adding a company restarts the baseline.** Adding a company the monitor does not already watch changes its scope: the monitor discards undelivered findings, cancels an in-progress check, and rebuilds its baseline on the next check, so hires that started before the change are not reported. The response has `baseline_reset: true`. Adding only companies the monitor already watches is a no-op (`added_company_count: 0`, `baseline_reset: false`).
A monitor holds at most 10,000 companies; exceeding it returns `422 company_limit_reached`. Invalid or duplicate URLs in the request return `422 invalid_companies`. A market monitor has no company list (`422 market_monitor_has_no_companies`), and monitors created before role filters existed can only be edited in the app (`422 legacy_monitor`).
The JSON request body must fit within **8 MiB (8,388,608 bytes)**; larger bodies return `413`. Adding companies spends no credits.
## Next step
Use [Get a new hire monitor](/api-reference/new-hire-monitors/get) to follow each company's resolution.
---
## Remove a company from a new hire monitor
Source: https://docs.airscale.io/api-reference/new-hire-monitors/companies/remove.md
Description: Stop watching one company; removing a company rebuilds the baseline. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Remove one company by its `identifier`, the lower-case company slug or numeric ID from its URL as returned in the monitor's `companies`. The response returns the updated monitor, the removed `company`, and `baseline_reset: true`.
**Removing a company restarts the baseline.** The monitor discards undelivered findings, cancels an in-progress check, and rebuilds its baseline on the next check. New hires already delivered and the results table are kept.
A company-list monitor keeps at least one company: removing the last one returns `422 last_company`. An identifier the monitor does not watch returns `404 company_not_found`. Market and legacy monitors return `422 market_monitor_has_no_companies` and `422 legacy_monitor`.
## Next step
Use [Add companies](/api-reference/new-hire-monitors/companies/add) to replace a removed company.
---
## List new hire events
Source: https://docs.airscale.io/api-reference/new-hire-monitors/events.md
Description: Read cursor-paginated new hires, filtered by hire type and date, with their webhook delivery receipts. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
List the new hires delivered to the results table for one monitor, newest first. Set `limit` from 1 to 100 (default 50), filter with `type` (`all`, `external`, `internal`), and `from` and `to` (`YYYY-MM-DD`, UTC, inclusive). When `next_cursor` is not `null`, send it unchanged as `cursor` **with the same filters**; a cursor used with different filters returns `422 invalid_event_cursor`. Unknown query parameters return `422 invalid_event_page`.
Each event has `hire_type`, `person` (`name`, `linkedin_url`, `location`), `title`, `start_date` (the reported start month `YYYY-MM`, or `null`), `company` (`name`, `linkedin_company_id`, `linkedin_url`), `previous_title`, `previous_company_name`, `detected_at`, and `read_at`. Unknown fields are `null`. This endpoint is also the durable fallback when webhook delivery is delayed or unavailable.
## Webhook delivery receipts
Each event carries a `webhook` object, or `null` when no delivery exists. `status` is `pending`, `sending`, `retryable`, `sent`, `failed`, `uncertain`, or `cancelled`, with `attempt_count`, `last_attempt_at`, `sent_at`, and `error_code` (for example `webhook_http_410` or `webhook_configuration_changed`). `uncertain` means a timeout or dropped connection: the request may have been received. Use [Redeliver a webhook](/api-reference/new-hire-monitors/events/redeliver) to send an event again.
## Next step
Use [Mark an event as read](/api-reference/new-hire-monitors/events/read) after your application has processed an event.
---
## Mark a new hire event as read
Source: https://docs.airscale.io/api-reference/new-hire-monitors/events/read.md
Description: Acknowledge one new hire after processing it. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Mark one event as read after your integration has handled it. The response returns the event with its `read_at` timestamp, and the monitor's `unread_event_count` decreases.
The request accepts an empty body or `{}`. A body that is present but not valid JSON returns `400`.
The call is idempotent: marking an event that is already read returns it again with its first `read_at`. Webhook retries use the same event ID, so treat the event ID as the durable acknowledgement key.
Reading an event does not delete it. You can still retrieve it through [List new hire events](/api-reference/new-hire-monitors/events). Marking events read spends no credits.
## Next step
Review [Create a new hire monitor](/api-reference/new-hire-monitors/create) for webhook setup and signature verification.
---
## Redeliver a new hire webhook
Source: https://docs.airscale.io/api-reference/new-hire-monitors/events/redeliver.md
Description: Send one new hire's webhook again after a failed or unconfirmed delivery. Rate limit: 120 requests per fixed minute per API key, shared by all new hire monitor endpoints.
New hire monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Re-arm one event's webhook, for example after a `failed` or `uncertain` attempt or after resuming a paused monitor. Airscale resets the attempt count and sends the event again to the monitor's **current** webhook URL, signed with its current signing secret. Redelivery never searches again and spends no credits.
The request accepts an empty body or `{}`. The `202` response returns `event_id` and the new `webhook` receipt, normally `pending` with `attempt_count: 0`.
The event keeps the same ID and `Idempotency-Key: new-hire-event:` header. Your receiver may already have processed an `uncertain` delivery, so handle the event idempotently.
A monitor without a webhook returns `422 webhook_not_configured`. Track the outcome through the `webhook` receipt in [List new hire events](/api-reference/new-hire-monitors/events).
## Next step
Use [Update a new hire monitor](/api-reference/new-hire-monitors/update) to change the webhook URL or rotate its signing secret before redelivering.
---
## Create a post engagement monitor
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/create.md
Description: Follow up to 100 LinkedIn company pages and profiles and receive the people who react to or comment on their posts, with one results table and an optional webhook. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Create an active monitor with [Bearer authentication](/api-reference/authentication). A post engagement monitor follows LinkedIn company pages and personal profiles. On every check it reads the recent posts of each source and finds the people who reacted to or commented on them. Each newly detected engager is added as a row to the monitor's results table and, when configured, pushed to your webhook.
Each successful request creates a new monitor, and creation has no idempotency key. If a network failure leaves the result unknown, [list your monitors](/api-reference/post-engagement-monitors/list) before retrying; otherwise you may create a second monitor that charges the same people again.
**Sources are company pages and profiles only.** `sources` takes 1 to 100 LinkedIn company (`/company/...`) or profile (`/in/...`) URLs; they are canonicalized and de-duplicated. Single post URLs are rejected with `422 invalid_monitor`; use [Post likers](/api-reference/post-likers) or [Post commenters](/api-reference/post-commenters) for one post.
## Settings
- `frequency`: `daily` (default) or `weekly`.
- `engagement_types`: any of `reactions` and `comments`; default both.
- `include_existing_engagers`: default `false`, so the first check only records a baseline. `true` also delivers and charges people who engaged before the monitor existed.
- `filters`: `titles` and `locations` (case-insensitive contains matches, up to 50 each) and `excluded_company_urls` (LinkedIn company URLs, up to 100). Engagers that do not match are not delivered or charged.
- `webhook_url`: a public HTTPS URL without embedded credentials. Private, loopback, and internal hosts are rejected with `422` before creation and checked again at every send.
Unknown fields are rejected with `422 invalid_monitor`. The JSON request body must be at most **256 KiB (262,144 bytes)**; a larger body returns `413`.
## Limits and admission
A workspace can hold at most **25 monitors** (`422 monitor_limit_reached`), counting monitors created in the Airscale app. Creation requires at least 0.2 credits (`402 insufficient_credits`). While post engagement monitoring is closed, creation returns `503 monitoring_not_enabled`.
The `202 Accepted` response contains `monitor`, `sources`, `signing_secret`, and `signing_secret_warning`. Store `signing_secret` immediately; it is encrypted at rest and never returned again. Checks run asynchronously: the first check is due immediately and runs within a few minutes. Monitors share a check queue, so under load `next_check_at` can slip, but nothing is lost.
## Credits
Each engager delivered to the results table costs **0.2 credits**, charged once per person per monitor however many posts they engage with later. Reading posts and engagement pages is free, and reads, webhook deliveries, redeliveries, mark-read, and configuration changes never spend credits. When credits run out, checks keep running but new engagers wait unpaid: the monitor shows `results_status: "blocked"` and `results_error: "insufficient_credits"`, and they are charged and delivered within a few minutes of a top-up. Monitors are independent: the same person engaging with sources of two monitors is delivered and charged by each.
## Results table
Each monitor owns a regular Airscale results table named ` — Post engagement`. If the table is deleted or full in the app, delivery stops without charging and the monitor reports `results_status: "blocked"` with the reason. Deleting the monitor keeps its results table.
## Verify webhook signatures
One webhook is sent per delivered engager, including existing engagers imported on request. The JSON body has `"type": "post_engagement.engager_detected"`, `id` (the engager ID), `monitor_id`, `detected_at` (the delivery time), `engager` (the engager object from [List engagers](/api-reference/post-engagement-monitors/engagers) without `read_at` and `webhook`), and `engagements` (up to the 25 most recent engagement objects from [List engagements](/api-reference/post-engagement-monitors/engagements)).
The request includes `X-Airscale-Event: post_engagement.engager_detected`, `X-Airscale-Event-Id: `, `X-Airscale-Timestamp`, `X-Airscale-Signature: sha256=`, and `Idempotency-Key: post-engagement-engager:`. Compute HMAC-SHA256 with the `signing_secret` over `.`, compare it in constant time, and reject timestamps more than five minutes from the current time. This is the same scheme as job-change monitor webhooks. Deduplicate on the event ID and return a 2xx response only after durable handling.
Deliveries are dispatched every couple of minutes with a 15-second timeout. Airscale makes up to five attempts with exponential backoff: `408`, `425`, `429`, and `5xx` responses are retried; other responses fail permanently (`webhook_http_`); a blocked destination fails with `webhook_url_rejected`; timeouts and dropped connections become `uncertain` and are never resent automatically. Use [Redeliver a webhook](/api-reference/post-engagement-monitors/engagers/redeliver) to send an engager again.
## Next step
Use [Get a post engagement monitor](/api-reference/post-engagement-monitors/get) to follow the first check of each source.
---
## List post engagement monitors
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/list.md
Description: List the post engagement monitors in a workspace with their settings, results table, and source, engager and unread counts. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
List every post engagement monitor in the authenticated workspace, most recently updated first, including monitors created in the Airscale app. Each monitor includes its status, schedule, engagement types, filters, results-table state, webhook state, `source_count`, `engager_count`, and `unread_engager_count`.
This operation is read-only and spends no credits. It never returns a webhook signing secret.
`engager_count` counts engagers delivered to the results table, and `unread_engager_count` is an exact count independent of any page size. A paused monitor stays in the list so you can resume it later. Deleted monitors are not listed. If a create request's response was lost, list monitors before deciding whether to create another.
## Next step
Open [Get a post engagement monitor](/api-reference/post-engagement-monitors/get) for its sources.
---
## Get a post engagement monitor
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/get.md
Description: Retrieve one monitor and its active sources. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Retrieve one monitor by `monitor_id` with its active sources, sorted by URL.
Each source has `id`, `linkedin_url`, `kind` (`company` or `profile`), `status` (`pending` until its first check, then `monitoring`), `last_checked_at`, and `last_error`. Monitors created in the Airscale app can also contain single-post sources with `kind: "post"`; the API itself only adds company and profile sources.
The monitor reports `next_check_at` and `last_checked_at` as ISO 8601 timestamps, or `null`, and `last_error` as a short code when the last check could not complete. `results_status` is `ready`, `pending` (engagers waiting for delivery), or `blocked` with `results_error` such as `insufficient_credits`, `results_table_deleted`, `table_row_limit_reached`, or `results_columns_missing`.
## Next step
Use [List engagers](/api-reference/post-engagement-monitors/engagers) to read the people delivered so far.
---
## Update a post engagement monitor
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/update.md
Description: Change a monitor's settings or filters, pause or resume checks, change its webhook, or rotate the signing secret. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Update any combination of `name`, `frequency` (`daily` or `weekly`), `action` (`pause` or `resume`), `engagement_types`, `include_existing_engagers`, `filters`, `webhook_url` (HTTPS URL or `null`), and `rotate_signing_secret: true`. Sources change through [Add sources](/api-reference/post-engagement-monitors/sources/add) and [Remove a source](/api-reference/post-engagement-monitors/sources/remove); any other field returns `422 invalid_monitor_update`.
## Pause and resume
**Pause** stops checks and holds queued webhooks until the monitor is resumed. **Resume** schedules a check immediately and requires monitoring to be available (`503 monitoring_not_enabled`) and at least 0.2 credits (`402 insufficient_credits`).
## Settings
- Changing `frequency` schedules the next check one period from now.
- Changing `engagement_types` or `filters` restarts coverage. People already delivered stay delivered and are never charged again. `filters` replaces the whole filter object; omitted lists become empty.
- Turning `include_existing_engagers` on delivers previously seen engagers on the next pass and charges them.
## Change the webhook or recover a lost signing secret
- Setting or changing `webhook_url`, or sending `rotate_signing_secret: true`, returns a new one-time `signing_secret` with `signing_secret_warning`. Store it immediately.
- `{"webhook_url": null}` disables the webhook and clears the secret. Rotating without a webhook returns `422 webhook_not_configured`; combining rotation with `webhook_url: null` returns `422 invalid_monitor_update`.
- Repeating the same URL without rotation returns no secret.
Queued deliveries made for the old configuration are cancelled (`webhook_configuration_changed`); use redelivery to send them again. If a delivery is being sent at that moment, the edit returns `409 webhook_delivery_in_progress` and changes nothing; retry shortly. Configuration changes never spend credits.
## Next step
Use [Redeliver a webhook](/api-reference/post-engagement-monitors/engagers/redeliver) after changing the webhook URL.
---
## Delete a post engagement monitor
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/delete.md
Description: Stop a monitor and remove it from the API while keeping its results table. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Delete a monitor by `monitor_id`. Checks stop, queued webhooks and follow-ups are cancelled, and the monitor no longer appears in the API. The results table and its rows are kept in the Airscale app.
Deletion cannot be undone. [Pause the monitor](/api-reference/post-engagement-monitors/update) to stop checks temporarily.
The operation returns `{ "ok": true }`. A deleted monitor no longer counts toward the 25-monitor workspace limit.
## Next step
Use [List post engagement monitors](/api-reference/post-engagement-monitors/list) to verify the monitor no longer appears.
---
## Add sources to a post engagement monitor
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/sources/add.md
Description: Follow more LinkedIn company pages or profiles, up to 100 per monitor. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Add sources with `{"sources": ["https://www.linkedin.com/in/example-person-2"]}`. Each URL must be a LinkedIn company (`/company/...`) or profile (`/in/...`) URL; single post URLs are rejected with `422 invalid_sources`.
The `201` response returns `sources` (all active sources), `added_source_count` (URLs already followed are ignored), and `source_count`. A monitor follows at most **100 sources**; exceeding it returns `422 source_limit_reached`.
Adding sources restarts coverage for the monitor. Delivered engagers and the results table are kept, and people already delivered are never charged again.
The JSON request body must be at most **256 KiB (262,144 bytes)**. Adding sources spends no credits.
## Next step
Use [Get a post engagement monitor](/api-reference/post-engagement-monitors/get) to follow the first check of each new source.
---
## Remove a source from a post engagement monitor
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/sources/remove.md
Description: Stop following one LinkedIn company page or profile. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Remove one source by `source_id`. The response returns the source with `status: "removed"`.
Removing a source restarts coverage for the monitor; delivered engagers and the results table are kept. A monitor needs at least one source: removing the last one returns `422 source_required`. A source the monitor does not follow returns `404 source_not_found`.
## Next step
Use [Add sources](/api-reference/post-engagement-monitors/sources/add) to follow a replacement.
---
## List post engagers
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/engagers.md
Description: Read cursor-paginated engagers delivered to the results table, with their webhook delivery receipts. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
List the engagers delivered to the results table for one monitor, newest delivery first. Set `limit` from 1 to 100 (default 50). Pass the returned `next_cursor` unchanged as `cursor`; it is `null` on the last page. A malformed cursor returns `422 invalid_cursor`, and an invalid `limit` or unknown query parameter returns `422 invalid_page`.
Each engager has `linkedin_url`, `name`, `headline`, `title`, `company_name`, `company_linkedin_url`, `location` (each `null` when unknown), `engagement_count`, `first_detected_at`, `last_detected_at`, `delivered_at`, and `read_at`. `existing_engager: true` marks people imported because `include_existing_engagers` was on. Use [List engagements](/api-reference/post-engagement-monitors/engagements) for the individual reactions and comments.
## Webhook delivery receipts
Each engager carries a `webhook` object, or `null` when no delivery exists (for example, no webhook was configured when the engager was delivered). `status` is `pending`, `sending`, `retryable`, `sent`, `failed`, `uncertain`, or `cancelled`, with `attempt_count`, `last_attempt_at`, `sent_at`, and `error_code` (for example `webhook_http_405` or `webhook_configuration_changed`). Use [Redeliver a webhook](/api-reference/post-engagement-monitors/engagers/redeliver) to send an engager again.
## Next step
Use [Mark an engager as read](/api-reference/post-engagement-monitors/engagers/read) after your application has processed an engager.
---
## List post engagements
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/engagements.md
Description: Read cursor-paginated reactions and comments of delivered engagers. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
List the individual reactions and comments of delivered engagers, newest detection first. Set `limit` from 1 to 100 (default 50) and pass the returned `next_cursor` unchanged; it is `null` on the last page. Only engagements of engagers delivered (and paid for) are returned.
Each engagement has `engager_id`, `type` (`reaction` or `comment`), `post_url`, `source_url` (the followed source), `post_author_url`, `comment` (the comment text, or `null` for a reaction), `occurred_at` (when the person engaged, or `null` when unknown), and `detected_at`.
Reading engagements spends no credits.
## Next step
Use [List engagers](/api-reference/post-engagement-monitors/engagers) for one row per person.
---
## Mark a post engager as read
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/engagers/read.md
Description: Acknowledge one delivered engager after processing it. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Mark one delivered engager as read after your integration has handled it. The response returns the engager with its `read_at` timestamp and webhook receipt, and the monitor's `unread_engager_count` decreases.
The request accepts an empty body or `{}`. A body that is present but not valid JSON returns `400`.
The call is idempotent: marking an engager that is already read keeps its first `read_at`. Webhook retries use the engager ID as the event ID, so treat it as the durable acknowledgement key.
Marking an engager read does not delete it and spends no credits.
## Next step
Review [Create a post engagement monitor](/api-reference/post-engagement-monitors/create) for webhook setup and signature verification.
---
## Redeliver a post engager webhook
Source: https://docs.airscale.io/api-reference/post-engagement-monitors/engagers/redeliver.md
Description: Send one engager's webhook again after a failed or unconfirmed delivery. Rate limit: 120 requests per fixed minute per API key, shared by all post engagement monitor endpoints.
Post engagement monitoring requires a **V2 workspace API key**. Legacy V1 API keys are not supported by these endpoints. Monitors and their credits belong to the V2 workspace associated with the key.
Re-arm one delivered engager's webhook. Airscale resets the attempt count and sends the engager again to the monitor's **current** webhook URL with its current signing secret. Redelivery never re-runs a check and spends no credits. A paused monitor holds the delivery until it is resumed.
The request accepts an empty body or `{}`. The `202` response returns `engager_id` and the new `webhook` receipt, normally `pending` with `attempt_count: 0`. If a send for the engager is already in flight, its `sending` receipt is returned unchanged.
The engager keeps the same event ID and `Idempotency-Key: post-engagement-engager:` header. Your receiver may already have processed an `uncertain` delivery, so handle the engager idempotently.
A monitor without a webhook returns `422 webhook_not_configured`. Track the outcome through the `webhook` receipt in [List engagers](/api-reference/post-engagement-monitors/engagers).
## Next step
Use [Update a post engagement monitor](/api-reference/post-engagement-monitors/update) to change the webhook URL or rotate its signing secret before redelivering.
---
## Business intent topics
Source: https://docs.airscale.io/api-reference/business-intent-topics.md
Description: Check a LinkedIn company for selected business intent topics. A matched result costs 3 credits. Rate limit: 6 requests per second per workspace.
Check a company LinkedIn URL against one or more business intent topics. Submit only a LinkedIn **company** URL; a domain or personal profile URL is not accepted.
## Find topic values
Call [Company filter values](/api-reference/find-companies/filter-values) with `filter=topics` and a search term of at least two characters. This lookup uses the same API key and is free.
```bash Search topics
curl --get 'https://api.airscale.io/v1/find-companies/filter-values' \
-H "Authorization: Bearer $AIRSCALE_API_KEY" \
--data-urlencode 'filter=topics' \
--data-urlencode 'q=customer relationship'
```
The response contains `values` with a display `label` and a request `value`. For example, a result can be `{"label":"crm: customer relationship management (crm)","value":"crm: customer relationship management (crm)"}`. Copy the complete `value` string into the `topics` array. Search again with another term to find more topics; send 1–20 values per intent request.
## Check a company
```bash Check business intent
curl 'https://api.airscale.io/v1/business-intent-topics' \
-H "Authorization: Bearer $AIRSCALE_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"linkedin_company_url":"https://www.linkedin.com/company/example-company/","topics":["crm: customer relationship management (crm)"]}'
```
Use an HTTPS `linkedin.com/company//` URL without a query or fragment. The request body accepts only `linkedin_company_url` and `topics` and is limited to 16 KiB. Topic strings are trimmed, must be nonempty, and can be at most 150 characters each.
When `matched` is `true`, the response includes `intent_topics`, `level_of_intent`, `date_stamp`, company details when available, and `credits_consumed: 3`. When the company is not matched, `matched` is `false`, `intent_topics` is empty, and `credits_consumed` is `0`. A result with no usable intent topics is treated as an error rather than a paid match. Keep at least 3 credits available before calling this endpoint, including for a possible no-match result.
The limit is 6 requests per second per workspace, shared with Find companies and Company filter values. For `429`, wait and retry with bounded backoff. A repeated POST is a new lookup and can cost another 3 credits. If a `503` response includes `operation_id`, credit settlement is uncertain; contact Airscale support with that ID before retrying.
## Next step
Use the returned `intent_topics` and `level_of_intent` in your workflow, or [search for more topic values](/api-reference/find-companies/filter-values) to run another check.
---
## Website Technologies
Source: https://docs.airscale.io/api-reference/miscellaneous/website-technologies.md
Description: Find the technologies used by a website. Rate limit: 10 requests per second per workspace.
Find the technologies used by one website, such as its CMS, analytics tools, or JavaScript frameworks. Authenticate with your Airscale workspace API key and send exactly one `domain` field containing a bare hostname or HTTP(S) URL.
The domain is normalized to lowercase without a leading `www.` or trailing dot. Paths and queries are ignored. IP addresses, localhost, URL credentials, non-default ports, and non-HTTP(S) schemes are rejected. The JSON body must fit within **16 KiB**; additional fields are not accepted.
## Usage and credits
You need at least **0.5 credits** before a lookup can start. A response with one or more technology names costs **0.5 credits**. An empty result returns `technologies: []` and `credits_consumed: 0`.
Read `domain` for the normalized hostname and `technologies` for the list of names. Duplicate names are removed without regard to case. An empty list means no technologies were found for that lookup; it does not prove the website uses no technologies.
## Rate limits and retries
The limit is **10 requests per second per workspace**, measured in fixed UTC-second windows. Lookup capacity is also shared across workspaces, so actual throughput can be lower. A workspace rate limit returns `429`; unavailable lookup capacity returns `503`.
Allow more than **60 seconds** for a request: the lookup itself can take up to 60 seconds, with additional time for authentication and billing. A failed or timed-out lookup returns `502`. Authentication or billing services can also return `503`.
Use bounded backoff for temporary errors. This endpoint does not support caller idempotency keys. Retrying can run and charge another lookup, including when the original response was lost. A client timeout does not confirm that no credits were charged.
## Next step
Check your [credit balance](/api-reference/credit-count) or review [rate limits](/api-reference/rate-limits) before scheduling more lookups.
---
## WhatsApp checker
Source: https://docs.airscale.io/api-reference/miscellaneous/whatsapp-check.md
Description: Check whether one phone number is available on WhatsApp. Rate limit: 60 requests per minute per workspace for POST, including replays.
Check one phone number in strict E.164 format: a leading `+` followed by 7–15 digits, without spaces. The body must contain exactly one `phone` field and fit within 16 KiB.
## Usage and credits
The limit is **60 requests per minute per workspace**, including POST retries. A definitive `yes` or `no` costs **1 credit**. HTTP `202` means `pending` or `unknown`; it does not confirm availability or a final credit amount.
## Retrying and reconciliation
`Idempotency-Key` is optional. Use a UUID (versions 1–5) and reuse the same key and phone for retries of one logical check. Changing the phone with the same key returns `409`. Without a key, the server generates an operation ID; save the returned `operation_id`.
After a `202` response, use [WhatsApp check status](/api-reference/miscellaneous/whatsapp-check/status) to reconcile the operation before submitting another check. Repeating a headerless POST creates a new operation and can incur another charge.
A recorded insufficient-credit rejection returns `403`; a known unavailable check returns `503`. Both can include an `operation_id`. Reuse the original key when reconciling a lost response. Use bounded backoff for temporary errors and rate limits.
## Next step
[Look up the operation status](/api-reference/miscellaneous/whatsapp-check/status) using the same workspace API key.
---
## WhatsApp check status
Source: https://docs.airscale.io/api-reference/miscellaneous/whatsapp-check/status.md
Description: Reconcile a WhatsApp check using its operation ID. Rate limit: No endpoint-specific GET throttle.
Read a WhatsApp check in the authenticated workspace using the returned `operation_id`. This read-only lookup has no request body and does not start another check or charge additional credits. There is no endpoint-specific GET throttle.
## Reading the result
- HTTP `200` with `status: "completed"`, `whatsapp`, and `credits_consumed: 1` confirms a definitive result. The phone number is not returned.
- HTTP `202` with `status: "pending"` or `"unknown"` means the outcome is not yet confirmed. Poll with bounded backoff; do not infer a yes/no result or final charge.
- HTTP `200` with `status: "unavailable"` or `"rejected"` reports a terminal operation state without a WhatsApp result or credit amount.
- A completed state without result fields does not confirm a definitive result.
- HTTP `404` means the operation was not found in this workspace.
## Next step
Return to [WhatsApp checker](/api-reference/miscellaneous/whatsapp-check). Keep the original idempotency key when reconciling the same logical check.
---
## Meta Ads
Source: https://docs.airscale.io/api-reference/miscellaneous/meta-ads.md
Description: Look up Meta ads for a company domain. Rate limit: 60 requests per minute per workspace.
Look up Meta ads for one company. Send exactly one `domain` field: a bare hostname or HTTP(S) URL. Paths and queries are ignored after normalization. IP literals, credentials, non-default ports, and invalid domain labels are rejected. The JSON body must fit within 16 KiB.
## Usage and credits
The limit is **60 requests per minute per workspace**. You need at least **1 credit** before the lookup can start. A finite numeric `number_of_ads` greater than zero costs **1 credit**. A zero, missing, nonnumeric, or nonpositive count costs **0 credits**.
Read `credits_consumed` for the cost of the lookup. Fields such as `page_id` and `number_of_ads` are optional and can vary in type; check them before use. A zero-ad result costs zero credits.
## Timeouts and retries
The lookup can take up to **90 seconds**. HTTP `504` means that lookup timed out without a debit. Use bounded backoff for temporary errors and rate limits.
This endpoint does not support caller idempotency keys. Retrying a successful lookup can run and bill another lookup, including when the original response was lost.
## Next step
Review [credit balance](/api-reference/credit-count) or [rate limits](/api-reference/rate-limits) before scheduling more lookups.
---
## Google Ads
Source: https://docs.airscale.io/api-reference/miscellaneous/google-ads.md
Description: Look up Google ads for a company domain. Rate limit: 2 requests per rolling second and 120 per rolling minute per workspace.
Look up Google ads for one company. Send exactly one `domain` field: a bare hostname or HTTP(S) URL. Paths and queries are ignored after normalization. IP literals, credentials, non-default ports, and invalid domain labels are rejected. The JSON body must fit within 16 KiB.
## Usage and credits
The limit is **2 requests per rolling second and 120 requests per rolling minute per workspace**. You need at least **1 credit** before a lookup can start. A valid result with a positive `total_ad_count` or a nonempty `ads` array costs **1 credit**. A valid zero-ad result costs **0 credits**. Read `credits_consumed` for the charge.
The endpoint returns the first page of up to 20 ads. `total_ad_count` can be larger than the returned `ads` array. If `next_page_token` is present, it is returned, but this endpoint does not accept a token or fetch later pages.
The response is a JSON object. Common fields are `status`, `country_code`, `total_ad_count` (often a numeric string), `available_ads_in_response`, `ads`, `cached`, and `credits_consumed`. Each ad can include `advertiser_id`, `advertiser_name`, `creative_id`, `original_url`, `start`, `last_seen`, `format_type`, and a `variants` array with creative content or image URLs. Fields may be absent or vary by ad format. Treat any HTML in `variants[].content` as untrusted.
## Errors and retries
Invalid input returns `400`; insufficient credits returns `403`; the workspace limit returns `429`. Lookup failures return `502`, configuration or settlement failures return `503`, and lookup timeouts return `504`. Failed lookups and valid zero-ad results do not consume credits.
There is no caller idempotency key. A retry can run another lookup and charge another credit if ads are found. A `503` after a completed lookup can mean credit settlement is uncertain; check your balance or contact support before retrying.
## Next step
Review [credit balance](/api-reference/credit-count) or [rate limits](/api-reference/rate-limits) before scheduling more lookups.
---
## Google Maps
Source: https://docs.airscale.io/api-reference/miscellaneous/google-maps.md
Description: Find businesses around an address or coordinates. Rate limit: 15 admitted searches per rolling minute and five active searches per workspace, shared across API keys and MCP.
Search Google Maps for businesses within a strict circle around an address or supplied coordinates. The request waits for the search to finish and returns up to **500 unique businesses** in one response.
Authenticate with your workspace API key. See [Authentication](/api-reference/authentication).
## Search area and result limit
Send a business category or search phrase in `query` and an address or locality in `address`. Both are required. Text is trimmed before validation: `query` accepts 1–160 characters and `address` accepts 1–240.
`radius_km` accepts an integer from **1 to 100**, defaulting to **20**. `limit` accepts an integer from **1 to 500**, defaulting to **20**. Results can be fewer than requested. Defaults apply only when a field is omitted; `null` and unknown fields are rejected.
To choose the center precisely, supply `location` with `lat`, `lng`, and `display_name`. The coordinates take precedence over address lookup; `address` is still required. Latitude must be between -90 and 90, longitude between -180 and 180, and the trimmed display name between 1 and 240 characters.
Website contact extraction is unavailable. Omit `include_contacts` or set it to `false`; `true` is rejected. Business phone numbers and websites can still appear in the Maps results.
## Credits and limits
Each unique returned business costs **0.1 credit**. Three businesses cost 0.3 credits; empty results cost zero. Have `limit × 0.1` credits available before starting: 2 credits for the default limit of 20, or 50 credits for the maximum of 500. Unused reserved credits are refunded. The response's `credits_used` is the final charge.
Each workspace can start **15 searches per rolling minute** and have **five active searches** at a time. These limits are shared across API keys and the `airscale_google_maps` MCP tool. Requests may wait briefly for shared search capacity. A rate, concurrency or capacity limit returns `429`; honor `Retry-After` when present.
## Business results
The response contains `status`, `total_results`, `credits_used`, `data`, and `warnings`. Every business in `data` includes these fields:
| Fields | Meaning |
| --- | --- |
| `id`, `google_id`, `place_id` | Business identifiers. `id` is unique within the response. |
| `name`, `type`, `subtypes` | Business name, primary category, and an array of additional categories. |
| `business_status`, `verified` | Business status and a boolean verification value, or `null` when unknown. |
| `phone_number`, `website`, `domain`, `place_link` | Business contact details and Google Maps link. |
| `full_address`, `address`, `city`, `state`, `country` | Address details. |
| `latitude`, `longitude` | Coordinates as numbers, or `null`. |
| `rating`, `review_count` | Rating and integer review count, or `null`. |
`id` and `name` are nonempty strings. Other text fields can be empty strings or `null`; `subtypes` can be empty. Check `warnings` for search notices. A successful search with no matches returns `data: []`, `total_results: 0`, and `credits_used: 0`.
## Timing and errors
Allow at least **100 seconds** for your client timeout. The search has a 90-second server deadline.
Invalid input returns `400`, insufficient available credits returns `402`, and an unresolved or ambiguous location returns `422`. When `code` is `google_maps_location_ambiguous`, the response can include a `locations` array: select the intended candidate and submit it as `location`. Search failures return `502`, temporary availability or billing failures return `503`, and timeouts return `504`. Error bodies contain `error` and `code`, with generic messages such as "Google Maps search is temporarily unavailable."
## Next step
Use the same inputs with [`airscale_google_maps`](/mcp/tools#airscale-google-maps) from an MCP client.
---
## Email verifier
Source: https://docs.airscale.io/api-reference/miscellaneous/email-verifier.md
Description: Verify the deliverability of one email address. Rate limit: No endpoint-specific throttle.
Verify one email address using your workspace API key. Send exactly one `email` field in a JSON body of at most **16 KiB**. Surrounding whitespace is trimmed, and the trimmed address must be at most 320 characters. The legacy `/email-verifier` route remains available.
## Usage and credits
The cost is **0.5 credits per request**, reserved before verification. There is no endpoint-specific throttle.
Allow at least **135 seconds**, plus a network margin, in your client timeout. If verification remains inconclusive, the result is `risky`; waiting for that result does not add another charge.
## Reading the response
Read the result from `body` when that object is present; otherwise read it from the top level. JSON object results include `credits_consumed: 0.5` alongside the result. Wrapped results also include `returned_an_error: false` at the top level.
Fields such as `email`, `status`, and `result` may be absent or have different types. Check the response content type before parsing: successful responses can also contain non-object JSON or non-JSON content without a `credits_consumed` field.
## Errors and retries
An unsuccessful verification can return an error such as `422`; error bodies can vary. Failed verification requests are eligible for a refund. A `503` can mean the charge or refund could not be confirmed, so do not assume the credits have been returned.
This endpoint does not support caller idempotency keys. Retrying creates another verification request and can incur another charge. Use bounded backoff for temporary failures and avoid treating a timeout as proof that no credits were charged.
## Next step
Use [Email finder](/api-reference/email-finder) to find a work email, or check your [credit balance](/api-reference/credit-count).
---
## US DNC Checker
Source: https://docs.airscale.io/api-reference/dnc-checker.md
Description: Check whether a US phone number is listed on the US Do Not Call list. Rate limit: 5 requests per second per workspace.
Submit a US phone number using `phone`. The operation normalizes accepted numbers to `+1` format and returns whether the number is listed on the US Do Not Call (DNC) list. For UK numbers, use the [UK DNC Checker](/api-reference/uk-dnc-checker).
A successful check costs 1 credit whether `listed` is `true` or `false`. The limit is 5 requests per second per workspace. Validation and lookup failures are not charged.
`POST /v1/dnc-check` remains supported for existing integrations; it accepts the same request and returns the same response, pricing, and limits as `POST /v1/us-dnc-check`.
Non-US numbers return `422` with `code: "unsupported_phone_region"` without starting a check. Malformed numbers return `422` with `code: "invalid_input"`. Correct the input before retrying either response.
`phone_number` and `mobile_phone` are accepted aliases. `phone` takes precedence when non-null, followed by `phone_number`, then `mobile_phone`. Use one field to avoid ambiguity.
## Read a successful result
| Field | Meaning |
| --- | --- |
| `status` | `success` for a completed check. |
| `phone` | Normalized US phone number. |
| `listed` | Boolean indicating whether the number is listed. |
| `result` | `Listed on DNC` or `Not listed on DNC`. |
| `credits_used` | Credits charged for this check. |
| `credits_remaining` | Remaining workspace credit balance. |
After `429`, retry in a later second with bounded exponential backoff. For temporary `502` or `503` responses, retry with increasing delays and a fixed retry limit; contact support if errors persist. The maximum JSON body size is 256 KiB.
## Next step
Review [Authentication](/api-reference/authentication) before updating an existing integration.
---
## UK DNC Checker
Source: https://docs.airscale.io/api-reference/uk-dnc-checker.md
Description: Check whether a UK phone number is registered on TPS or CTPS. Rate limit: 5 requests per rolling second per workspace.
Submit a UK phone number using `phone`. The operation checks the number against the UK TPS and CTPS registers: TPS (Telephone Preference Service) is the register for individuals, and CTPS (Corporate Telephone Preference Service) is the register for businesses. For US numbers, use the [US DNC Checker](/api-reference/dnc-checker).
A completed check costs 1 credit whether the number is listed or not. The limit is 5 requests per rolling second per workspace. Validation failures, rejected numbers, and lookup failures are not charged.
## Send a number
Send national (`020 7946 0000`) or international (`+44 20 7946 0000`) format. Spaces, parentheses, dots, and hyphens are accepted, up to 32 characters. Numbers in the Crown dependency ranges, such as Jersey, Guernsey, and the Isle of Man, are accepted. The response returns the number in `+44` format.
`phone_number` and `mobile_phone` are accepted aliases. `phone` takes precedence when non-null, followed by `phone_number`, then `mobile_phone`. Any other body field returns `400` with `code: "invalid_input"`. The maximum JSON body size is 256 KiB.
## Read a successful result
| Field | Meaning |
| --- | --- |
| `status` | `success` for a completed check. |
| `phone` | Normalized UK phone number in `+44` format. |
| `listed` | `true` when the number is on TPS, CTPS, or both. |
| `on_tps` | `true` when the number is on TPS, the register for individuals. |
| `on_ctps` | `true` when the number is on CTPS, the register for businesses. |
| `result` | `Listed on TPS`, `Listed on CTPS`, `Listed on TPS & CTPS`, or `Not listed on TPS/CTPS`. |
| `credits_used` | Credits charged for this check: always `1`. |
| `credits_remaining` | Remaining workspace credit balance. |
## Errors and retries
| Status | Meaning | Charged |
| --- | --- | --- |
| `400` | Invalid JSON, a body that is not an object, or an unsupported field. | No |
| `401` | Missing or invalid API key. | No |
| `403` | Insufficient credits. At least 1 credit is required before a check starts. | No |
| `413` | JSON body larger than 256 KiB. | No |
| `422` | `code: "unsupported_phone_region"` for a valid non-UK number; `code: "invalid_input"` for a missing, malformed, or invalid UK number. | No |
| `429` | Workspace rate limit exceeded. | No |
| `502` | The register lookup failed or returned an invalid result. | No |
| `503` | A service the check depends on is temporarily unavailable. | No result is returned |
| `504` | The register lookup timed out. | No |
Correct the input before retrying a `400` or `422`. After `429`, retry in a later second with bounded exponential backoff. For temporary `502`, `503`, or `504` responses, retry with increasing delays and a fixed retry limit; contact support if errors persist. Every completed retry is a new check that costs 1 credit.
## Next step
Review [Authentication](/api-reference/authentication) and [rate limits](/api-reference/rate-limits) before scheduling checks.
---
## How to use the Airscale MCP (+Claude demo)
Source: https://docs.airscale.io/mcp/how-to-use-the-airscale-mcp.md
Description: Prospect through conversation with Airscale search, enrichment, and export tools.
Prospect without leaving your AI chat. Airscale connects Claude, ChatGPT, and other compatible assistants to search, enrichment, research, and export tools, so you can build a list through natural-language conversation.
## What is the Airscale MCP?
The Airscale MCP gives your assistant 42 typed tools that can:
- Check your workspace credit balance.
- Search for people and companies, including with Leads Finder filters.
- Find companies similar to reference domains with Company lookalikes.
- Discover valid Find Companies filters before searching.
- Enrich contact details and person or company profiles.
- Find a company's LinkedIn URL from its domain and list the people engaging with a LinkedIn post.
- Verify emails, check WhatsApp and US Do Not Call status, and look up Meta ads.
- Run Airsearch for structured web research.
- Create downloadable CSV or JSONL exports.
See the [MCP tool catalog](/mcp/tools) for every tool and its inputs.
## How credits work
Find People costs 0.1 credit per returned person. Find Companies costs 0.1 credit per returned company. Airsearch costs 0.5 credits per successful call.
Company lookalikes costs 0.5 credits per unique returned company. Set an explicit small `limit`; the API reserves `limit × 0.5` credits and refunds unused credits. `airscale_company_lookalikes` returns synchronously and shares 15 starts per rolling minute and 5 active searches per workspace with the API. Do not automatically retry: a search can complete and be charged even when its response is lost, and repeating it can cause another charge. See [Company lookalikes](/api-reference/company-lookalikes).
Credit checks, people counts, and Find Companies filter discovery are free planning tools. Other enrichment follows linked API pricing in the related references for [contact data](/api-reference/email-finder), [people profiles](/api-reference/extract-people-profile), and [company profiles](/api-reference/extract-company-profile).
Before a paid export starts, review the final filters, row limit, and maximum spend, then explicitly confirm that paid action. No paid search, enrichment, or export should run before your approval.
## Run a search in natural language
Describe the cohort and keep the first result small. The example prompts below are illustrative and non-executing; they instruct your assistant to pause before every paid action.
> Find up to five cybersecurity companies in France with 51–200 employees. Before you run it, show me the proposed tool, filters, row limit, and maximum cost, then wait for my approval.
Your assistant can use a free filter-discovery tool first when a value needs validation. Approve only the bounded search you reviewed.
### Review your results
Review the company name, domain, website, country, and filter precision before expanding the search. At 0.1 credit per returned company, a five-company sample costs at most 0.5 credits.
### Enrich contacts through conversation
Begin with a bounded role-discovery request for only the companies you approved:
> Discovery step: For the approved companies, discover at most one CEO, one CFO, and one Head of Growth per approved company. Show me the proposed tool, per-step maximum cost, and cumulative workflow maximum, then wait for my approval.
Review the discovered people and approve the decision-makers you want to continue with. Then request only their professional work emails:
> Professional work email enrichment step: For only the approved decision-makers, find professional work emails. Show me the proposed tool, contact count, per-step maximum cost, and new cumulative workflow maximum, then wait for my approval.
Review the requested fields and linked pricing before approving each stage. Keep each follow-up bounded, and do not add unapproved companies or contacts to the request.
## Export your final list
People and company exports perform a fresh paid search from the final filters. They do not export the selected chat rows, may return different rows, and add a new charge in addition to earlier paid steps in the workflow.
Before starting, require the assistant to repeat the exact filters, fields, format, `max_rows`, additional maximum credits, and cumulative workflow maximum, then wait for your approval.
Exports are asynchronous: start one export, check its status, then retrieve the file after completion. Save the returned `export_id` and reuse the same `export_id` for status and file requests.
Do not start a duplicate export while the existing job is `queued` or `running`; follow the returned `poll_after_seconds` interval instead. When status is `completed` or `failed`, stop polling; retrieve the file only after completion.
## Get started
- [Connect Airscale MCP to ChatGPT](/mcp/connect-airscale-mcp-to-chatgpt)
- [Connect Airscale MCP to Claude](/mcp/connect-airscale-mcp-to-claude)
- [Read the Airscale MCP server reference](/mcp/airscale-mcp-server)
---
## Connect Airscale MCP to ChatGPT
Source: https://docs.airscale.io/mcp/connect-airscale-mcp-to-chatgpt.md
Description: Connect ChatGPT to Airscale through browser OAuth and validate the connection without spending credits.
Connect ChatGPT to your Airscale workspace with browser OAuth, then verify the connection with a free tool call before you approve any paid work.
## MCP server URL
Use the official remote MCP endpoint exactly as shown:
```text
https://mcp.airscale.io/mcp
```
## What ChatGPT can do with Airscale MCP
Airscale MCP gives ChatGPT 42 typed tools that can:
- Check the authorized workspace's credit balance.
- Search for people and companies, including with Leads Finder filters.
- Find companies similar to reference domains with Company lookalikes.
- Count matches and discover accepted filter values before a paid search.
- Enrich work contact details and extract people or company profiles.
- Find a company's LinkedIn URL from its domain and list the people who liked or commented on a LinkedIn post.
- Verify emails, check WhatsApp availability and US Do Not Call status, and look up a company's Meta ads.
- Run Airsearch web research.
- Create downloadable people or company exports.
Managed large contact enrichment is work-email-only in its current phase. Review exact inputs and credit behavior in the [MCP tool catalog](/mcp/tools).
## Before you start
You need an Airscale account with access to the intended workspace, API access enabled, and an active workspace credential. You also need a ChatGPT account and workspace where Developer mode is available; availability can depend on account and workspace policy.
ChatGPT uses browser OAuth for this connection: if prompted, the browser asks you to sign in to Airscale, choose a workspace, and authorize ChatGPT. OpenAI's [current plugin connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt) is the source for the navigation below.
After OAuth, Airscale's MCP server resolves the authorized workspace's current credential server-side on each tool call; ChatGPT neither receives nor stores that API key. Do not paste an Airscale API key into ChatGPT, prompts, or tool inputs.
## Step-by-step setup
Open **Settings → Security and login**, then turn on **Developer mode**. Developer mode availability can depend on account and workspace policy.
Go to **ChatGPT Plugins** and select the plus button.
Enter a user-facing name and description, such as **Airscale MCP** and a short description of its search, enrichment, research, and export tools.
Under **Connection**, choose the public endpoint option and enter `https://mcp.airscale.io/mcp`, including the `/mcp` path. Create the connection. If prompted, complete browser OAuth, sign in to Airscale, select the intended workspace, and return to ChatGPT. Do not enter an API key or static authorization value.
Review the tools and metadata discovered from the server. Confirm that the Airscale connection shows the expected 42 typed tools before testing it.
Start a new conversation, add the Airscale MCP connection from the tools menu, and run `airscale_check_credits` without another tool. A returned balance confirms tool discovery and authentication to an Airscale workspace without debiting credits, but it does not identify which workspace. Separately verify the workspace shown during OAuth before paid actions.
## Recommended first prompts
The identities and domains below are synthetic.
> Use `airscale_check_credits` to show my current Airscale credit balance. Do not call another tool.
This is the free connection test. A returned balance confirms tool discovery and authentication to an Airscale workspace without debiting credits. It does not identify which workspace; verify the workspace shown during OAuth before paid actions.
> Count people named Jordan Example who work at `northstar.example`. Do not run a paid search.
> Plan an Airscale search for up to five companies matching `sample-company.test`. Show the proposed Airscale tool, arguments, and maximum cost, then wait for my approval.
For a complete staged sequence, follow the [safe MCP workflow](/mcp/how-to-use-the-airscale-mcp).
## Export behavior in ChatGPT
A people or company export performs a fresh paid search from the final filters; it does not package the selected chat rows and may return different rows. Before approval, review the exact filters, fields, format, `max_rows`, additional maximum credits, and cumulative workflow maximum.
An export has one asynchronous lifecycle: start the export once, check its status, then retrieve the file when it is ready. Reuse the same `export_id` and honor the returned `poll_after_seconds`. Do not start a duplicate export while the original job is queued or running.
## Credits and confirmation
The credit check, people count, company filter-value discovery, export status, and export-file retrieval are free. Search and enrichment tools can consume credits; Airsearch costs 0.5 credits per successful call. Managed contact enrichment is work-email-only in its current phase.
Paid export starts fail closed until `confirm_credit_spend` is explicitly `true`. Review ChatGPT's proposed tool, arguments, row limit, and maximum cost before confirming. An export can support up to 10,000 rows, but use the smallest limit that serves the task.
## Refreshing tools
If Airscale tools or metadata are stale, open the connection in **ChatGPT Plugins**, select **Refresh**, confirm the advertised metadata changed, then start a new conversation and add the connection again from the tools menu.
## Troubleshooting
Open **Settings → Security and login** and look for **Developer mode**. Availability can depend on account and workspace policy, so ask the workspace administrator to check policy if the control is unavailable.
Confirm the exact public endpoint, including the `/mcp` path. Complete Airscale browser authorization if prompted, return to ChatGPT, and review any connection or discovered-tool errors before retrying.
Confirm that the selected Airscale workspace has API access, an active workspace credential, and enough credits for the proposed paid tool. Run `airscale_check_credits` before retrying.
Poll `airscale_get_export_status` with the same identifier and the returned `poll_after_seconds`. Do not create another paid job.
## Security note
Authorize only the Airscale workspace you intend to use. Keep secrets out of chats and tool inputs, review every proposed paid action, and remove the Airscale MCP connection when it is no longer needed.
## Need help?
- Review the [MCP tool catalog](/mcp/tools) for exact schemas and credit behavior.
- Use the [safe MCP workflow](/mcp/how-to-use-the-airscale-mcp) before running a search or export.
- Read the [Airscale MCP server overview](/mcp/airscale-mcp-server) for authentication and security guidance.
---
## Connect Airscale MCP to Claude
Source: https://docs.airscale.io/mcp/connect-airscale-mcp-to-claude.md
Description: Connect Claude clients to Airscale with hosted OAuth or a protected Claude Code authorization header.
Connect Claude to your Airscale workspace through hosted remote OAuth where supported, or configure Claude Code with a protected environment-backed header.
## MCP server URL
Use the official remote MCP endpoint exactly as shown:
```text
https://mcp.airscale.io/mcp
```
## What Claude can do with Airscale MCP
Airscale MCP gives Claude 42 typed tools that can:
- Check the authorized workspace's credit balance.
- Search for people and companies, including with Leads Finder filters.
- Find companies similar to reference domains with Company lookalikes.
- Count matches and discover accepted filter values before a paid search.
- Enrich work contact details and extract people or company profiles.
- Find a company's LinkedIn URL from its domain and list the people who liked or commented on a LinkedIn post.
- Verify emails, check WhatsApp availability and US Do Not Call status, and look up a company's Meta ads.
- Run Airsearch web research.
- Create downloadable people or company exports.
Managed large contact enrichment is work-email-only in its current phase. Review exact inputs and credit behavior in the [MCP tool catalog](/mcp/tools).
## Before you start
You need an Airscale account with access to the intended workspace, API access enabled, and an active workspace credential.
Claude web and desktop clients can use remote OAuth in the browser where supported by the Claude account and client. Each hosted user signs in to Airscale and authorizes a workspace.
Claude Code can instead use a protected authorization header sourced from an environment variable. Hosted OAuth and Claude Code header authentication are separate connection methods. Never put the credential in a prompt or MCP tool argument.
## Claude web setup
Use the hosted connector flow that matches your Claude account. If availability or labels differ, check Anthropic's current [remote custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
### Individual Claude accounts
Individual Free, Pro, or Max accounts can add a custom connector directly. A Free account is limited to one custom connector.
Sign in to Claude web or desktop and open **Customize → Connectors**. Use the current connectors or integrations settings if the label differs.
Choose the control to add a custom connector, name it **Airscale MCP**, and enter `https://mcp.airscale.io/mcp` as the remote server URL.
Continue to the browser sign-in, authenticate with Airscale, select the intended workspace, approve access, and return to Claude.
Select Airscale MCP for a new conversation and confirm that Claude can see its tools.
### Claude Team and Enterprise
For Claude Team or Enterprise, an Owner or Primary Owner must add Airscale through **Custom → Web** before members can connect.
Open **Organization settings → Connectors**, choose **Add**, hover over **Custom**, select **Web**, and enter `https://mcp.airscale.io/mcp`. Add the connector to the organization.
Each member opens **Customize → Connectors**, finds Airscale MCP, clicks **Connect**, and authenticates with their own Airscale account in the browser.
Select Airscale MCP and the tools needed for the conversation. Organization approval makes the connector available; it does not share an Owner's Airscale authorization with members.
## Claude Code setup
Load `AIRSCALE_API_KEY` through an OS or team secret manager or a protected runtime environment before starting Claude Code. Do not type a literal API key into a shell command or shell history.
Create a project-scoped `.mcp.json` at the project root:
```json Project .mcp.json
{
"mcpServers": {
"airscale": {
"type": "http",
"url": "https://mcp.airscale.io/mcp",
"headers": {
"Authorization": "Bearer ${AIRSCALE_API_KEY}"
}
}
}
}
```
The `${AIRSCALE_API_KEY}` expression is resolved from the Claude Code process environment. Never replace it with a literal secret in `.mcp.json`; each developer supplies the environment value independently.
From the project root, verify that Claude Code loaded the server:
```bash
claude mcp list
```
Inside Claude Code, run `/mcp` to inspect connection status and the available tools. See the official [Claude Code MCP scope documentation](https://code.claude.com/docs/en/mcp) before choosing a different scope; local and user configurations live in `~/.claude.json`, not in the project file.
## Recommended first prompts
The identities and domains below are synthetic.
> Use `airscale_check_credits` to show my current Airscale credit balance. Do not call another tool.
This is the free connection test. A returned balance confirms tool discovery and authentication to an Airscale workspace without debiting credits, but it does not identify which workspace. Hosted users must verify the OAuth-selected workspace, and Claude Code users must verify which workspace owns the configured credential before paid actions.
> Use Airscale MCP to count people named Taylor Example at `northstar.example`. Do not run a paid search.
> Plan an Airscale search for up to five companies matching `sample-company.test`. Show the proposed Airscale tool, arguments, and maximum cost, then wait for my approval.
For a complete staged sequence, follow the [safe MCP workflow](/mcp/how-to-use-the-airscale-mcp).
## Export behavior
A people or company export performs a fresh paid search from the final filters; it does not package the selected chat rows and may return different rows. Before approval, review the exact filters, fields, format, `max_rows`, additional maximum credits, and cumulative workflow maximum.
An export has one asynchronous lifecycle: start the export once, check its status, then retrieve the file when it is ready. Reuse the same `export_id` and honor the returned `poll_after_seconds`. Do not start a duplicate export while the original job is queued or running.
## Credits and confirmation
The credit check, people count, company filter-value discovery, export status, and export-file retrieval are free. Search and enrichment tools can consume credits; Airsearch costs 0.5 credits per successful call. Managed contact enrichment is work-email-only in its current phase.
Paid export starts fail closed until `confirm_credit_spend` is explicitly `true`. Review Claude's proposed tool, arguments, row limit, and maximum cost before confirming. An export can support up to 10,000 rows, but use the smallest limit that serves the task.
## Refreshing tools
If Airscale tools are stale or missing, refresh or reconnect the hosted connector and start a new conversation. In Claude Code, verify the environment and server with `claude mcp list`, then use `/mcp` to inspect the refreshed connection.
## Troubleshooting
Confirm that the Claude client and account support remote MCP connectors. In Team or Enterprise, ask an Owner or Primary Owner to add Airscale before each member connects their own account.
Complete the Airscale browser sign-in, wait for the authorization confirmation, and return to Claude. Reconnect while signed in to the intended workspace if the state does not update.
Confirm that the environment variable is available to the Claude Code process and that the project configuration uses the `Bearer` scheme. Do not print the value while debugging.
Poll `airscale_get_export_status` with the same identifier and the returned `poll_after_seconds`. Do not create another paid job.
## Security note
Hosted Claude users should authorize only the Airscale workspace they intend to use. Claude Code users should keep the environment value out of version control, prompts, and tool inputs. For either method, review every proposed paid action and remove access when it is no longer needed.
## Need help?
- Review the [MCP tool catalog](/mcp/tools) for exact schemas and credit behavior.
- Use the [safe MCP workflow](/mcp/how-to-use-the-airscale-mcp) before running a search or export.
- Read the [Airscale MCP server overview](/mcp/airscale-mcp-server) for authentication and security guidance.
---
## Airscale MCP Server
Source: https://docs.airscale.io/mcp/airscale-mcp-server.md
Description: Connect Airscale to your AI assistant and prospect without leaving the chat.
Airscale MCP gives compatible AI assistants a concise, typed interface for prospecting through conversation while keeping authentication and paid actions explicit.
## MCP server URL
```text
https://mcp.airscale.io/mcp
```
This remote Streamable HTTP server works with hosted assistants and trusted developer clients. For hosted clients, OAuth is preferred and uses browser sign-in. The Airscale MCP server resolves the authorized workspace credential server-side; the client neither receives nor stores the API key.
Trusted header-capable developer clients must load `AIRSCALE_API_KEY` from a protected runtime environment or secret manager. Never place a literal API key in a prompt or tool argument, source or browser code, or a shell command or shell history.
## Getting started
1. First, choose the setup guide for your assistant.
2. Then connect it to the MCP server URL above.
3. Complete browser OAuth or authenticate from a protected developer runtime.
4. Select and verify the intended workspace.
5. Run `airscale_check_credits` as the free connection check before any paid tool.
The credit check confirms authentication to an Airscale workspace without debiting credits, but it does not identify which workspace. Verify the workspace selected during OAuth—or the workspace that owns a developer credential—before paid actions.
## Setup walkthroughs
- [ChatGPT setup guide](/mcp/connect-airscale-mcp-to-chatgpt)
- [Claude setup guide](/mcp/connect-airscale-mcp-to-claude)
- [Airscale MCP workflow](/mcp/how-to-use-the-airscale-mcp)
These guides contain the client-specific connection steps; this page keeps the shared server contract in one place.
## What you can do
- **People and companies search:** discover prospects with bounded, structured searches.
- **Company lookalikes:** find similar companies from 1–10 reference domains using `airscale_company_lookalikes`.
- **Filter discovery:** inspect available filters and counts before requesting rows.
- **Contact and profile enrichment:** add professional contact details or public person and company profiles.
- **Airsearch:** answer natural-language research questions with structured results.
- **Downloadable exports:** create bounded people, company, or managed contact files and retrieve them when complete.
The [MCP tool catalog](/mcp/tools) is the schema reference for all 42 typed tools. Managed contact enrichment is a work-email-only flow; it does not add mobile numbers, personal emails, or profile enrichment.
## Export lifecycle
### People and company exports
People and company exports are fresh paid searches, not packages of selected chat rows. A people export uses the final `query`; a company export uses the final `filters`. Results may differ from the sample, and each export creates an additional charge.
Before confirming, review the final scope, fields, format, `max_rows`, additional maximum credits, and cumulative workflow maximum. At up to 0.1 credits per exported row, the requested limit defines the maximum for this fresh search. Set `confirm_credit_spend` only after that review.
### Managed contact enrichment export
A managed contact enrichment export uses a `batch_id`. The batch remains appendable through `airscale_add_contacts_to_enrichment_batch` until the confirmed start. Review the approved contact count, `work_email` as the only enrichment, fields and format, and the maximum calculated as the approved contact count multiplied by up to 2 credits per contact. Review that additional maximum together with the cumulative workflow maximum. After reviewing the contact count and maximum, do not add more contacts.
If the batch may have changed, rerun `airscale_start_contact_enrichment_export` with `confirm_credit_spend` set to false or omitted to obtain the current maximum, then review again. Only after approval should you set it to true. That confirmed start creates the export job and freezes the batch.
### One export lifecycle
Both branches use one asynchronous lifecycle:
1. Run the **confirmed start** once. An unconfirmed managed-contact maximum check does not create a job. Keep the returned `export_id`, and do not start a duplicate export while the job is queued or running.
2. While status is `queued` or `running`, check **status** with the same `export_id` and respect the returned `poll_after_seconds`.
3. When status is `completed` or `failed`, stop polling. Retrieve the **file** with the same `export_id` only after completion.
## How credits work
- Free operations include the credit check, planning, people count or company filter discovery, export status polling, and completed file retrieval.
- Find People and Find Companies each cost 0.1 credit per returned row.
- Company lookalikes costs 0.5 credits per unique returned company and reserves `limit × 0.5` credits before searching.
- Airsearch costs 0.5 credits per successful call.
- The managed work-email-only contact enrichment phase costs up to 2 credits per contact.
- Paid export starts fail closed until `confirm_credit_spend` is explicitly set after review.
For exact per-tool behavior, use the [MCP tool catalog](/mcp/tools).
## Recommended workflow
1. Run `airscale_check_credits` for a free connection check.
2. Verify the intended workspace before choosing a paid path.
### People and company search/export
1. Use a free count or filter discovery tool to plan the request.
2. Run a bounded sample and inspect the returned shape.
3. Review the workspace, results, and credit implications before continuing.
4. For optional enrichment, request separate approval with its own maximum and updated cumulative spend.
5. Before exporting, perform a renewed export review of the final `query` or `filters`, fields, format, `max_rows`, additional maximum credits, and cumulative workflow maximum.
6. Set `confirm_credit_spend` only after approval, then start once.
### Company lookalikes
Use `airscale_company_lookalikes` with 1–10 reference domains and an explicit small `limit`. All results return in one synchronous response. The tool shares 15 starts per rolling minute and 5 active searches per workspace with the API. Do not automatically retry; a lost response can still belong to a completed, charged search, and repeating it can cause another charge. See [Company lookalikes](/api-reference/company-lookalikes) for filters and total-result limits.
### Managed contact enrichment/export
1. Create a batch with `airscale_create_contact_enrichment_batch`.
2. Use `airscale_add_contacts_to_enrichment_batch` while the batch is appendable before the confirmed start.
3. Review the approved contact count, `work_email`, fields and format.
4. Calculate the maximum from the approved contact count multiplied by up to 2 credits per contact, then review the additional maximum and cumulative workflow maximum.
5. After reviewing the contact count and maximum, do not add more contacts.
6. If the batch may have changed, rerun `airscale_start_contact_enrichment_export` with `confirm_credit_spend` set to false or omitted to obtain the current maximum, then review again.
7. Only after approval should you set `confirm_credit_spend` to true. That confirmed start creates the export job and freezes the batch.
### Finish either export
Start once. While status is `queued` or `running`, poll status for the same export job using the same `export_id` and returned `poll_after_seconds`. When status is `completed` or `failed`, stop polling; retrieve the file only after completion. Do not start the export again.
## Security notes
- OAuth keeps workspace credential resolution server-side; the hosted client does not receive or store the Airscale API key.
- Header-capable developer clients should read `AIRSCALE_API_KEY` only from a protected runtime environment or secret manager.
- Never put a literal key in prompts, tool arguments, source control, browser code, shell commands, or shell history.
- Verify the intended workspace before paid actions because a credit balance alone does not identify it.
- Review every paid tool name, scope, and maximum cost before approval.
- If a developer API key is exposed or suspected compromised, rotate it immediately, update the protected secret, and reconnect every trusted client that used it.
- Treat tokenized export URLs and exported files as sensitive. Never place them in prompts or logs, and follow your organization's access, retention, and deletion rules.
## Troubleshooting
For OAuth, restart browser sign-in and verify the intended workspace. For a header-capable developer client, confirm that its protected runtime can read the configured secret.
Confirm that the server URL is exactly `https://mcp.airscale.io/mcp`, then disconnect and reconnect so the client refreshes all 42 tools.
Run `airscale_check_credits`, reduce the paid scope, and review the maximum again. Do not repeatedly submit the same paid request.
Continue polling the same `export_id` at `poll_after_seconds`. Do not create a duplicate while its outcome is unknown.
---
## Airscale CLI
Source: https://docs.airscale.io/cli/overview.md
Description: Install the Airscale CLI, preview a contact file for free, connect a workspace, and run bounded searches and enrichment.
`airscale` lets you search for people and companies, enrich work emails from CSV or JSONL, check credits, and follow durable runs from a terminal.
## Install
Requires **Node.js 20.3 or newer**. This guide covers CLI **0.2.1**. If you installed an earlier version, follow the [upgrade instructions](/cli/troubleshooting#upgrade-the-cli).
```bash
npx @airscale/cli --help
```
Replace `airscale` with `npx @airscale/cli` in the examples below.
```bash
npm install --global @airscale/cli
airscale --help
```
## Preview a file for free
Create `contacts.csv` with two fictional contacts and reserved example domains:
```csv contacts.csv
first_name,last_name,domain
Avery,Stone,northstar.example
Morgan,Lee,solstice.example
```
Validate both rows and calculate the maximum exposure locally:
```bash
airscale enrich file contacts.csv \
--dry-run --json --quiet
```
This dry run needs no `--output` or confirmation. It runs without credentials, HTTP requests, or credit spend. With `--json --quiet`, stdout contains only:
```json
{
"rows": 2,
"valid_rows": 2,
"estimated_max_credits": 4,
"field": "work_email",
"format": "csv",
"output": null,
"dry_run": true
}
```
## Connect your workspace
Create a workspace key in the [Airscale dashboard](https://app.airscale.io/dashboard), under **Settings → API key**, then enter it through the hidden prompt:
```bash
airscale auth login
airscale auth status --json
```
`auth login` stores the key locally and shows `airscale auth status` as the next step. The status command makes a free `/credits` request to verify the key and connectivity. It displays the credential source and a short fingerprint without printing the key.
For a guided first-time flow, run:
```bash
airscale setup
```
`setup` points you to **Settings → API key**, checks for an existing credential, and uses the hidden prompt only when none exists. It finishes with the same free credit check. The command is interactive; scripts should configure `AIRSCALE_API_KEY` through a secret manager.
API keys cannot be passed as command-line arguments. `AIRSCALE_API_KEY` takes precedence over a saved credential.
## Enrich the sample
Replace the fictional rows with contacts you are authorized to enrich, then run the free preview again. Review any validation errors and the updated estimate before starting paid work.
For a validated two-row file, provide a real output path and approve a maximum of 4 credits:
```bash
airscale enrich file contacts.csv \
--output contacts-enriched.csv --max-credits 4 \
--confirm-credit-spend --resume --json
```
Fresh paid execution requires `--output`. `--resume` saves credential-free state so the same command can continue an interrupted run without starting a replacement batch. Keep the input, output path, field, format, and API URL unchanged when resuming.
## More bounded examples
Find up to five people with a maximum exposure of 0.5 credit:
```bash
airscale people search \
--title CTO --company-domain northstar.example \
--size 5 --max-credits 0.5 \
--confirm-credit-spend --json
```
Export up to 20 companies as CSV:
```bash
airscale companies search \
--country France --industry Software \
--size 20 --limit 20 --max-credits 2 \
--confirm-credit-spend --format csv --output companies.csv
```
Searches cost **0.1 credit per returned result**. Before paid work starts, the CLI checks the maximum row budget and available credits. Interactive terminals can confirm at the prompt; scripts must pass `--confirm-credit-spend`.
Use the `exp_…` run ID from enrichment output or saved state for free status reads:
```bash
airscale runs status exp_example --json
airscale runs wait exp_example --json
```
To download a completed enrichment file, rerun `enrich file` with `--resume`.
See the [command reference](/cli/commands) for every command, flag, input rule, and pagination behavior. See [Troubleshooting](/cli/troubleshooting) for installation, authentication, CSV, confirmation, and resume errors.
## Output and exit codes
All results, including interactive tables and `--output -`, go to stdout. Progress and errors go to stderr, so result pipelines stay clean. `--quiet` hides progress and informational messages, but never hides errors.
For `credits`, search, and run commands, choose `--json`, `--jsonl`, or `--format json|jsonl|csv|table`. A real `--output path` writes a file. When format flags are combined, `--json` takes precedence over `--jsonl`, then `--format`.
Search JSON includes the response envelope and continuation cursor. CSV and JSONL contain result records. Use JSON when you need pagination metadata.
| Exit code | Meaning |
| --- | --- |
| `0` | Success. |
| `2` | Invalid command, option, input, state, or file access. |
| `3` | Missing or invalid authentication or configuration. |
| `4` | Credit ceiling, insufficient credits, confirmation, or admission failure. |
| `5` | API or durable-run failure. |
| `130` | Interrupted with Ctrl-C; enrichment state is retained. |
## Configuration
| Setting | Configuration | Precedence or default |
| --- | --- | --- |
| API key | `AIRSCALE_API_KEY` or `airscale auth login` | Environment variable before saved credentials. `auth set-key` remains an alias. |
| API URL | `--base-url` or `AIRSCALE_API_BASE_URL` | Flag, then environment variable, then `https://api.airscale.io/v1`. |
| Credential file directory | `XDG_CONFIG_HOME` | `$XDG_CONFIG_HOME/airscale`, otherwise `~/.config/airscale`. |
Saved credentials use the optional system keychain when available, under service `airscale` and account `default`. Otherwise they are stored in `config.json` inside the credential directory, with file permissions `0600` and directory permissions `0700`.
API URLs must use HTTPS, except for HTTP on loopback addresses such as `http://127.0.0.1:8787/v1`. URLs containing credentials, query parameters, or fragments are rejected.
```bash
airscale --base-url http://127.0.0.1:8787/v1 auth status --json
```
---
## Command reference
Source: https://docs.airscale.io/cli/commands.md
Description: Every Airscale CLI 0.2.1 command and flag for setup, authentication, completion, search, file enrichment, credits, and runs.
This reference covers `@airscale/cli` **0.2.1**. Start with [Airscale CLI](/cli/overview) for the free first-run workflow.
## Global flags and help
| Flag | Description |
| --- | --- |
| `--json` | Write JSON to stdout. For `enrich file`, this applies to the summary, not the completed file. |
| `--base-url ` | Override `AIRSCALE_API_BASE_URL`. Default: `https://api.airscale.io/v1`. |
| `--quiet` | Hide progress and informational messages. Errors and result output remain visible. |
| `-V, --version` | Show the CLI version. |
| `-h, --help` | Show help for the current command. |
Use `airscale help [command]` for a top-level group or append `--help` to any nested command.
```bash
airscale --version
airscale help auth
airscale setup --help
airscale people search --help
airscale enrich file --help
```
### Output flags
These flags are available on `credits`, `people search`, `companies search`, `runs status`, and `runs wait`.
| Flag | Description |
| --- | --- |
| `--output ` | Write to a file. `--output -` writes the selected result format to stdout. |
| `--format ` | One of `json`, `jsonl`, `csv`, or `table`. Defaults to a table in an interactive terminal and JSON otherwise or when writing a file. |
| `--jsonl` | Emit one JSON object per line. Search output contains result records. |
All result formats go to stdout when no file path is selected, including tables. Progress and errors go to stderr. The global `--json` flag wins over `--jsonl`, which wins over `--format`.
JSON search output preserves the response envelope and continuation cursor. CSV and JSONL contain result records. Select the format explicitly when writing a `.csv` or `.jsonl` search file; the filename does not select its format.
### Credit flags
These flags are available on both search commands and `enrich file`.
| Flag | Description |
| --- | --- |
| `--confirm-credit-spend` | Confirm the maximum credit exposure. Required to start fresh paid work in non-interactive mode; otherwise the CLI asks in the terminal. |
| `--max-credits ` | Plain positive decimal that caps maximum exposure, such as `0.5` or `4`, up to `9,007,199,254,740,991`. Scientific notation, `Infinity`, hexadecimal, and signed values are rejected. This does not replace spend confirmation. |
Credit checks are free. Search costs 0.1 credit per returned result. File enrichment previews a maximum of 2 credits per row. Row counts, page sizes, and limits remain positive integers.
## Authentication
### `airscale auth login`
Store a workspace API key through a hidden terminal prompt. It takes no arguments or command-specific flags and requires an interactive terminal.
```bash
airscale auth login
```
After saving the key, the CLI shows `airscale auth status` as the next step. The optional system keychain is used when available; otherwise the CLI writes a restricted local credential file. `AIRSCALE_API_KEY` overrides the saved key. There is no API-key command-line flag.
`airscale auth set-key` remains an alias for compatibility:
```bash
airscale auth set-key
```
### `airscale auth status`
Check configured authentication and API connectivity with a free `/credits` request. It takes no arguments or command-specific flags; use global `--json` for machine-readable status.
```bash
airscale auth status --json
```
A successful status includes `configured`, `connected`, `source`, `fingerprint`, and `base_url`. Missing credentials produce `configured: false`, `connected: false`, and `source: "none"`, then exit `3`. Invalid credentials also exit `3`. The full API key is never displayed.
### `airscale auth logout`
Remove locally saved credentials. It takes no arguments or command-specific flags.
```bash
airscale auth logout
```
This does not revoke the API key. If `AIRSCALE_API_KEY` is set, it remains active until removed from the environment.
## Guided setup
### `airscale setup`
Guide an interactive user through authentication and a free connectivity check.
```bash
airscale setup
```
The command points to the [Airscale dashboard](https://app.airscale.io/dashboard) and tells the user to choose **Settings → API key**, then checks whether a credential is already configured. If one exists, it skips the key prompt. If none exists, it accepts the key through a hidden prompt. It finishes by checking `/credits`, which does not spend credits.
In a non-interactive environment, `setup` fails before it reads any credential or makes an HTTP request. For CI, set `AIRSCALE_API_KEY` through a secret manager and run `airscale auth status --json` when a free connectivity check is needed.
## Shell completion
### `airscale completion `
Print a completion script for `bash` or `zsh`.
```bash
airscale completion bash
airscale completion zsh
```
The command writes the shell script only to stdout. It does not edit a shell profile, create files, or enable completion automatically. Review the output, then explicitly source it or save it in the completion directory used by your shell. See [Troubleshooting](/cli/troubleshooting#enable-shell-completion) for opt-in examples.
## Credits
### `airscale credits`
Show the authenticated workspace's remaining credits. This request is free and supports all [output flags](#output-flags).
```bash
airscale credits --json
airscale credits --format csv --output credits.csv
```
## Search
### Shared search flags
Both searches support the [output flags](#output-flags), [credit flags](#credit-flags), and these request and pagination flags:
| Flag | Description |
| --- | --- |
| `--request ` | Read an advanced public API request from a JSON file. Cannot be combined with convenience filters. |
| `--size ` | Integer page size from `1` to `100`. Defaults to `100` for people and `50` for companies; a company cursor carries its own page size. |
| `--cursor ` | Continue a previous search. Overrides the request file's cursor. |
| `--all` | Follow continuation cursors until exhausted or the row limit is reached. |
| `--limit ` | Integer maximum from `1` to `10000`. With `--all`, defaults to `10000`. Without `--all`, limits one page. |
`--size` also overrides a request file's size. Without `--all`, maximum exposure is the smaller of the page size and `--limit`. With `--all`, it is `--limit` (or 10,000) multiplied by 0.1 credits.
People page sizes shrink to the remaining row budget. Company cursors require a full page: the CLI stops before another page would exceed `--limit` and preserves its continuation cursor. Keep the filters unchanged when continuing with `next_cursor`.
Paid search requests are not automatically retried. If a response is lost or ambiguous, inspect API request logs before repeating the search.
### `airscale people search`
Search for people with convenience filters or an advanced [Find People request](/api-reference/find-people).
| Flag | Description |
| --- | --- |
| `--title ` | Job title. Repeat to include multiple titles. |
| `--company-domain ` | Company domain. Repeat to include multiple domains. |
| `--location ` | Location. Repeat to include multiple locations. |
Also supports every [shared search flag](#shared-search-flags).
```bash
airscale people search \
--title CTO --company-domain northstar.example \
--size 5 --max-credits 0.5 \
--confirm-credit-spend --json
```
For advanced filters, save a JSON object with the public request schema:
```json people-query.json
{
"query": {
"JobTitle": { "include": ["CTO"], "exclude": ["Assistant"] },
"currentCompany.headcount": { ">=": 20, "<=": 200 }
},
"size": 25
}
```
```bash
airscale people search --request people-query.json \
--max-credits 2.5 --confirm-credit-spend \
--jsonl --output people.jsonl
```
Unknown top-level request keys and filter names are rejected before the search.
### `airscale companies search`
Search for companies with convenience filters or an advanced [Find Companies request](/api-reference/find-companies). At least one real filter is required.
| Flag | Description |
| --- | --- |
| `--country ` | Country. Repeat to include multiple countries. |
| `--industry ` | Industry. Repeat to include multiple industries. |
Also supports every [shared search flag](#shared-search-flags).
```bash
airscale companies search \
--country France --country Germany --industry Software \
--size 50 --all --limit 200 \
--max-credits 20 --confirm-credit-spend \
--format csv --output companies.csv
```
Advanced requests use the public `filters` object. See [company filter values](/api-reference/find-companies/filter-values) for supported values.
```json company-query.json
{
"filters": {
"country": ["France"],
"industry": ["Software"]
},
"size": 20
}
```
```bash
airscale companies search --request company-query.json \
--max-credits 2 --confirm-credit-spend --json
```
## File enrichment
### `airscale enrich file `
Validate a CSV or JSONL file locally, or enrich it with professional work emails through one durable run.
| Argument or flag | Description |
| --- | --- |
| `` | A `.csv` or `.jsonl` path, or `-` to read stdin and detect the format. Maximum 10,000 records. |
| `--output ` | Required for paid execution and optional with `--dry-run`. Must differ from the input and cannot be `-`. A dry run never writes the output. |
| `--field ` | Defaults to `work_email`, the only supported field. |
| `--format ` | Completed-file format: `csv` or `jsonl`. Inferred from an explicit `.jsonl` output path; otherwise defaults to CSV. |
| `--dry-run` | Validate every row and preview maximum exposure locally, without credentials, HTTP requests, or credit spend. |
| `--resume` | Continue the saved run with the same input, output, field, format, and API URL. With no saved state, prepares fresh paid work. |
| `--state-file ` | Override the default `