FullEnrich Reverse Email Lookup API

openapi: 3.1.0
info:
  title: FullEnrich Reverse Email Lookup API
  description: Resolve the person and company behind an email address in bulk. FullEnrich API enables
    you to enrich B2B contacts with emails and phone numbers using data from 20+ providers.  We are GDPR
    and CCPA compliant.
  version: 2.0.0
  contact:
    name: FullEnrich Support
    url: https://docs.fullenrich.com
  termsOfService: https://fullenrich.com/tos
servers:
- url: https://app.fullenrich.com/api/v2
security:
- BearerAuth: []
tags:
- name: Reverse Email Lookup
  description: Resolve the person and company behind an email address in bulk.
paths:
  /contact/reverse/email/bulk:
    post:
      summary: Reverse Contact Lookup In Bulk
      description: ''
      operationId: postContactBulkReverseEmail
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestPostContactBulkReverseEmail'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsePostContactBulkReverseEmail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ReverseEmailInvalid:
                  value:
                    code: error.reverse.email.invalid
                    message: Email is invalid
                ReverseEmailNotSet:
                  value:
                    code: error.reverse.email.empty
                    message: Email cannot be empty
                WebhookURLInvalid:
                  value:
                    code: error.enrichment.webhook_url
                    message: Webhook URL must be start with http or https
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknownApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
      security:
      - BearerAuth: []
      tags:
      - Reverse Email Lookup
  /contact/reverse/email/bulk/{enrichment_id}:
    get:
      summary: Get Bulk Reverse Email Results
      description: Use this endpoint to retrieve the result from a reverse email lookup.
      operationId: GetContactBulkReverseEmailByID
      parameters:
      - name: enrichment_id
        in: path
        required: true
        description: The unique identifier returned when the reverse lookup was started
        schema:
          type: string
        example: 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseGetContactBulkReverseEmail'
              example:
                id: 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
                name: Reverse Email Lookup
                status: FINISHED
                cost:
                  credits: 1
                data:
                - input:
                    email: johnsnow@gmail.com
                  custom:
                    user_id: '12584'
                  profile:
                    id: 746e4816-19c8-54d8-b558-65a5a52cc85c
                    full_name: John Snow
                    first_name: John
                    last_name: Snow
                    headline: Head of Sales Operations at Example Inc | Revenue Operations, CRM & Sales
                      Enablement
                    description: Sales operations leader focused on revenue processes, CRM architecture
                      and sales enablement. I help go-to-market teams scale pipeline with clean data and
                      reliable reporting.
                    location:
                      country: United States
                      country_code: US
                      city: San Francisco
                      region: California
                    social_profiles:
                      professional_network:
                        url: https://www.linkedin.com/in/demoge/
                        handle: demoge
                        connection_count: 500
                    educations:
                    - school_name: Stanford University
                      degree: Bachelor of Science in Computer Science
                      start_at: '2015-09-01T00:00:00Z'
                      end_at: '2019-06-01T00:00:00Z'
                    languages:
                    - language: English
                      proficiency: PROFESSIONAL_WORKING
                    - language: French
                      proficiency: NATIVE_OR_BILINGUAL
                    skills:
                    - Sales Operations
                    - Business Development
                    - CRM Management
                    employment:
                      current:
                        title: Head of Sales Operations
                        is_current: true
                        start_at: '2022-03-15T00:00:00Z'
                        company:
                          id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                          name: Example Inc
                          domain: example.com
                          website: https://www.example.com
                          description: Leading example company
                          year_founded: 2010
                          headcount: 250
                          company_type: Privately Held
                          locations:
                            headquarters:
                              line1: 123 Market St
                              line2: San Francisco, CA 94105, US
                              city: San Francisco
                              region: California
                              country: United States
                              country_code: US
                            offices:
                            - line1: 456 Broadway
                              line2: New York, NY 10013, US
                          industry:
                            main_industry: Software Development
                          social_profiles:
                            professional_network:
                              url: https://www.linkedin.com/company/example-inc
                              handle: example-inc
                              connection_count: 12000
                          logo_url: https://app.fullenrich.com/logo/company/handle/example-inc
                      all:
                      - title: Head of Sales Operations
                        is_current: true
                        start_at: '2022-03-15T00:00:00Z'
                        company:
                          id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                          name: Example Inc
                          domain: example.com
                          website: https://www.example.com
                          description: Leading example company
                          year_founded: 2010
                          headcount: 250
                          company_type: Privately Held
                          locations:
                            headquarters:
                              line1: 123 Market St
                              line2: San Francisco, CA 94105, US
                              city: San Francisco
                              region: California
                              country: United States
                              country_code: US
                            offices:
                            - line1: 456 Broadway
                              line2: New York, NY 10013, US
                          industry:
                            main_industry: Software Development
                          social_profiles:
                            professional_network:
                              url: https://www.linkedin.com/company/example-inc
                              handle: example-inc
                              connection_count: 12000
                          logo_url: https://app.fullenrich.com/logo/company/handle/example-inc
                      - title: Sales Manager
                        is_current: false
                        start_at: '2019-07-01T00:00:00Z'
                        end_at: '2022-03-01T00:00:00Z'
                        company:
                          id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                          name: Previous Corp
                          domain: previouscorp.com
                          website: https://www.previouscorp.com
                          description: Enterprise software solutions
                          year_founded: 2005
                          headcount: 500
                          company_type: Privately Held
                          locations:
                            headquarters:
                              line1: 789 5th Ave
                              line2: New York, NY 10022, US
                              city: New York
                              region: New York
                              country: United States
                              country_code: US
                            offices: []
                          industry:
                            main_industry: Software Development
                          social_profiles:
                            professional_network:
                              url: https://www.linkedin.com/company/previous-corp
                              handle: previous-corp
                              connection_count: 8000
                          logo_url: https://app.fullenrich.com/logo/company/handle/previous-corp
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknownApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseGetContactBulkReverseEmail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ReverseEmailNotFound:
                  value:
                    code: error.reverse.email.not_found
                    message: Reverse email ID not found
      security:
      - BearerAuth: []
      tags:
      - Reverse Email Lookup
