openapi: 3.0.3
info:
  title: Apollo.io Accounts Contacts 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: Contacts
  description: Manage contacts saved in your Apollo account.
paths:
  /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'
components:
  responses:
    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'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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
    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
    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
  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.