openapi: 3.0.3
info:
  title: Apollo.io Accounts 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: Accounts
  description: Manage accounts (companies) saved to your Apollo team.
paths:
  /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'
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:
    Error:
      type: object
      properties:
        error:
          type: string
        error_code:
          type: string
    Pagination:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total_entries:
          type: integer
        total_pages:
          type: integer
    AccountWrite:
      type: object
      properties:
        name:
          type: string
        domain:
          type: string
        phone:
          type: string
        raw_address:
          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
  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.