Apollo Io Search

To search for people at a specific company by job title:

1. Use the People API Search endpoint (POST /api/v1/mixed_people/api_search) - does NOT consume credits
2. Filter by company domain using q_organization_domains_list: ["company.com"]
3. Filter by job titles using person_titles: ["VP Engineering", "CTO"]
4. Note: This returns basic profile data but NOT email/phone - use People Enrichment to get contact details

Example - Find VPs at a specific company:

curl -X POST "https://api.apollo.io/api/v1/mixed_people/api_search" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "q_organization_domains_list": ["zenlayer.com"],
    "person_titles": ["VP Marketing", "VP Sales"],
    "per_page": 25
  }'

Setup (First Use)

Before using this skill, you need an Apollo.io API key.

On first use, ask the user:

"To use Apollo.io search, I need your API key. You can find it in your Apollo.io account under Settings > API Keys. What is your Apollo.io API key?"

Once the user provides their key:

1. Set the environment variable before running scripts:
   • macOS/Linux: export APOLLO_API_KEY="<user_provided_key>"
   • Windows (CMD): set APOLLO_API_KEY=<user_provided_key>
   • Windows (PowerShell): $env:APOLLO_API_KEY="<user_provided_key>"
2. Use the key in all API requests via header: X-Api-Key: <user_provided_key>
3. For Team endpoints, use query param: ?api_key=<user_provided_key>
4. Alternatively, pass the key directly: python apollo_search.py people --api-key "<user_provided_key>" ...

Do not store the API key in any files. Always use the environment variable or pass it directly.

Endpoints

1. People Enrichment (Get Email/Phone)

Get detailed contact information including emails and phone numbers for a specific person.

• URL: POST https://api.apollo.io/v1/people/match
• Auth: Header x-api-key: {api_key}
• Content-Type: application/json
• Rate Limit: 600 requests per hour
• Consumes Credits: Yes, based on your Apollo pricing plan

Key Parameters:

Important Notes:

• Provide as much information as possible for better match accuracy
• Email and phone are NOT returned by default - you must set reveal_personal_emails: true and/or reveal_phone_number: true
• If you set reveal_phone_number: true, you must provide a webhook_url for async delivery
• Waterfall enrichment checks third-party data sources for broader coverage
• GDPR regions: Personal emails will not be returned for people in GDPR-compliant regions

Example curl:

curl -X POST "https://api.apollo.io/v1/people/match" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -d '{
    "first_name": "Tim",
    "last_name": "Zheng",
    "organization_name": "Apollo",
    "reveal_personal_emails": true,
    "reveal_phone_number": true
  }'

Example Response (when reveal flags are true):

{
  "person": {
    "id": "64a7ff0cc4dfae00013df1a5",
    "first_name": "Tim",
    "last_name": "Zheng",
    "name": "Tim Zheng",
    "linkedin_url": "http://www.linkedin.com/in/tim-zheng-677ba010",
    "title": "Founder & CEO",
    "email": "[email protected]",
    "email_status": "verified",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "contact": {
      "contact_emails": [
        {
          "email": "[email protected]",
          "email_status": "verified",
          "position": 0
        }
      ],
      "phone_numbers": [
        {
          "raw_number": "(123) 456-7890",
          "sanitized_number": "+11234567890",
          "type": "mobile",
          "status": "valid_number"
        }
      ]
    },
    "organization": {
      "id": "5e66b6381e05b4008c8331b8",
      "name": "Apollo.io",
      "website_url": "http://www.apollo.io",
      "primary_domain": "apollo.io",
      "estimated_num_employees": 1600
    }
  }
}

2. People API Search (Find People, No Contact Info)

Find net new people in Apollo's database — optimized for API usage, does NOT consume credits.

Important: Does NOT return email addresses or phone numbers. Use People Enrichment to get contact details.

• URL: POST https://api.apollo.io/api/v1/mixed_people/api_search
• Auth: Header x-api-key: {api_key} (requires master API key)
• Content-Type: application/json
• Max: 50,000 display limit (100 per page × 500 pages)
• Rate Limit: 600 requests per hour

All Parameters (pass as query params or JSON body):

Response returns total_entries and people[] array with: id, first_name, last_name_obfuscated, title, last_refreshed_at, has_email, has_city, has_state, has_country, has_direct_phone, plus nested organization object with name and availability flags.

Use Case: Find all VPs at a Specific Company

