Apollo People Search API

openapi: 3.0.3
info:
  title: Apollo.io API
  description: >-
    A working model of the Apollo.io REST API for sales intelligence, contact
    discovery, and data enrichment. Apollo exposes People Enrichment (single and
    bulk match), People Search, Organization Enrichment and Search, Contacts and
    Accounts management, and Sequences (emailer campaigns) over a REST interface
    at https://api.apollo.io/api/v1. All requests authenticate with an
    `x-api-key` header; some endpoints (for example People Search and account
    user listing) require a key marked as a master key. API access is gated by
    Apollo plan tier - programmatic access begins on the Professional plan.


    Grounding note: base URL, the `x-api-key` header, and the core endpoint
    paths (people/match, people/bulk_match, mixed_people/api_search,
    organizations/enrich, mixed_companies/search, contacts/search,
    accounts/search, emailer_campaigns/{id}/add_contact_ids) are taken directly
    from Apollo's published reference at docs.apollo.io. Request/response
    schemas here are modeled from the documented parameters and are illustrative,
    not exhaustive; consult the live docs for the authoritative field lists.
  version: '1.0'
  contact:
    name: Apollo.io
    url: https://www.apollo.io
  termsOfService: https://www.apollo.io/legal/terms-of-service
servers:
  - url: https://api.apollo.io/api/v1
    description: Apollo.io production API
security:
  - apiKeyAuth: []
tags:
  - name: People Enrichment
    description: Match and enrich person records, single or in bulk.
  - name: People Search
    description: Search Apollo's people database for prospects.
  - name: Organization Enrichment
    description: Match and enrich company records, single or in bulk.
  - name: Organization Search
    description: Search Apollo's company database.
  - name: Contacts
    description: Manage contacts saved in your Apollo account.
  - name: Accounts
    description: Manage accounts (companies) saved to your Apollo team.
  - name: Sequences
    description: Manage sequences (emailer campaigns) and outreach emails.
