Enrich Person Enrichment API

openapi: 3.1.0
info:
  title: Enrich Person Enrichment API
  description: 'Reverse email lookup returning a person''s professional profile, single or in bulk.


    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: Reverse Email Lookup
paths:
  /reverse-lookup/bulk-lookup:
    post:
      summary: Look up professional profiles in batch
      deprecated: false
      description: "Submit up to **100 000 emails** and get back professional profile data for each\n\
        one. Duplicate emails are removed (case-insensitive) before processing.\n\n**Cost:** 10 credits\
        \ per unique email, reserved upfront. Credits for emails\nwhere no profile was found are refunded.\n\
        \n### Webhook callbacks\n\nIf you include a `webhookUrl`, your server will receive:\n\n1. **A\
        \ per-result callback** for every email as it is processed. See\n   [reverseLookupResult](#tag/Webhooks/operation/webhookReverseLookupResult)\
        \ for the payload.\n\n2. **A completion callback** when the entire batch finishes. See\n   [reverseLookupCompletion](#tag/Webhooks/operation/webhookReverseLookupCompletion)\
        \ for the payload.\n"
      operationId: bulkReverseLookup
      tags:
      - Reverse Email Lookup
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkLookupRequest'
            example:
              emails:
              - emily.zhang@figma.com
              - david.kim@vercel.com
              - aisha.johnson@cloudflare.com
              webhookUrl: https://api.yourapp.com/webhooks/enrich
      responses:
        '200':
          description: Bulk lookup submitted — credits have been reserved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLookupResponse'
              example:
                success: true
                data:
                  batchId: 665d2f8b9c5b2a0015d0bc10
                  status: queued
                  itemCount: 3
                  message: Bulk lookup job created
                  originalCount: 3
                  duplicatesRemoved: 0
                meta:
                  requestId: 665d2f8b9c5b2a0015d0bc0f
                  creditsReserved: 30
                  creditsPerItem: 10
                  estimatedCredits: 30
          headers: {}
        '400':
          description: Something is wrong with the request — check the `detail` field for specifics
          content:
            application/json:
              schema: &id001
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/validation-error
                title: Validation Error
                status: 400
                detail: body/email Invalid email
                instance: /requests/3fa85f64-5717-4562-b3fc-2c963f66afa6
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: *id001
              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: *id001
              example:
                type: https://dev.enrich.so/errors/insufficient-credits
                title: Insufficient Credits
                status: 402
                detail: 'Not enough credits. Required: 10, available: 3'
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id001
              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: *id001
              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-27483204-run
  /reverse-lookup/bulk-lookup/{batchId}:
    get:
      summary: Check bulk lookup progress
      deprecated: false
      description: 'Poll this endpoint to track the batch.


        **Cost:** Free.

        '
      operationId: getBulkLookupStatus
      tags:
      - Reverse Email Lookup
      parameters:
      - name: batchId
        in: path
        description: The batch identifier returned when you submitted the job
        required: true
        example: 665a1f4e2c3b7800129dce01
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Current batch status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              example:
                success: true
                data:
                  batchId: 665d2f8b9c5b2a0015d0bc10
                  status: processing
                  totalItems: 3
                  processedItems: 2
                  progress: 66.7
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id002
                $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: *id002
              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: *id002
              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:
              schema:
                type: string
            X-RateLimit-Limit:
              schema:
                type: string
            X-RateLimit-Remaining:
              schema:
                type: string
            X-RateLimit-Reset:
              schema:
                type: string
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27483205-run
  /reverse-lookup/bulk-lookup/{batchId}/results:
    get:
      summary: Get bulk lookup results
      deprecated: false
      description: 'Retrieve paginated professional profile results. Each result contains the full

        profile data, or the result is omitted if no profile was found for that email.


        **Credit settlement:** Emails with no matching profile are not charged.

        The difference between reserved and actual credits is refunded.

        '
      operationId: getBulkLookupResults
      tags:
      - Reverse Email Lookup
      parameters:
      - name: batchId
        in: path
        description: The batch identifier returned when you submitted the job
        required: true
        example: 665a1f4e2c3b7800129dce01
        schema:
          type: string
          minLength: 1
      - name: page
        in: query
        description: 'Page number (default: 1)'
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: 'Results per page (default: 100, max: 1 000)'
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      responses:
        '200':
          description: Paginated lookup results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLookupResultsResponse'
              example:
                success: true
                data:
                  batchId: 665d2f8b9c5b2a0015d0bc10
                  status: completed
                  totalItems: 3
                  processedItems: 3
                  successful: 2
                  failed: 1
                  page: 1
                  limit: 100
                  results:
                  - id: ACoAABk7TGwBfn9oQe3F
                    displayName: Emily Zhang
                    firstName: Emily
                    lastName: Zhang
                    headline: Staff Product Designer at Figma
                    companyName: Figma
                    location: San Francisco, California
                    profileUrl: https://www.example.com/in/emilyzhang
                    isPublic: true
                    skills:
                    - Product Design
                    - Design Systems
                    - Figma
                  - id: ACoAAC2dPR4BvKx9nJQm
                    displayName: David Kim
                    firstName: David
                    lastName: Kim
                    headline: Engineering Manager at Vercel
                    companyName: Vercel
                    location: New York, New York
                    profileUrl: https://www.example.com/in/davidkim
                    isPublic: true
                    skills:
                    - Next.js
                    - React
                    - Engineering Management
                meta:
                  requestId: 665d38ca9c5b2a0015d0bc20
                  creditsUsed: 20
                  creditsRefunded: 10
                  creditsRemaining: 24970
                  totalItems: 3
                  processedItems: 3
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id003
                $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: *id003
              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: *id003
              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:
              schema:
                type: string
            X-RateLimit-Limit:
              schema:
                type: string
            X-RateLimit-Remaining:
              schema:
                type: string
            X-RateLimit-Reset:
              schema:
                type: string
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27483206-run
  /reverse-lookup/lookup:
    post:
      summary: Look up a professional profile by email
      deprecated: false
      description: 'Pass an email address and get back the person''s professional profile — including

        their name, headline, current company, job history, education, and skills.


        **Cost:** 10 credits. You are **not** charged if no profile is found.

        '
      operationId: reverseLookup
      tags:
      - Reverse Email Lookup
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupRequest'
            example:
              email: emily.zhang@figma.com
      responses:
        '200':
          description: Professional profile data returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReverseLookupResponse'
              example:
                success: true
                data:
                  id: ACoAABk7TGwBfn9oQe3F
                  displayName: Emily Zhang
                  firstName: Emily
                  lastName: Zhang
                  headline: Staff Product Designer at Figma
                  summary: Product designer focused on design systems and developer tools. Previously
                    at Airbnb and Google.
                  companyName: Figma
                  location: San Francisco, California
                  photoUrl: https://media.licdn.com/dms/image/v2/D5603AQH/profile-displayphoto-shrink_200/photo.jpg
                  profileUrl: https://www.example.com/in/emilyzhang
                  connectionCount: 500
                  isConnectionCountObfuscated: true
                  isPublic: true
                  skills:
                  - Product Design
                  - Design Systems
                  - Figma
                  - User Research
                  - Prototyping
                  locale:
                    country: US
                    language: en
                  schools:
                    educationsCount: 1
                    educationHistory:
                    - degreeName: B.A. Interaction Design
                      schoolName: Carnegie Mellon University
                      schoolLocation: Pittsburgh, PA
                      startEndDate:
                        start:
                          year: 2012
                        end:
                          year: 2016
                  positions:
                    positionsCount: 3
                    positionHistory:
                    - title: Staff Product Designer
                      companyName: Figma
                      companyLocation: San Francisco, CA
                      description: Leading the design systems team.
                      startEndDate:
                        start:
                          month: 1
                          year: 2022
                        end: null
                    - title: Senior Product Designer
                      companyName: Airbnb
                      companyLocation: San Francisco, CA
                      startEndDate:
                        start:
                          month: 5
                          year: 2019
                        end:
                          month: 12
                          year: 2021
                    - title: Product Designer
                      companyName: Google
                      companyLocation: Mountain View, CA
                      startEndDate:
                        start:
                          month: 7
                          year: 2016
                        end:
                          month: 4
                          year: 2019
                  creditsConsumed: 10
                meta:
                  requestId: 665d1e4a9c5b2a0015d0bc01
                  creditsUsed: 10
                  creditsRemaining: 24990
                  processingTimeMs: 2140
          headers: {}
        '400':
          description: Something is wrong with the request — check the `detail` field for specifics
          content:
            application/json:
              schema: &id004
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/validation-error
                title: Validation Error
                status: 400
                detail: body/email Invalid email
                instance: /requests/3fa85f64-5717-4562-b3fc-2c963f66afa6
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: *id004
              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: *id004
              example:
                type: https://dev.enrich.so/errors/insufficient-credits
                title: Insufficient Credits
                status: 402
                detail: 'Not enough credits. Required: 10, available: 3'
          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:
              schema:
                type: string
            X-RateLimit-Limit:
              schema:
                type: string
            X-RateLimit-Remaining:
              schema:
                type: string
            X-RateLimit-Reset:
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id004
              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-27483203-run