{
  "q_organization_domains_list": ["zenlayer.com"],
  "person_titles": ["VP Engineering", "VP Marketing", "VP Sales", "VP Operations"],
  "person_seniorities": ["vp"],
  "per_page": 100
}

Example curl:

curl -X POST "https://api.apollo.io/api/v1/mixed_people/api_search" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -d '{
    "person_titles": ["VP Infrastructure", "CTO"],
    "person_seniorities": ["vp", "c_suite"],
    "organization_locations": ["singapore"],
    "organization_num_employees_ranges": ["250,1000", "1000,5000"],
    "per_page": 25,
    "page": 1
  }'

Error Codes:

• 401 — Invalid API key
• 403 — Requires master API key (API_INACCESSIBLE error)
• 422 — Invalid parameters
• 429 — Rate limit exceeded (max 600/hour)

3. Bulk People Enrichment

Enrich data for up to 10 people with a single API call. Useful for batch processing.

• URL: POST https://api.apollo.io/api/v1/people/bulk_enrichment
• Auth: Header x-api-key: {api_key}
• Rate Limit: 50% of the People Enrichment endpoint's per-minute rate limit
• Consumes Credits: Yes

Parameters:

• Same as People Enrichment but wrap person details in details array
• api_key: Your API key
• details[]: Array of person objects (max 10)
• reveal_personal_emails: boolean
• reveal_phone_number: boolean
• webhook_url: Required if revealing phone numbers

Example:

curl -X POST "https://api.apollo.io/api/v1/people/bulk_enrichment" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "{YOUR_APOLLO_API_KEY}",
    "details": [
      {
        "first_name": "John",
        "last_name": "Smith",
        "organization_name": "Acme Corp"
      },
      {
        "first_name": "Jane",
        "last_name": "Doe",
        "organization_name": "Tech Inc"
      }
    ],
    "reveal_personal_emails": true,
    "reveal_phone_number": true
  }'

4. Organization (Company) Search

Find companies in Apollo's database — consumes credits per Apollo pricing plan.

• URL: POST https://api.apollo.io/api/v1/mixed_companies/search
• Auth: Header x-api-key: {api_key}
• Content-Type: application/json
• Max: 50,000 display limit (100 per page × 500 pages)
• Rate Limit: 600 requests per hour

All Parameters (pass as query params or JSON body):

Response returns organizations[] array with: id, name, website_url, linkedin_url, twitter_url, facebook_url, phone, primary_domain, founded_year, publicly_traded_symbol, publicly_traded_exchange, logo_url, languages[], alexa_ranking, linkedin_uid, plus pagination object.

Common Filters:

{
  "q_organization_name": "Zenlayer",
  "organization_locations": ["Singapore", "Hong Kong", "China"],
  "organization_num_employees_ranges": ["1000,10000"]
}

Example curl:

curl -X POST "https://api.apollo.io/api/v1/mixed_companies/search" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -d '{
    "q_organization_keyword_tags": ["cloud infrastructure"],
    "organization_locations": ["singapore"],
    "organization_num_employees_ranges": ["250,1000", "1000,5000"],
    "per_page": 25,
    "page": 1
  }'

Error Codes:

• 401 — Invalid API key
• 403 — Endpoint requires paid Apollo plan
• 429 — Rate limit exceeded (max 600/hour)

5. People Enrichment — Get Email & Phone Numbers

Enrich a person's profile to retrieve verified email addresses and phone numbers. This endpoint consumes credits based on your Apollo pricing plan.

• URL: POST https://api.apollo.io/api/v1/people/match
• Auth: Header x-api-key: {api_key} (requires master API key)
• Content-Type: application/json
• Rate Limit: 600 requests per hour

Query Parameters:

Important Notes:

• The People search endpoint (mixed_people/api_search) does NOT return email/phone — use THIS endpoint instead
• Email/phone retrieval consumes credits based on your Apollo plan
• Waterfall enrichment may consume more credits but has higher success rates
• Use email parameter for exact lookup, OR use name + domain for fuzzy matching

Example curl — Search by email:

curl -X POST "https://api.apollo.io/api/v1/people/match?email=john.doe%40zenlayer.com&reveal_personal_emails=true&reveal_phone_number=true" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache"

Example curl — Search by name + domain:

curl -X POST "https://api.apollo.io/api/v1/people/match?first_name=John&last_name=Doe&domain=zenlayer.com&reveal_personal_emails=true&reveal_phone_number=true" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache"