components:
  schemas:
    CompanyAddress:
      type: object
      description: Structured headquarters address with parsed location fields
      properties:
        line1:
          type: string
          description: Address line 1 (street address)
          example: 548 Market St
        line2:
          type: string
          description: Address line 2 (full location string including city, region, postal code, and country
            code)
          example: San Francisco, CA 94105, US
        city:
          type: string
          description: City name
          example: San Francisco
        region:
          type: string
          description: State or region
          example: California
        country:
          type: string
          description: Country name
          example: United States
        country_code:
          type: string
          description: ISO country code
          example: US
    CompanySocialProfile:
      type: object
      properties:
        professional_network:
          type: object
          description: Professional network profile information
          properties:
            id:
              type: integer
              description: Professional network profile ID
              example: 1234
            url:
              type: string
              description: Full professional network profile URL
              example: https://www.linkedin.com/company/anthropic
            handle:
              type: string
              description: Professional network profile handle/username
              example: anthropic
            connection_count:
              type: integer
              description: Number of professional network followers
              example: 125000
    ContactReverseEmailInput:
      type: object
      properties:
        email:
          type: string
          examples:
          - john.snow@example.com
    Cost:
      type: object
      properties:
        credits:
          type: integer
          format: int64
          description: Number of credits consumed for this enrichment
          examples:
          - 1
          - 0
    Employment:
      type: object
      properties:
        title:
          type: string
          description: Job title or position
          example: Senior Software Engineer
        seniority:
          type: string
          description: Seniority level of the person in the company
          example: Senior
        job_functions:
          type: array
          description: Job functions of the person in the company
          items:
            type: object
            properties:
              function:
                type: string
                description: Job function
                example: Not Employed
              sub_function:
                type: string
                description: Sub function of the job function
                example: Freelancer
        description:
          type: string
          description: Description of the role and responsibilities. Not always present.
          example: Leading the backend team and designing microservices architecture.
        company:
          type: object
          description: Company information
          allOf:
          - $ref: '#/components/schemas/EmploymentCompany'
        is_current:
          type: boolean
          description: Whether this is the current employment
          example: true
        start_at:
          type: string
          format: date-time
          description: Employment start date in ISO 8601 format with T separator (YYYY-MM-DDTHH:MM:SSZ)
          example: '2022-03-15T00:00:00Z'
        end_at:
          type: string
          format: date-time
          description: Employment end date in ISO 8601 format with T separator (YYYY-MM-DDTHH:MM:SSZ).
            This field is not returned for current employment (when is_current is true).
          example: '2024-06-30T00:00:00Z'
    EmploymentCompany:
      type: object
      properties:
        id:
          type: string
          description: Unique company identifier
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: Company name
          example: Anthropic
        domain:
          type: string
          description: Company domain
          example: anthropic.com
        website:
          type: string
          description: Company website URL as declared by the company. May differ from `domain` (can include
            a subdomain, a path or tracking parameters). Omitted when not available.
          example: https://www.anthropic.com
        description:
          type: string
          description: Company description
          example: AI safety and research company
        year_founded:
          type: integer
          description: Year the company was founded. Returns 0 when unknown.
          example: 2021
        headcount:
          type: integer
          description: Exact number of employees. May return 0 even when headcount_range is available.
          example: 2610
        headcount_range:
          type: string
          description: Employee count range (e.g., '1-10', '11-50', '51-200', '201-500', '501-1000', '1001-5000',
            '5001-10000', '10001+')
          example: 1001-5000
        company_type:
          type: string
          description: Type of company (e.g., 'Public Company', 'Privately Held', 'Nonprofit', 'Self-Employed',
            'Partnership', 'Educational', 'Government Agency')
          example: Privately Held
        specialties:
          type: array
          description: Specialties associated with the company
          items:
            type: string
          example:
          - Data Enrichment
          - B2B Data
        locations:
          type: object
          description: Company location information
          properties:
            headquarters:
              type: object
              description: Main headquarters address with structured location fields. Can be an empty
                object when no headquarters data is available.
              allOf:
              - $ref: '#/components/schemas/CompanyAddress'
            offices:
              type: array
              description: Additional office locations. Only contains raw address lines (line1, line2)
                without structured city/region/country fields. Can be null or an empty array.
              nullable: true
              items:
                $ref: '#/components/schemas/OfficeAddress'
        industry:
          type: object
          description: Company industry information
          properties:
            main_industry:
              type: string
              description: Primary industry category (e.g., 'Software Development', 'Computer Hardware
                Manufacturing', 'Financial Services', 'Healthcare')
              example: Software Development
        social_profiles:
          type: object
          description: Company's social media profiles
          allOf:
          - $ref: '#/components/schemas/CompanySocialProfile'
        logo_url:
          type: string
          description: URL of the company logo hosted by FullEnrich, built from the company's professional
            network handle. Empty when the handle is unknown.
          example: https://app.fullenrich.com/logo/company/handle/anthropic
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
      - code
      - message
    OfficeAddress:
      type: object
      description: Office address. Unlike headquarters, office addresses only contain raw address lines
        without parsed location fields.
      properties:
        line1:
          type: string
          description: Street address
          example: 111 8th Ave
        line2:
          type: string
          description: Full location string (city, region, postal code, country code)
          example: New York, NY 10011, US
    Person:
      type: object
      properties:
        id:
          type: string
          description: Unique person identifier
          example: 746e4816-19c8-54d8-b558-65a5a52cc85c
        full_name:
          type: string
          description: Person's full name
          example: Enzo Romera
        first_name:
          type: string
          description: Person's first name
          example: Enzo
        last_name:
          type: string
          description: Person's last name
          example: Romera
        headline:
          type: string
          description: Short professional tagline written by the person on their professional network
            profile
          example: Marketing Strategist | 10+ Years in Strategy, Account Management & Activation | Consulting
            Expert
        description:
          type: string
          description: Free-text summary written by the person in the about section of their professional
            network profile. Omitted when not available.
          example: Marketing strategist with 10+ years helping B2B companies build demand generation engines.
            I work with go-to-market teams on positioning, account-based campaigns and channel activation.
        location:
          type: object
          description: Person's location information
          properties:
            country:
              type: string
              description: Country name
              example: United States
            country_code:
              type: string
              description: ISO country code
              example: US
            city:
              type: string
              description: City name
              example: San Francisco
            region:
              type: string
              description: Region or state
              example: California
        social_profiles:
          type: object
          description: Person's social media profiles
          allOf:
          - $ref: '#/components/schemas/PersonSocialProfile'
        educations:
          type: array
          description: Person's education history
          items:
            $ref: '#/components/schemas/PersonEducation'
        languages:
          type: array
          description: Languages spoken by the person
          items:
            $ref: '#/components/schemas/PersonLanguage'
        skills:
          type: array
          description: Person's professional skills
          items:
            type: string
          example:
          - JavaScript
          - Project Management
          - Python
        employment:
          type: object
          description: Person's employment history
          properties:
            current:
              type: object
              description: Current employment information. If the person is in their current position,
                the end_at field will not be returned.
              allOf:
              - $ref: '#/components/schemas/Employment'
            all:
              type: array
              description: All employment history (current and past)
              items:
                $ref: '#/components/schemas/Employment'
    PersonEducation:
      type: object
      properties:
        school_name:
          type: string
          description: Name of the educational institution
          example: Stanford University
        degree:
          type: string
          description: Degree or qualification obtained
          example: Bachelor of Science in Computer Science
        start_at:
          type: string
          format: date-time
          description: Start date in ISO 8601 format with T separator (YYYY-MM-DDTHH:MM:SSZ)
          example: '2015-09-01T00:00:00Z'
        end_at:
          type: string
          format: date-time
          description: End date in ISO 8601 format with T separator (YYYY-MM-DDTHH:MM:SSZ)
          example: '2019-06-01T00:00:00Z'
    PersonLanguage:
      type: object
      properties:
        language:
          type: string
          description: Language name
          example: French
        proficiency:
          type: string
          description: Proficiency level in the language (e.g., 'NATIVE_OR_BILINGUAL', 'FULL_PROFESSIONAL',
            'PROFESSIONAL_WORKING', 'LIMITED_WORKING', 'ELEMENTARY')
          example: NATIVE_OR_BILINGUAL
    PersonSocialProfile:
      type: object
      properties:
        professional_network:
          type: object
          description: Professional network profile information
          properties:
            id:
              type: integer
              description: Professional network profile ID
              example: 1234
            url:
              type: string
              description: Full professional network profile URL
              example: https://www.linkedin.com/in/john-doe
            handle:
              type: string
              description: Professional network profile handle/username
              example: john-doe
            connection_count:
              type: integer
              description: Number of professional network connections
              example: 500
    RecordReverseEmail:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/ContactReverseEmailInput'
        custom:
          type: object
          examples:
          - user_id: '12584'
        profile:
          $ref: '#/components/schemas/Person'
    RequestPostContactBulkReverseEmail:
      type: object
      properties:
        name:
          type: string
          description: A readable name for this reverse lookup (visible in your dashboard)
          example: Reverse Lookup Batch 1
        webhook_url:
          type: string
          description: URL that will receive a POST request when the entire reverse lookup is finished
            (all emails processed).
          example: https://example.com/webhook
        webhook_events:
          type: object
          description: Optional webhook URLs for specific events during reverse lookup
          properties:
            contact_finished:
              type: string
              description: URL that receives a POST request each time a single email is processed, without
                waiting for the entire batch to complete.
              example: https://example.com/webhook/contact
        data:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
                description: Email address to perform reverse lookup on
                example: john.snow@example.com
              custom:
                type: object
                description: Custom fields returned in the result (max 10 keys, 100 chars per value)
                example:
                  user_id: '12584'
            required:
            - email
          example:
          - email: john.snow@example.com
            custom:
              user_id: '12584'
      required:
      - name
      - data
    ResponseGetContactBulkReverseEmail:
      type: object
      properties:
        id:
          type: string
          format: uuid
          examples:
          - 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
        name:
          type: string
          examples:
          - Start Reverse Email Lookup Operation
        status:
          type: string
          examples:
          - FINISHED
          enum:
          - CREATED
          - IN_PROGRESS
          - CANCELED
          - CREDITS_INSUFFICIENT
          - FINISHED
          - RATE_LIMIT
          - UNKNOWN
        data:
          type: array
          items:
            $ref: '#/components/schemas/RecordReverseEmail'
        cost:
          $ref: '#/components/schemas/Cost'
    ResponsePostContactBulkReverseEmail:
      type: object
      properties:
        enrichment_id:
          type: string
          format: uuid
          examples:
          - 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string