components:
  schemas:
    BatchResultsMeta:
      type: object
      description: Metadata returned when you fetch batch results (includes credit settlement)
      properties:
        requestId:
          type: string
          description: Unique ID for this request
          examples:
          - 665a23bc2c3b7800129dce10
        creditsUsed:
          type: number
          minimum: 0
          description: Actual credits charged after settlement
          examples:
          - 80
        creditsRefunded:
          type: number
          minimum: 0
          description: Credits refunded (difference between reserved and actual cost)
          examples:
          - 20
        creditsRemaining:
          type: number
          minimum: 0
          description: Your remaining credit balance after settlement
          examples:
          - 24920
        totalItems:
          type: integer
          minimum: 0
          description: Total items in the batch
          examples:
          - 10
        processedItems:
          type: integer
          minimum: 0
          description: Items that were processed
          examples:
          - 10
    BatchStatusData:
      type: object
      description: Progress information for a batch job
      required:
      - batchId
      - status
      properties:
        batchId:
          type: string
          description: The batch identifier
          examples:
          - 665a1f4e2c3b7800129dce01
        status:
          type: string
          description: 'Current status: `queued`, `processing`, `completed`, or `failed`'
          examples:
          - processing
        totalItems:
          type: integer
          minimum: 0
          description: Total items in the batch
          examples:
          - 100
        processedItems:
          type: integer
          minimum: 0
          description: Items processed so far
          examples:
          - 50
        progress:
          type: number
          minimum: 0
          maximum: 100
          description: Completion percentage (0–100)
          examples:
          - 50
    BatchStatusResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/BatchStatusData'
        meta:
          type: object
          properties:
            requestId:
              type: string
              description: Request tracking ID
    BatchSubmitMeta:
      type: object
      description: Metadata returned when you submit a batch job
      properties:
        requestId:
          type: string
          description: Unique ID for this request
          examples:
          - 665a1f4e2c3b7800129dce00
        creditsReserved:
          type: number
          minimum: 0
          description: Total credits reserved for the batch
          examples:
          - 100
        creditsPerItem:
          type: number
          minimum: 0
          description: Cost per item
          examples:
          - 10
        estimatedCredits:
          type: number
          minimum: 0
          description: Estimated total cost (same as creditsReserved)
          examples:
          - 100
    BulkLookupRequest:
      type: object
      required:
      - emails
      properties:
        emails:
          type: array
          minItems: 1
          maxItems: 100000
          items:
            type: string
            format: email
            maxLength: 254
          description: Email addresses to look up (up to 100 000)
          examples:
          - - emily.zhang@figma.com
            - david.kim@vercel.com
        webhookUrl:
          type: string
          format: uri
          description: 'A URL on your server where we should send webhook callbacks.

            You''ll receive one POST per email, plus one final completion POST.

            '
          examples:
          - https://api.yourapp.com/webhooks/enrich
    BulkLookupResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/BulkLookupSubmitData'
        meta:
          $ref: '#/components/schemas/BatchSubmitMeta'
    BulkLookupResultsResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
          - batchId
          - status
          properties:
            batchId:
              type: string
              examples:
              - 665d2f8b9c5b2a0015d0bc10
            status:
              type: string
              examples:
              - completed
            totalItems:
              type: integer
              minimum: 0
            processedItems:
              type: integer
              minimum: 0
            successful:
              type: integer
              minimum: 0
              description: How many emails had a matching profile
            failed:
              type: integer
              minimum: 0
              description: How many emails had no matching profile
            page:
              type: integer
              minimum: 1
            limit:
              type: integer
              minimum: 1
            results:
              type: array
              items:
                $ref: '#/components/schemas/ReverseLookupResult'
        meta:
          $ref: '#/components/schemas/BatchResultsMeta'
    BulkLookupSubmitData:
      type: object
      description: Returned when you submit a bulk reverse lookup
      required:
      - batchId
      - status
      - itemCount
      properties:
        batchId:
          type: string
          description: The batch identifier — use it to poll status and fetch results
          examples:
          - 665d2f8b9c5b2a0015d0bc10
        status:
          type: string
          examples:
          - queued
        itemCount:
          type: integer
          minimum: 0
          description: Unique emails in the batch (after deduplication)
          examples:
          - 50
        message:
          type: string
          examples:
          - Bulk lookup job created
        originalCount:
          type: integer
          minimum: 0
          description: How many emails you submitted before deduplication
          examples:
          - 55
        duplicatesRemoved:
          type: integer
          minimum: 0
          description: How many duplicate emails were removed
          examples:
          - 5
    EducationHistoryItem:
      type: object
      description: One entry in a person's education history
      properties:
        degreeName:
          type: string
          description: Degree or program name
          examples:
          - B.S. Computer Science
        startEndDate: &id005
          $ref: '#/components/schemas/StartEndDate'
        schoolName:
          type: string
          description: Name of the school
          examples:
          - Stanford University
        schoolLocation:
          type: string
          description: Where the school is located
          examples:
          - Stanford, CA
        schoolLogo:
          type: string
          format: uri
          description: URL of the school's logo
    EnrichmentMeta:
      type: object
      description: Metadata included with every enrichment response
      properties:
        requestId:
          type: string
          description: Unique ID for this request — useful for support tickets
          examples:
          - 664f2b3c9a1e4d0012abcdef
        creditsUsed:
          type: number
          minimum: 0
          description: How many credits this request consumed
          examples:
          - 10
        creditsRemaining:
          type: number
          minimum: 0
          description: Your remaining credit balance after this request
          examples:
          - 24990
        processingTimeMs:
          type: number
          description: How long the lookup took, in milliseconds
          examples:
          - 420
    ErrorEnvelope:
      type: object
      description: RFC 9457 Problem Details error response.
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
          description: URI reference that identifies the problem type.
          examples:
          - https://dev.enrich.so/errors/validation-error
        title:
          type: string
          description: Short, human-readable summary of the problem.
          examples:
          - Validation Error
        status:
          type: integer
          description: HTTP status code.
          examples:
          - 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          examples:
          - body/email Invalid email
        instance:
          type: string
          description: URI reference that identifies the specific occurrence.
          examples:
          - /requests/3fa85f64-5717-4562-b3fc-2c963f66afa6
    LookupRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
          maxLength: 254
          description: The email address to look up
          examples:
          - emily.zhang@figma.com
    PositionHistoryItem:
      type: object
      description: One entry in a person's work history
      properties:
        title:
          type: string
          description: Job title
          examples:
          - Senior Software Engineer
        startEndDate: *id005
        description:
          type: string
          description: What the person did in this role
          examples:
          - Led the migration to a microservices architecture.
        companyName:
          type: string
          description: Company name
          examples:
          - Stripe
        companyLocation:
          type: string
          description: Where the company is located
          examples:
          - San Francisco, CA
        companyLogo:
          type: string
          format: uri
          description: URL of the company's logo
    ReverseLookupResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/ReverseLookupResult'
        meta:
          $ref: '#/components/schemas/EnrichmentMeta'
    ReverseLookupResult:
      type: object
      description: Professional profile data for a person
      properties:
        id:
          type: string
          description: Profile identifier
          examples:
          - ACoAABk7TGwBfn9oQe3F
        displayName:
          type: string
          description: Full name
          examples:
          - Emily Zhang
        firstName:
          type: string
          examples:
          - Emily
        lastName:
          type: string
          examples:
          - Zhang
        headline:
          type: string
          description: Professional headline
          examples:
          - Staff Product Designer at Figma
        summary:
          type: string
          description: About section from their profile
          examples:
          - Product designer focused on design systems and developer tools.
        companyName:
          type: string
          description: Current company
          examples:
          - Figma
        location:
          type: string
          description: Where they are based
          examples:
          - San Francisco, California
        photoUrl:
          type: string
          format: uri
          description: Profile photo URL
        profileUrl:
          type: string
          format: uri
          description: Profile URL
          examples:
          - https://www.example.com/in/emilyzhang
        reportProfileUrl:
          type: string
          format: uri
          description: URL to report this profile
        connectionCount:
          type: integer
          minimum: 0
          description: Number of connections
          examples:
    

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