Response Fields (email/phone in person object):

{
  "person": {
    "id": "5d8f8f8f8f8f8f8f8f8f8f8",
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "email_status": "verified",
    "phone_numbers": [
      {
        "raw_number": "(555) 123-4567",
        "sanitized_number": "+15551234567",
        "type": "mobile",
        "status": "valid_number"
      }
    ],
    "title": "VP Engineering",
    "linkedin_url": "https://linkedin.com/in/johndoe",
    "organization": {
      "id": "5f5f5f5f5f5f5f5f5f5f5f5f",
      "name": "Zenlayer",
      "domain": "zenlayer.com"
    }
  }
}

Error Codes:

• 401 — Invalid API key
• 403 — Requires master API key (API_INACCESSIBLE error)
• 422 — Invalid parameters
• 429 — Rate limit exceeded

6. Bulk People Enrichment — Get Email & Phone for Multiple Contacts

Enrich up to 10 people at once. Same credit rules apply.

• URL: POST https://api.apollo.io/api/v1/people/bulk_match
• Auth: Header x-api-key: {api_key} (requires master API key)
• Content-Type: application/json
• Max: 10 people per request

Query Parameters (same as single enrichment):

• reveal_personal_emails: boolean
• reveal_phone_number: boolean
• run_waterfall_email: boolean
• run_waterfall_phone: boolean

Request Body:

{
  "details": [
    { "email": "[email protected]" },
    { "first_name": "Jane", "last_name": "Smith", "domain": "apolo.io" },
    { "id": "64a7ff0cc4dfae00013df1a5" }
  ]
}

Example curl:

curl -X POST "https://api.apollo.io/api/v1/people/bulk_match?reveal_personal_emails=true&reveal_phone_number=true" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -d '{
    "details": [
      { "email": "[email protected]" },
      { "first_name": "Jane", "last_name": "Smith", "domain": "apollo.io" }
    ]
  }'

Response: Returns matches[] array with enriched person data, plus credits_consumed count.

7. Search Team Contacts

Search contacts explicitly added to your team's Apollo account.

• URL: POST https://api.apollo.io/api/v1/contacts/api_search
• Auth: Query param ?api_key={api_key} (master key required)

8. Search Team Sequences

Find sequences created for your team.

• URL: POST https://api.apollo.io/api/v1/sequences/api_search
• Auth: Query param ?api_key={api_key} (master key required)

Common Workflows

Workflow 1: Find Contact Info for a Specific Person

Step 1: Use People Enrichment API (this consumes credits):

# Option A: Search by email
curl -X POST "https://api.apollo.io/api/v1/people/match?email=marko.stankovic%40zenlayer.com&reveal_personal_emails=true&reveal_phone_number=true" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache"

# Option B: Search by name + domain
curl -X POST "https://api.apollo.io/api/v1/people/match?first_name=Marko&last_name=Stankovic&domain=zenlayer.com&reveal_personal_emails=true&reveal_phone_number=true" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache"

Response includes: email, email_status, phone_numbers[] array with sanitized_number.

