Skip to content

Instantly share code, notes, and snippets.

@kmahorker

kmahorker/testopenapi.yaml

Created March 19, 2025 04:53
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save kmahorker/52276eaaebe670210de8338cdc06492c to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save kmahorker/52276eaaebe670210de8338cdc06492c to your computer and use it in GitHub Desktop.
Download ZIP
Raw
testopenapi.yaml
openapi: 3.0.0
info:
title: Apollo.io API
version: 1.0.0
description: |
Combined API specification for Apollo.io endpoints.
All endpoints are accessible via https://app.apollo.io/api/v1
## Important Notes
1. Many parameters require prerequisite API calls to resolve their values
2. Some filters use bootstrapped data loaded during application initialization
3. All search endpoints support pagination and caching
4. Most endpoints require authentication via Bearer token
servers:
- url: https://app.apollo.io/api/v1
description: Apollo.io API server
paths:
/api/v1/mixed_people/search:
post:
summary: Search for people and contacts
description: |
Search for people and contacts with advanced filtering capabilities.
## Prerequisites
Before using certain parameters, you must first resolve their values:
1. Organization IDs:
- Call GET /organizations/search with company name
- Use returned IDs in organization_ids parameter
2. Location Values:
- Call GET /tags/search with kind="location"
- Use returned UIDs in location parameters
3. Technology Tags:
- Call GET /tags/search with kind="technology"
- Use returned UIDs in technology parameters
4. Industry Tags:
- Call GET /tags/search with kind="linkedin_industry"
- Use returned UIDs in industry parameters
5. Seniority Levels:
- Call GET /facets with facet_key="personSeniorityFacets"
- Use returned values in person_seniorities parameter
6. Department/Subdepartment:
- Use bootstrapped subdepartments configuration
- No API call needed
7. Company Size Ranges:
- Use bootstrapped numEmployeesFacets configuration
- No API call needed
## Filter Categories:
- Contact and person attributes
- Organization details
- Email engagement metrics
- Technology usage
- Intent signals
- Location and department filters
- Custom fields and recommendations
operationId: apollo_search_search_mixed_people
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
cacheKey:
type: string
description: Timestamp for cache invalidation
example: '1741993547532'
context:
type: string
description: Context identifier for the page making the request
example: people-index-page
display_mode:
type: string
enum:
- explorer_mode
description: Display mode for the results
finder_version:
type: integer
description: Version of the finder being used
example: 2
page:
type: integer
description: Page number for pagination
minimum: 1
example: 1
per_page:
type: integer
description: Number of results per page
example: 25
fields:
type: array
items:
type: string
description: Fields to return in the response
organization_ids:
type: array
items:
type: string
description: |
Organization IDs to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /organizations/search with company name
2. Use returned organization IDs in this parameter
person_seniorities:
type: array
items:
type: string
description: |
Seniority levels to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /facets with facet_key="personSeniorityFacets"
2. Use returned values in this parameter
currently_using_any_of_technology_uids:
type: array
items:
type: string
description: |
Technology UIDs to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /tags/search with kind="technology"
2. Use returned UIDs in this parameter
person_locations:
type: array
items:
type: string
description: |
Location UIDs to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /tags/search with kind="location"
2. Use returned UIDs in this parameter
organization_job_locations:
type: array
items:
type: string
description: |
Job location UIDs to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /tags/search with kind="location"
2. Use returned UIDs in this parameter
organization_num_employees_ranges:
type: array
items:
type: string
description: |
Employee count ranges to filter by. Uses bootstrapped data.
Valid ranges:
- "1,10" (1-10 employees)
- "11,20" (11-20 employees)
- "21,50" (21-50 employees)
- "51,100" (51-100 employees)
- "101,200" (101-200 employees)
- "201,500" (201-500 employees)
- "501,1000" (501-1000 employees)
contact_email_status_v2:
type: array
items:
type: string
enum:
- verified
- unverified
- invalid
description: Email verification status to filter by
contact_label_ids:
type: array
items:
type: string
description: |
Contact label IDs to filter by. Must be valid MongoDB ObjectIds.
Labels are managed through the labels management interface.
contact_last_activity_date_range:
type: object
properties:
min:
type: string
format: date
max:
type: string
format: date
description: |
Date range for last activity.
Validation rules:
- min must be before max
- dates cannot be in the future
required:
- context
- display_mode
- finder_version
- page
- per_page
- fields
responses:
'200':
description: Successful search response
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
description: Person or contact object with requested fields
total_count:
type: integer
description: Total number of matching results
page:
type: integer
description: Current page number
total_pages:
type: integer
description: Total number of pages
'400':
description: Bad request - invalid parameters
'401':
description: Unauthorized - authentication required
'403':
description: Forbidden - insufficient permissions
/api/v1/organizations/search:
get:
summary: Search for organizations
description: |
Search organizations by fuzzy name matching or fetch specific organizations by IDs.
This endpoint is commonly used as a prerequisite call to resolve company names to IDs
before using them in the mixed_people/search endpoint.
## Usage Flow:
1. Call this endpoint with company name
2. Extract organization IDs from response
3. Use IDs in mixed_people/search organization_ids parameter
## Response Format:
```json
{
"organizations": [
{
"id": "string", // Use this ID in organization_ids
"name": "string", // Display name
"logoUrl": "string", // Optional company logo
"domain": "string" // Company domain
}
]
}
```
parameters:
- name: display_mode
in: query
required: true
schema:
type: string
enum:
- fuzzy_select_mode
description: Display mode for results, must be "fuzzy_select_mode"
- name: q_organization_fuzzy_name
in: query
required: false
schema:
type: string
description: Fuzzy search query for organization names. Required when not using ids[]
- name: ids[]
in: query
required: false
schema:
type: array
items:
type: string
description: Array of specific organization IDs to fetch. Required when not using q_organization_fuzzy_name
style: form
explode: true
- name: per_page
in: query
required: false
schema:
type: integer
description: Number of results per page (default varies by context)
- name: cacheKey
in: query
required: false
schema:
type: string
description: Cache key for invalidating cached responses
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
num_fetch_result:
type: integer
nullable: true
description: Number of results fetched
organizations:
type: array
items:
type: object
properties:
name:
type: string
example: Google
domain:
type: string
example: google.com
website_url:
type: string
example: http://www.google.com
required:
- name
- domain
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Unauthorized
operationId: apollo_search_get_api_v1_organizations_search
/api/v1/labels/search:
get:
summary: Search for contact labels
description: Search and retrieve available contact labels for filtering
parameters:
- name: q_label_fuzzy_name
in: query
required: false
schema:
type: string
description: Fuzzy search query for label names
- name: display_mode
in: query
required: true
schema:
type: string
enum:
- fuzzy_select_mode
description: Display mode for results
- name: per_page
in: query
required: false
schema:
type: integer
description: Number of results per page
- name: cacheKey
in: query
required: false
schema:
type: string
description: Cache key for invalidating cached responses
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
labels:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
color:
type: string
count:
type: integer
required:
- id
- name
'401':
$ref: '#/components/responses/Unauthorized'
operationId: apollo_search_get_api_v1_labels_search
/api/v1/departments/search:
get:
summary: Search for departments and subdepartments
description: Retrieve available departments and their subdepartments for filtering
parameters:
- name: q_department_fuzzy_name
in: query
required: false
schema:
type: string
description: Fuzzy search query for department names
- name: display_mode
in: query
required: true
schema:
type: string
enum:
- fuzzy_select_mode
description: Display mode for results
- name: include_subdepartments
in: query
required: false
schema:
type: boolean
description: Whether to include subdepartments in the response
default: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
departments:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
subdepartments:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
parent_id:
type: string
count:
type: integer
count:
type: integer
required:
- id
- name
'401':
$ref: '#/components/responses/Unauthorized'
operationId: apollo_search_get_api_v1_departments_search
/api/v1/locations/search:
get:
summary: Search for locations
description: Search and retrieve locations for filtering
parameters:
- name: q_location_fuzzy_name
in: query
required: false
schema:
type: string
description: Fuzzy search query for location names
- name: display_mode
in: query
required: true
schema:
type: string
enum:
- fuzzy_select_mode
description: Display mode for results
- name: type
in: query
required: false
schema:
type: string
enum:
- city
- state
- country
- region
description: Type of locations to search for
- name: per_page
in: query
required: false
schema:
type: integer
description: Number of results per page
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
locations:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
type:
type: string
enum:
- city
- state
- country
- region
count:
type: integer
required:
- id
- name
- type
'401':
$ref: '#/components/responses/Unauthorized'
operationId: apollo_search_get_api_v1_locations_search
/api/v1/locations/radius_search:
get:
summary: Search locations within radius
description: Search for locations within a specified radius of a ZIP code
parameters:
- name: zip_code
in: query
required: true
schema:
type: string
description: ZIP code to search around
- name: radius_miles
in: query
required: true
schema:
type: integer
enum:
- 5
- 10
- 25
- 50
- 100
description: Radius in miles to search within
- name: display_mode
in: query
required: true
schema:
type: string
enum:
- fuzzy_select_mode
description: Display mode for results
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
locations:
type: array
items:
type: object
properties:
zip_code:
type: string
city:
type: string
state:
type: string
distance:
type: number
count:
type: integer
required:
- zip_code
- city
- state
- distance
'400':
description: Invalid ZIP code
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid ZIP code
'401':
$ref: '#/components/responses/Unauthorized'
operationId: apollo_search_get_api_v1_locations_radius_search
/api/v1/job_titles/search:
get:
summary: Search for job titles
description: Search and retrieve job titles for filtering
parameters:
- name: q_title_fuzzy_name
in: query
required: false
schema:
type: string
description: Fuzzy search query for job titles
- name: display_mode
in: query
required: true
schema:
type: string
enum:
- fuzzy_select_mode
description: Display mode for results
- name: per_page
in: query
required: false
schema:
type: integer
description: Number of results per page
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
titles:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
count:
type: integer
required:
- id
- name
'401':
$ref: '#/components/responses/Unauthorized'
operationId: apollo_search_get_api_v1_job_titles_search
/api/v1/tags/search:
get:
summary: Search for tags based on type and query
description: |
Search and retrieve tags filtered by type. This endpoint is used to resolve
values for multiple filter types in the mixed_people/search endpoint.
## Tag Types (kind parameter):
1. technology: Technology usage tags
- Used for currently_using_any_of_technology_uids parameter
2. location: Location tags
- Used for person_locations and organization_job_locations parameters
- Typically excludes "US state" category
3. linkedin_industry: Industry tags
- Used for industry filters
## Usage Notes:
- Results are sorted alphabetically by label
- Each tag has a unique ID (uid), clean name, and category
- Technology values are managed through a tag system with categories
- Location searches typically exclude US states using exclude_categories
parameters:
- name: q_tag_fuzzy_name
in: query
required: true
schema:
type: string
description: Search query string for fuzzy matching
- name: display_mode
in: query
required: true
schema:
type: string
enum:
- fuzzy_select_mode
description: Must be "fuzzy_select_mode"
- name: kind
in: query
required: true
schema:
type: string
enum:
- technology
- location
- linkedin_industry
description: |
Type of tags to search:
- technology: For technology usage filters
- location: For location-based filters
- linkedin_industry: For industry filters
- name: exclude_categories
in: query
required: false
schema:
type: array
items:
type: string
description: |
Categories to exclude from results.
Common usage: ["US state"] for location searches
- name: perPage
in: query
required: false
schema:
type: integer
description: |
Number of results per page.
Defaults:
- Industry search: 200 results
- Location search: No default limit
- Technology search: No default limit
- name: ids
in: query
required: false
schema:
type: array
items:
type: string
description: Specific tag IDs to fetch
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
tags:
type: array
items:
type: object
properties:
uid:
type: string
cleanedName:
type: string
category:
type: string
name:
type: string
logoUrl:
type: string
domain:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
operationId: apollo_search_get_api_v1_tags_search
/api/v1/facets:
get:
summary: Fetch faceted filter options
description: |
Retrieve faceted filter options for various entity types. This endpoint is used
to resolve values for multiple filters in the mixed_people/search endpoint.
## Facet Keys:
1. personSeniorityFacets:
- Used for person_seniorities parameter
- Returns available seniority levels
2. organizationFundingStageFacets:
- Used for organization_latest_funding_stage_cd parameter
- Returns available funding stages
3. contactJobChangedFacets:
- Used for job change filters
- Returns job change status options
4. organizationTradingStatusFacets:
- Used for organization_trading_status parameter
- Returns available trading status options
5. organizationIntentScoringFacets:
- Used for intent scoring filters
- Returns available intent score options
## Usage Notes:
- Some facets are also available in bootstrapped data
- Values include display name and count information
- Facets are used for dropdown/select filter options
parameters:
- name: facet_key
in: query
required: true
schema:
type: string
enum:
- personSeniorityFacets
- organizationFundingStageFacets
- contactJobChangedFacets
- organizationTradingStatusFacets
- organizationIntentScoringFacets
description: |
Type of facets to fetch:
- personSeniorityFacets: Seniority level options
- organizationFundingStageFacets: Company funding stages
- contactJobChangedFacets: Job change status options
- organizationTradingStatusFacets: Company trading status
- organizationIntentScoringFacets: Intent scoring options
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
facets:
type: array
items:
type: object
properties:
value:
type: string
description: Option identifier
label:
type: string
description: Display name
count:
type: integer
description: Number of records
'401':
$ref: '#/components/responses/Unauthorized'
operationId: apollo_search_get_api_v1_facets
/api/v1/auth/check:
get:
summary: Check authentication status and get bootstrapped data
description: Verifies if the user is currently logged in and returns bootstrapped application data
parameters:
- name: timezone_offset
in: query
required: true
schema:
type: integer
description: Client's timezone offset in minutes
example: 420
- name: current_finder_view_id
in: query
required: false
schema:
type: string
description: ID of the current finder view
- name: cacheKey
in: query
required: false
schema:
type: string
description: Cache key for invalidating cached responses
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
is_logged_in:
type: boolean
description: Whether the user is currently logged in
maintenance_alert:
type: object
nullable: true
description: System maintenance alerts if any
bootstrapped_data:
type: object
description: Application bootstrapped data
properties:
current_user_id:
type: string
example: 61d448d3103b47012f9bf6be
current_team_id:
type: string
example: 551e3ef07261695147160000
feature_flags:
type: object
properties:
ai_assistant_mvp:
type: boolean
ai_sdr:
type: boolean
apollo_boost_enabled:
type: boolean
companies_finder_v2:
type: boolean
'401':
$ref: '#/components/responses/Unauthorized'
operationId: apollo_search_get_api_v1_auth_check
components:
schemas:
MixedPeopleSearchRequest:
type: object
properties:
cacheKey:
type: string
description: Timestamp for cache invalidation
example: '1741993547532'
context:
type: string
description: Context identifier for the page making the request
example: people-index-page
display_mode:
type: string
enum:
- explorer_mode
description: Display mode for the results
finder_version:
type: integer
description: Version of the finder being used
example: 2
page:
type: integer
description: Page number for pagination
minimum: 1
example: 1
per_page:
type: integer
description: Number of results per page
example: 25
fields:
type: array
items:
type: string
description: Fields to return in the response
organization_ids:
type: array
items:
type: string
description: |
Organization IDs to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /organizations/search with company name
2. Use returned organization IDs in this parameter
person_seniorities:
type: array
items:
type: string
description: |
Seniority levels to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /facets with facet_key="personSeniorityFacets"
2. Use returned values in this parameter
currently_using_any_of_technology_uids:
type: array
items:
type: string
description: |
Technology UIDs to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /tags/search with kind="technology"
2. Use returned UIDs in this parameter
person_locations:
type: array
items:
type: string
description: |
Location UIDs to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /tags/search with kind="location"
2. Use returned UIDs in this parameter
organization_job_locations:
type: array
items:
type: string
description: |
Job location UIDs to filter by. REQUIRES PREREQUISITE CALL:
1. Call GET /tags/search with kind="location"
2. Use returned UIDs in this parameter
organization_num_employees_ranges:
type: array
items:
type: string
description: |
Employee count ranges to filter by. Uses bootstrapped data.
Valid ranges:
- "1,10" (1-10 employees)
- "11,20" (11-20 employees)
- "21,50" (21-50 employees)
- "51,100" (51-100 employees)
- "101,200" (101-200 employees)
- "201,500" (201-500 employees)
- "501,1000" (501-1000 employees)
contact_email_status_v2:
type: array
items:
type: string
enum:
- verified
- unverified
- invalid
description: Email verification status to filter by
contact_label_ids:
type: array
items:
type: string
description: |
Contact label IDs to filter by. Must be valid MongoDB ObjectIds.
Labels are managed through the labels management interface.
contact_last_activity_date_range:
type: object
properties:
min:
type: string
format: date
max:
type: string
format: date
description: |
Date range for last activity.
Validation rules:
- min must be before max
- dates cannot be in the future
required:
- context
- display_mode
- finder_version
- page
- per_page
- fields
MixedPeopleSearchResponse:
type: object
properties:
results:
type: array
items:
type: object
description: Person or contact object with requested fields
total_count:
type: integer
description: Total number of matching results
page:
type: integer
description: Current page number
total_pages:
type: integer
description: Total number of pages
OrganizationsSearchResponse:
type: object
properties:
num_fetch_result:
type: integer
nullable: true
description: Number of results fetched
organizations:
type: array
items:
type: object
properties:
name:
type: string
example: Google
domain:
type: string
example: google.com
website_url:
type: string
example: http://www.google.com
required:
- name
- domain
LabelsSearchResponse:
type: object
properties:
labels:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
color:
type: string
count:
type: integer
required:
- id
- name
DepartmentsSearchResponse:
type: object
properties:
departments:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
subdepartments:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
parent_id:
type: string
count:
type: integer
count:
type: integer
required:
- id
- name
LocationsSearchResponse:
type: object
properties:
locations:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
type:
type: string
enum:
- city
- state
- country
- region
count:
type: integer
required:
- id
- name
- type
LocationsRadiusSearchResponse:
type: object
properties:
locations:
type: array
items:
type: object
properties:
zip_code:
type: string
city:
type: string
state:
type: string
distance:
type: number
count:
type: integer
required:
- zip_code
- city
- state
- distance
JobTitlesSearchResponse:
type: object
properties:
titles:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
count:
type: integer
required:
- id
- name
TagsSearchResponse:
type: object
properties:
tags:
type: array
items:
type: object
properties:
uid:
type: string
cleanedName:
type: string
category:
type: string
name:
type: string
logoUrl:
type: string
domain:
type: string
FacetsResponse:
type: object
properties:
facets:
type: array
items:
type: object
properties:
value:
type: string
description: Option identifier
label:
type: string
description: Display name
count:
type: integer
description: Number of records
AuthCheckResponse:
type: object
properties:
is_logged_in:
type: boolean
description: Whether the user is currently logged in
maintenance_alert:
type: object
nullable: true
description: System maintenance alerts if any
bootstrapped_data:
type: object
description: Application bootstrapped data
properties:
current_user_id:
type: string
example: 61d448d3103b47012f9bf6be
current_team_id:
type: string
example: 551e3ef07261695147160000
feature_flags:
type: object
properties:
ai_assistant_mvp:
type: boolean
ai_sdr:
type: boolean
apollo_boost_enabled:
type: boolean
companies_finder_v2:
type: boolean
responses:
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Unauthorized
securitySchemes:
BearerAuth:
type: http
scheme: bearer
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment