Enrich Company Intelligence API

openapi: 3.1.0
info:
  title: Enrich Company Intelligence API
  description: 'IP-to-company resolution (single and batch) and LinkedIn company-follower scraping with
    audience count estimation.


    Assembled verbatim from the per-endpoint OpenAPI fragments Enrich publishes on each page of https://doc.enrich.so
    — every documentation page embeds its own OpenAPI fragment, and this document is the union of the
    fragments carrying these tags, with only the components they reference.'
  version: '3.0'
  contact:
    name: Enrich
    url: https://www.enrich.so
  termsOfService: https://www.enrich.so/terms-of-service
servers:
- url: https://dev.enrich.so/api/v3
  description: Enrich API v3 production base URL, published at https://doc.enrich.so/api-reference-1951025m0
security:
- ApiKeyHeader: []
- BearerToken: []
tags:
- name: Company Followers
- name: Company Followers/Count Estimation
- name: IP to Company
paths:
  /company-follower:
    post:
      summary: Continue company follower scrape
      deprecated: false
      description: '> **Access required** — approved accounts only. [Contact us](https://enrich.so) to
        request access.


        Continue an under-delivered **partial** company-follower scrape to fill the gap. Re-runs **only**
        the filter combinations that under-delivered on the original run and appends the new profiles
        to the **same batch** (already-collected profiles are kept and de-duplicated within the batch).


        **How to call:** POST to this same `/company-follower` endpoint with the original batch id as
        the `batchId` query parameter and an **empty body**. The presence of `batchId` switches the endpoint
        from “start a new scrape” to “continue”.


        **Eligibility:** only a batch whose status is `partial` and that is **less than 3 days old** can
        be continued (after 3 days the per-filter diagnostics used to target the gap have expired → `410
        Gone`). A fully `completed` batch, or one already being continued, returns `409 Conflict`. If
        nothing is recoverable (every filter already delivered, or the remaining gap is unreachable) you
        get `422`.


        **Cost:** credits are reserved only for the recoverable **additional** profiles — not the whole
        batch again — under a separate reservation. On settle you are charged for the profiles the continue
        actually added and refunded the rest.


        **Polling & results:** keep using the **same** `batchId` with the progress and results endpoints;
        the continue tops up that same batch.

        '
      operationId: continueCompanyFollowerScrape
      tags:
      - Company Followers
      parameters:
      - name: batchId
        in: query
        description: The batch id of the PARTIAL scrape you want to continue. Its presence switches this
          endpoint from 'start a new scrape' to 'continue (fill the gap)'.
        required: true
        example: 665a1f4e2c3b7800129dce01
        schema:
          type: string
          minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: No body required — send an empty object. All filters are inherited from the
                original batch.
              properties: {}
            example: {}
      responses:
        '200':
          description: Continue accepted — the gap scrape has been queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartCompanyFollowerResponse'
              example:
                success: true
                data:
                  batchId: 665a1f4e2c3b7800129dce01
                  message: Continuing scrape for the remaining 7076 profile(s).
                  estimatedAdditional: 7076
                meta:
                  requestId: 664f2b3c9a1e4d0012abcdef
                  creditsReserved: 707600
                  creditsPerItem: 100
          headers: {}
        '400':
          description: Missing batchId or team context.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Short error class, e.g. "Conflict", "Gone".
                  message:
                    type: string
                    description: Human-readable explanation.
                required:
                - error
                - message
          headers: {}
        '401':
          description: Your API key is missing or invalid.
          content:
            application/json:
              schema: &id001
                $ref: '#/components/schemas/ErrorEnvelope'
          headers: {}
        '402':
          description: Not enough credits to reserve the recoverable gap.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Short error class, e.g. "Conflict", "Gone".
                  message:
                    type: string
                    description: Human-readable explanation.
                required:
                - error
                - message
              example:
                error: Payment Required
                message: Insufficient credits
                detail:
                  required: 707600
                  itemCount: 7076
          headers: {}
        '404':
          description: No batch with that id belongs to your team.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Short error class, e.g. "Conflict", "Gone".
                  message:
                    type: string
                    description: Human-readable explanation.
                required:
                - error
                - message
              example:
                error: Not Found
                message: Job not found
          headers: {}
        '409':
          description: The batch is not partial (nothing to continue), a continue is already in progress,
            or the scrape is still running.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Short error class, e.g. "Conflict", "Gone".
                  message:
                    type: string
                    description: Human-readable explanation.
                required:
                - error
                - message
              example:
                error: Conflict
                message: This scrape completed fully — there is nothing to continue.
          headers: {}
        '410':
          description: The batch is older than 3 days — the diagnostics needed to target the gap have
            expired. Start a fresh scrape instead.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Short error class, e.g. "Conflict", "Gone".
                  message:
                    type: string
                    description: Human-readable explanation.
                required:
                - error
                - message
              example:
                error: Gone
                message: Continue is only available within 3 days of the scrape. Start a fresh scrape
                  instead.
          headers: {}
        '422':
          description: 'Nothing is recoverable: every filter already delivered, or the remaining gap is
            unreachable.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Short error class, e.g. "Conflict", "Gone".
                  message:
                    type: string
                    description: Human-readable explanation.
                required:
                - error
                - message
              example:
                error: Unprocessable Entity
                message: Every filter fully delivered — the remaining gap is unclassified followers that
                  no filter can reach (not recoverable by re-running).
          headers: {}
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema: *id001
          headers: {}
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-40599317-run
  /company-follower/limit:
    get:
      summary: Check daily scraping limit
      deprecated: false
      description: 'Check your team''s daily company follower scraping limit and current usage. No credits
        consumed.


        **Possible statuses:**

        - `approved` — Team has access; `creditsPerProfile`, `dailyLimit`, `dailyUsed`, and `dailyRemaining`
        are included.

        - `pending` — Application is under review.

        - `rejected` — Application was rejected.

        - `revoked` — Access was revoked.

        - `none` — No application on file.

        '
      operationId: checkCompanyFollowerLimit
      tags:
      - Company Followers
      parameters: []
      responses:
        '200':
          description: Returns the team's current access status and daily limit info. For approved teams,
            includes dailyLimit, dailyUsed, and dailyRemaining. For non-approved statuses (none, pending,
            rejected, revoked), only the status field is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        description: 'Access status: approved, pending, rejected, revoked, or none'
                        examples:
                        - approved
                      dailyLimit:
                        type: integer
                        description: Maximum profiles allowed per day
                        examples:
                        - 5000
                      dailyUsed:
                        type: integer
                        description: Profiles used today
                        examples:
                        - 1200
                      dailyRemaining:
                        type: integer
                        description: Profiles remaining today
                        examples:
                        - 3800
                      creditsPerProfile:
                        type: integer
                        description: Credit cost per follower profile for your team
                        examples:
                        - 100
                    required:
                    - status
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                required:
                - success
                - data
              examples:
                '1':
                  summary: Approved team
                  value:
                    success: true
                    data:
                      status: approved
                      creditsPerProfile: 100
                      dailyLimit: 5000
                      dailyUsed: 1200
                      dailyRemaining: 3800
                    meta:
                      requestId: 664f2b3c9a1e4d0012abcdef
                '2':
                  summary: No access
                  value:
                    success: true
                    data:
                      status: none
                    meta:
                      requestId: 664f2b3c9a1e4d0012abcdef
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id002
                $ref: '#/components/schemas/ErrorEnvelope'
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id002
          headers:
            Retry-After:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id002
          headers: {}
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27814759-run
  /company-follower/{batchId}/export:
    get:
      summary: Export results as CSV
      deprecated: false
      description: '> **Access required** — This endpoint is available to approved accounts only. [Contact
        us](https://enrich.so) to request access.


        Download scrape results as a CSV file. Batch must be complete. No credits consumed.

        '
      operationId: exportCompanyFollowerCsv
      tags:
      - Company Followers
      parameters:
      - name: batchId
        in: path
        description: The batch identifier returned when you started the scrape
        required: true
        example: 665a1f4e2c3b7800129dce01
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: CSV file download containing all follower profiles
          content:
            text/csv:
              schema:
                type: string
          headers:
            Content-Type:
              example: text/csv
              required: false
              description: ''
              schema:
                type: string
            Content-Disposition:
              example: attachment; filename="followers-665a1f4e2c3b7800129dce01.csv"
              required: false
              description: ''
              schema:
                type: string
        '400':
          description: Batch is not yet complete. Wait for the scrape to finish before exporting.
          content:
            application/json:
              schema: &id003
                $ref: '#/components/schemas/ErrorEnvelope'
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: *id003
          headers: {}
        '404':
          description: The resource you requested doesn't exist or doesn't belong to your organization
          content:
            application/json:
              schema: *id003
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id003
          headers:
            Retry-After:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27730401-run
  /company-follower/{batchId}/progress:
    get:
      summary: Check scrape progress
      deprecated: false
      description: '> **Access required** — This endpoint is available to approved accounts only. [Contact
        us](https://enrich.so) to request access.


        Poll this endpoint to track the progress of your company follower scrape.


        **Cost:** Free — polling never costs credits.

        '
      operationId: getCompanyFollowerProgress
      tags:
      - Company Followers
      parameters:
      - name: batchId
        in: path
        description: The batch identifier returned when you started the scrape
        required: true
        example: 665a1f4e2c3b7800129dce01
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Current scrape progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyFollowerProgressResponse'
              example:
                success: true
                data:
                  batchId: 665a1f4e2c3b7800129dce01
                  processed: 125
                  total: 500
                  errors: 0
                  done: false
                  message: Fetching profiles... 25% complete (125/500)
                meta:
                  requestId: 664f2b3c9a1e4d0012abcdef
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id004
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
        '404':
          description: The resource you requested doesn't exist or doesn't belong to your organization
          content:
            application/json:
              schema: *id004
              example:
                type: https://dev.enrich.so/errors/not-found
                title: Not Found
                status: 404
                detail: No batch found with that ID
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id004
              example:
                type: https://dev.enrich.so/errors/rate-limit-exceeded
                title: Too Many Requests
                status: 429
                detail: Rate limit exceeded. Please retry after 30 seconds.
          headers:
            Retry-After:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27728072-run
  /company-follower/{batchId}/results:
    get:
      summary: Get scrape results
      deprecated: false
      description: '> **Access required** This endpoint is available to approved accounts only. [Contact
        us](https://enrich.so) to request access.


        Returns paginated follower profiles for a completed batch. Use `page` and `limit` query params
        to paginate through results.


        Credits are charged upfront when you start the scrape. If fewer profiles are found than `max_limit`,
        unused credits are refunded automatically.


        If you provided a `webhookUrl`, results are already delivered via webhooks and credits are auto-settled.
        No need to call this endpoint.


        Only call this after the progress endpoint reports `done: true`.

        '
      operationId: getCompanyFollowerResults
      tags:
      - Company Followers
      parameters:
      - name: batchId
        in: path
        description: The batch identifier returned when you started the scrape
        required: true
        example: 665a1f4e2c3b7800129dce01
        schema:
          type: string
          minLength: 1
      - name: page
        in: query
        description: 'Page number (default: 1)'
        required: false
        example: 1
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: 'Results per page, max 500 (default: 100)'
        required: false
        example: 100
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
      responses:
        '200':
          description: Follower profiles retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyFollowerResultsResponse'
              example:
                success: true
                data:
                  batchId: 665a1f4e2c3b7800129dce01
                  count: 100
                  data:
                  - objectURN: urn:li:member:123456
                    name: Sarah Chen
                    firstName: Sarah
                    lastName: Chen
                    profileUrl: https://linkedin.com/in/sarahchen
                    title: Senior Software Engineer
                    companyName: Stripe
                    location: San Francisco, CA
                    connectionDegree: 2
                    isPremium: false
                    isOpenProfile: true
                  pagination:
                    page: 1
                    limit: 100
                    total: 342
                    totalPages: 4
                meta:
                  requestId: 664f2b3c9a1e4d0012abcdef
                  creditsUsed: 34200
                  creditsRefunded: 15800
                  creditsRemaining: 0
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id005
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
        '404':
          description: The resource you requested doesn't exist or doesn't belong to your organization
          content:
            application/json:
              schema: *id005
              example:
                type: https://dev.enrich.so/errors/not-found
                title: Not Found
                status: 404
                detail: No batch found with that ID
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id005
              example:
                type: https://dev.enrich.so/errors/rate-limit-exceeded
                title: Too Many Requests
                status: 429
                detail: Rate limit exceeded. Please retry after 30 seconds.
          headers:
            Retry-After:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27728073-run
  /count-estimate:
    post:
      summary: Start count estimation
      deprecated: false
      description: '> **Access required** — This endpoint is available to approved accounts only. [Contact
        us](https://enrich.so) to request access.


        Starts an asynchronous count estimation job. Returns the estimated number of followers matching
        your filters, with optional breakdowns by department and seniority.


        **Cost:** 100 credits (fixed). Cached results for the same company + filters within 24 hours are
        free.


        **Results:** Poll the status endpoint to get results. Typically completes within 30–60 seconds.

        '
      operationId: startCountEstimate
      tags:
      - Company Followers
      - Company Followers/Count Estimation
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CountEstimateRequest'
            example:
              companyUrl: https://linkedin.com/company/stripe
              departments:
              - Engineering
              - Sales
      responses:
        '200':
          description: Count estimation job started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartCountEstimateResponse'
              example:
                success: true
                data:
                  batchId: 665b2a3f4c5d6e0013fgh002
                  status: pending
                  message: Count estimation job started. Results typically available within 30-60 seconds.
                meta:
                  requestId: 664f2b3c9a1e4d0012abcdef
                  creditsUsed: 100
                  creditsRemaining: 24900
          headers: {}
        '400':
          description: Something is wrong with the request — check the `detail` field for specifics
          content:
            application/json:
              schema: &id006
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/validation-error
                title: Validation Error
                status: 400
                detail: body/companyUrl Invalid url
                instance: /requests/3fa85f64-5717-4562-b3fc-2c963f66afa6
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: *id006
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
        '402':
          description: You don't have enough credits for this request
          content:
            application/json:
              schema: *id006
              example:
                type: https://dev.enrich.so/errors/insufficient-credits
                title: Insufficient Credits
                status: 402
                detail: 'Not enough credits. Required: 100, available: 3'
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id006
              example:
                type: https://dev.enrich.so/errors/rate-limit-exceeded
                title: Too Many Requests
                status: 429
                detail: Rate limit exceeded. Please retry after 30 seconds.
          headers:
            Retry-After:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id006
              example:
                type: https://dev.enrich.so/errors/internal-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred. Please try again later.
          headers: {}
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27728074-run
  /count-estimate/{batchId}:
    get:
      summary: Get estimation status/results
      deprecated: false
      description: '> **Access required** — This endpoint is available to approved accounts only. [Contact
        us](https://enrich.so) to request access.


        Check the status of a count estimation job and retrieve results when complete.


        **Cost:** Free — polling never costs credits.


        **Refunds:** If the job fails within 7 days, the 100 credits are refunded automatically on the
        next status check.

        '
      operationId: getCountEstimateStatus
      tags:
      - Company Followers
      - Company Followers/Count Estimation
      parameters:
      - name: batchId
        in: path
        description: The batch identifier returned when you started the estimation
        required: true
        example: 665b2a3f4c5d6e0013fgh002
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Estimation status and results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountEstimateStatusResponse'
              example:
                success: true
                data:
                  batchId: 665b2a3f4c5d6e0013fgh002
                  status: completed
                  companyUrl: https://linkedin.com/company/stripe
                  message: Count estimation complete. Found 8542 followers matching your criteria.
                  createdAt: '2025-06-03T14:30:00.000Z'
                  completedAt: '2025-06-03T14:31:15.000Z'
                  data:
                    totalCount: 8542
                    functionBreakdown:
                    - functionName: Engineering
                      functionId: '8'
                      count: 3200
                      percentage: 37.5
                    - functionName: Sales
                      functionId: '25'
                      count: 1850
                      percentage: 21.7
                    filtersApplied:
                      departments:
                      - Engineering
                      - Sales
                meta:
                  requestId: 664f2b3c9a1e4d0012abcdef
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id007
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
        '404':
          description: The resource you requested doesn't exist or doesn't belong to your organization
          content:
            application/json:
              schema: *id007
              example:
                type: https://dev.enrich.so/errors/not-found
                title: Not F

# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/enrich-so/refs/heads/main/openapi/enrich-so-company-intelligence-api-openapi.yml