paths:
  /people/match:
    post:
      operationId: matchPerson
      tags:
        - People Enrichment
      summary: Enrich a single person
      description: >-
        Enriches data for one person. Provide any combination of identifiers
        (name, email, domain, LinkedIn URL, Apollo id). Consumes Apollo credits
        per enriched record when data is returned. Set reveal flags to unlock
        personal emails or phone numbers (phone/waterfall reveals require a
        webhook_url).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeopleMatchRequest'
      responses:
        '200':
          description: The matched and enriched person.
          content:
            application/json:
              schema:
                type: object
                properties:
                  person:
                    $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /people/bulk_match:
    post:
      operationId: bulkMatchPeople
      tags:
        - People Enrichment
      summary: Bulk enrich people
      description: >-
        Enriches data for up to ten people in a single call. Pass an array of
        person records under `details`. Consumes Apollo credits per enriched
        record returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reveal_personal_emails:
                  type: boolean
                reveal_phone_number:
                  type: boolean
                details:
                  type: array
                  maxItems: 10
                  items:
                    $ref: '#/components/schemas/PeopleMatchRequest'
      responses:
        '200':
          description: The matched people.
          content:
            application/json:
              schema:
                type: object
                properties:
                  matches:
                    type: array
                    items:
                      $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /mixed_people/api_search:
    post:
      operationId: searchPeople
      tags:
        - People Search
      summary: Search for people
      description: >-
        Searches Apollo's people database for prospects. Requires a master API
        key. Does not return email addresses or phone numbers - pair with People
        Enrichment to reveal contact details. Paginates up to 50,000 records
        (100 per page, up to 500 pages).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeopleSearchRequest'
      responses:
        '200':
          description: A page of matching people.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeopleSearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The API key is not a master key or the plan lacks access to this endpoint.
        '429':
          $ref: '#/components/responses/RateLimited'
  /organizations/enrich:
    get:
      operationId: enrichOrganization
      tags:
        - Organization Enrichment
      summary: Enrich a single organization
      description: >-
        Enriches data for one company. Provide at least one of `domain`,
        `name`, `linkedin_url`, or `website`.
      parameters:
        - name: domain
          in: query
          schema:
            type: string
          example: apollo.io
        - name: name
          in: query
          schema:
            type: string
        - name: linkedin_url
          in: query
          schema:
            type: string
        - name: website
          in: query
          schema:
            type: string
      responses:
        '200':
          description: The enriched organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /organizations/bulk_enrich:
    post:
      operationId: bulkEnrichOrganizations
      tags:
        - Organization Enrichment
      summary: Bulk enrich organizations
      description: >-
        Enriches data for up to ten companies in a single call. Path modeled
        from Apollo's documented Bulk Organization Enrichment endpoint; confirm
        the exact request shape against the live reference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                domains:
                  type: array
                  maxItems: 10
                  items:
                    type: string
      responses:
        '200':
          description: The enriched organizations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /mixed_companies/search:
    post:
      operationId: searchOrganizations
      tags:
        - Organization Search
      summary: Search for organizations
      description: >-
        Searches Apollo's company database. Consumes Apollo credits per page
        when data is returned. Paginates up to 50,000 records (100 per page, up
        to 500 pages).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationSearchRequest'
      responses:
        '200':
          description: A page of matching organizations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contacts/search:
    post:
      operationId: searchContacts
      tags:
        - Contacts
      summary: Search for contacts
      description: Searches the contacts saved in your Apollo account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                q_keywords:
                  type: string
                contact_stage_ids:
                  type: array
                  items:
                    type: string
                page:
                  type: integer
                per_page:
                  type: integer
      responses:
        '200':
          description: A page of matching contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contacts:
    post:
      operationId: createContact
      tags:
        - Contacts
      summary: Create a contact
      description: Creates a new contact in your Apollo account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactWrite'
      responses:
        '200':
          description: The created contact.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contacts/{id}:
    put:
      operationId: updateContact
      tags:
        - Contacts
      summary: Update a contact
      description: Updates an existing contact by Apollo contact id.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactWrite'
      responses:
        '200':
          description: The updated contact.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /accounts/search:
    post:
      operationId: searchAccounts
      tags:
        - Accounts
      summary: Search for accounts
      description: Searches the accounts (companies) saved to your Apollo team.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                q_organization_name:
                  type: string
                page:
                  type: integer
                per_page:
                  type: integer
      responses:
        '200':
          description: A page of matching accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /accounts:
    post:
      operationId: createAccount
      tags:
        - Accounts
      summary: Create an account
      description: Creates a new account (company) for your Apollo team.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountWrite'
      responses:
        '200':
          description: The created account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /accounts/{id}:
    put:
      operationId: updateAccount
      tags:
        - Accounts
      summary: Update an account
      description: Updates an existing account by Apollo account id.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountWrite'
      responses:
        '200':
          description: The updated account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /emailer_campaigns/search:
    post:
      operationId: searchSequences
      tags:
        - Sequences
      summary: Search for sequences
      description: >-
        Searches sequences (emailer campaigns) in your Apollo account. Path
        modeled from Apollo's documented Search for Sequences endpoint.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                q_name:
                  type: string
                page:
                  type: integer
                per_page:
                  type: integer
      responses:
        '200':
          description: A page of matching sequences.
          content:
            application/json:
              schema:
                type: object
                properties:
                  emailer_campaigns:
                    type: array
                    items:
                      $ref: '#/components/schemas/Sequence'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /emailer_campaigns/{id}/add_contact_ids:
    post:
      operationId: addContactsToSequence
      tags:
        - Sequences
      summary: Add contacts to a sequence
      description: >-
        Adds one or more contacts to a sequence (emailer campaign) so they enter
        the outreach steps. Provide the contact ids and the sending
        configuration (email account and mailbox).
      parameters:
        - name: id
          in: path
          required: true
          description: The Apollo sequence (emailer campaign) id.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contact_ids:
                  type: array
                  items:
                    type: string
                emailer_campaign_id:
                  type: string
                send_email_from_email_account_id:
                  type: string
                sequence_active_in_other_campaigns:
                  type: boolean
      responses:
        '200':
          description: The contacts were added to the sequence.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Apollo API key passed in the `x-api-key` header on every request.
        Generate keys in the Apollo developer settings. Some endpoints (for
        example People Search) require a key marked as a master key.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        Rate limit exceeded. Apollo uses fixed-window rate limiting; limits vary
        by plan and are reported via response headers and the API usage stats
        endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PeopleMatchRequest:
      type: object
      description: Identifiers used to match and enrich one person.
      properties:
        first_name:
          type: string
        last_name:
          type: string
        name:
          type: string
        email:
          type: string
        hashed_email:
          type: string
        organization_name:
          type: string
        domain:
          type: string
        id:
          type: string
        linkedin_url:
          type: string
        reveal_personal_emails:
          type: boolean
        reveal_phone_number:
          type: boolean
        run_waterfall_email:
          type: boolean
        run_waterfall_phone:
          type: boolean
        webhook_url:
          type: string
          description: Required when using phone reveal or waterfall enrichment.
    PeopleSearchRequest:
      type: object
      description: Filters for searching Apollo's people database.
      properties:
        person_titles:
          type: array
          items:
            type: string
        person_seniorities:
          type: array
          items:
            type: string
            enum:
              - owner
              - founder
              - c_suite
              - vp
              - director
              - manager
              - senior
              - entry
              - intern
        person_locations:
          type: array
          items:
            type: string
        organization_locations:
          type: array
          items:
            type: string
        organization_ids:
          type: array
          items:
            type: string
        contact_email_status:
          type: array
          items:
            type: string
        currently_using_any_of_technology_uids:
          type: array
          items:
            type: string
        q_organization_domains_list:
          type: array
          description: Company domains to filter by (up to 1,000 per request).
          items:
            type: string
        page:
          type: integer
        per_page:
          type: integer
    PeopleSearchResponse:
      type: object
      properties:
        people:
          type: array
          items:
            $ref: '#/components/schemas/Person'
        pagination:
          $ref: '#/components/schemas/Pagination'
    OrganizationSearchRequest:
      type: object
      description: Filters for searching Apollo's company database.
      properties:
        q_organization_domains_list:
          type: array
          items:
            type: string
        organization_locations:
          type: array
          items:
            type: string
        organization_num_employees_ranges:
          type: array
          items:
            type: string
        revenue_range:
          type: object
          properties:
            min:
              type: integer
            max:
              type: integer
        currently_using_any_of_technology_uids:
          type: array
          items:
            type: string
        page:
          type: integer
        per_page:
          type: integer
    Person:
      type: object
      description: A person record from Apollo's database or enrichment.
      properties:
        id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        name:
          type: string
        title:
          type: string
        seniority:
          type: string
        email:
          type: string
        email_status:
          type: string
        linkedin_url:
          type: string
        phone_numbers:
          type: array
          items:
            type: string
        organization:
          $ref: '#/components/schemas/Organization'
    Organization:
      type: object
      description: A company record from Apollo's database or enrichment.
      properties:
        id:
          type: string
        name:
          type: string
        website_url:
          type: string
        primary_domain:
          type: string
        linkedin_url:
          type: string
        industry:
          type: string
        estimated_num_employees:
          type: integer
        annual_revenue:
          type: number
        city:
          type: string
        state:
          type: string
        country:
          type: string
    Contact:
      type: object
      description: A contact saved inside your Apollo account.
      properties:
        id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        title:
          type: string
        email:
          type: string
        contact_stage_id:
          type: string
        account_id:
          type: string
    ContactWrite:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        title:
          type: string
        email:
          type: string
        organization_name:
          type: string
        account_id:
          type: string
        label_names:
          type: array
          items:
            type: string
    Account:
      type: object
      description: An account (company) saved to your Apollo team.
      properties:
        id:
          type: string
        name:
          type: string
        domain:
          type: string
        phone:
          type: string
        owner_id:
          type: string
    AccountWrite:
      type: object
      properties:
        name:
          type: string
        domain:
          type: string
        phone:
          type: string
        raw_address:
          type: string
    Sequence:
      type: object
      description: A sequence (emailer campaign) used for multi-step outreach.
      properties:
        id:
          type: string
        name:
          type: string
        active:
          type: boolean
        num_steps:
          type: integer
    Pagination:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total_entries:
          type: integer
        total_pages:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: string
        error_code:
          type: string