### Workflow 2: Find All Decision Makers at a Company + Get Their Contact Info
```bash
# Step 1: Search for people by domain (no credits, returns list without email/phone)
curl -X POST "https://api.apollo.io/api/v1/mixed_people/api_search" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "q_organization_domains_list": ["zenlayer.com"],
    "person_titles": ["VP", "Director", "Head", "CTO", "CMO"],
    "person_seniorities": ["vp", "director", "head", "c_suite"],
    "per_page": 100
  }'

# Step 2: For each person found, enrich to get email and phone
# (consumes credits per person enriched)
curl -X POST "https://api.apollo.io/api/v1/people/match?id=APOLLO_PERSON_ID&reveal_personal_emails=true&reveal_phone_number=true" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache"

Tip: Use Bulk People Enrichment for up to 10 people at once to reduce API calls.

Workflow 3: Find Companies Then Their Executives

# Step 1: Find target companies
curl -X POST "https://api.apollo.io/api/v1/mixed_companies/search" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "q_organization_keyword_tags": ["cloud infrastructure"],
    "organization_locations": ["singapore"],
    "organization_num_employees_ranges": ["100,1000"]
  }'

# Step 2: Search for executives at each company using domain

Zenlayer-Specific Search Patterns

Emerging Markets Prospecting

{
  "person_titles": ["VP Infrastructure", "Director Cloud Operations", "Head of Engineering"],
  "person_seniorities": ["vp", "director", "head"],
  "organization_locations": ["Indonesia", "Nigeria", "Brazil", "India", "Vietnam", "Egypt", "South Africa", "Mexico", "Colombia"],
  "q_keywords": "edge computing OR low latency OR GPU infrastructure OR cloud gaming"
}

Global Infrastructure Decision Makers

{
  "person_titles": ["VP Network Operations", "Director Global Infrastructure", "CTO", "Head of Platform Engineering"],
  "person_seniorities": ["vp", "c_suite", "director", "head"],
  "q_keywords": "global infrastructure OR multi-region OR CDN OR edge computing OR cloud gaming OR real-time computing",
  "organization_num_employees_ranges": ["500,50000"]
}

AI/GPU Prospecting

{
  "person_titles": ["VP AI/ML", "Head of AI Infrastructure", "Director GPU Operations"],
  "person_seniorities": ["vp", "director", "head"],
  "q_keywords": "generative AI OR LLM OR GPU cluster OR AI training OR distributed inference",
  "organization_num_employees_ranges": ["1000,50000"]
}

Response Fields

Person Object (from People Enrichment)

{
  "id": "5d8f8f8f8f8f8f8f8f8f8f8",
  "first_name": "Jane",
  "last_name": "Zhao",
  "name": "Jane Zhao",
  "linkedin_url": "https://www.linkedin.com/in/jane-zhao-1234",
  "title": "VP of Cloud Infrastructure",
  "seniority": "vp",
  "email": "[email protected]",
  "email_status": "verified",
  "city": "San Francisco",
  "state": "California",
  "country": "United States",
  "contact": {
    "contact_emails": [
      {
        "email": "[email protected]",
        "email_status": "verified"
      }
    ],
    "phone_numbers": [
      {
        "raw_number": "(415) 123-4567",
        "sanitized_number": "+14151234567",
        "type": "mobile",
        "status": "valid_number"
      }
    ]
  },
  "organization": {
    "id": "5f5f5f5f5f5f5f5f5f5f5f5f",
    "name": "Global Gaming Corp",
    "domain": "globalgaming.com",
    "industry": "Gaming",
    "estimated_num_employees": 3500
  }
}

Organization Object

{
  "id": "5f5f5f5f5f5f5f5f5f5f5f5f",
  "name": "Zenlayer Inc",
  "domain": "zenlayer.com",
  "linkedin_url": "https://www.linkedin.com/company/zenlayer",
  "industry": "Telecommunications",
  "estimated_num_employees": 550
}

Pagination

All searches support pagination:

• page: Current page number (default: 1)
• per_page: Results per page (max: 100)

Example:

curl -X POST "https://api.apollo.io/api/v1/mixed_people/api_search" \
  -H "x-api-key: {YOUR_APOLLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -d '{"person_titles":["VP Engineering"],"page":2,"per_page":100}'

Rate Limits

Check headers returned:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Requests remaining in current window

Rate limits vary by Apollo plan (per minute/hour/day thresholds apply).

Endpoint-Specific Limits:

• People API Search: 600/hour
• People Enrichment: 600/hour
• Bulk People Enrichment: 50% of People Enrichment rate
• Organization Search: 600/hour

Quick Script

See scripts/apollo_search.py for Python search function with:

• Automatic pagination
• JSON/CSV export
• Error handling
• Rate limit tracking

Troubleshooting

Error 403 (error code: 1010):

• The Organization Search endpoint consumes credits — verify your Apollo plan has credits
• Team Contacts/Sequences require master API key (query param auth, not header)
• Some endpoints may require paid plan or different authentication

No email/phone in response:

• Make sure you've set reveal_personal_emails: true and/or reveal_phone_number: true
• Check if the person is in a GDPR region (personal emails won't be returned)
• Verify you have sufficient API credits

Webhook not receiving phone numbers:

• Ensure your webhook URL is publicly accessible over HTTPS
• Check that you've included webhook_url parameter when reveal_phone_number: true

See references/troubleshooting.md for complete error codes and solutions.

References

• Full API documentation: references/people-api-search.md
• Organization search reference: references/organization-api-search.md
• People Enrichment reference: references/people-enrichment.md
• Troubleshooting guide: references/troubleshooting.md