FullEnrich Contact Enrichment API

openapi: 3.2.0
info:
  title: FullEnrich Contact Enrichment API
  description: Submit contacts for asynchronous waterfall enrichment across 25+ data sources and retrieve results. 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: Contact Enrichment
  description: Submit contacts for asynchronous waterfall enrichment across 25+ data sources and retrieve results.
paths:
  /contact/enrich/bulk:
    post:
      summary: Enrich Contacts In Bulk
      description: ''
      operationId: postContactBulkEnrich
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestPostContactBulkEnrich'
            example:
              name: Sales Operations in London
              webhook_url: https://example.com/webhook
              webhook_events:
                contact_finished: https://example.com/webhook/contact
              data:
              - first_name: John
                last_name: Snow
                domain: example.com
                company_name: Example Inc
                linkedin_url: https://www.linkedin.com/in/demoge/
                enrich_fields:
                - contact.work_emails
                - contact.personal_emails
                - contact.phones
                custom:
                  user_id: '12584'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsePostContactBulkEnrich'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                EnrichmentNameNotSet:
                  value:
                    code: error.enrichment.name.empty
                    message: Enrichment name not set
                WebhookURLInvalid:
                  value:
                    code: error.enrichment.webhook_url
                    message: Webhook URL must be start with http or https
                ProviderNotSet:
                  value:
                    code: error.enrichment.provider.empty
                    message: Providers not set
                DataNotSet:
                  value:
                    code: error.enrichment.data.empty
                    message: Data is empty
                FirstNameNotSet:
                  value:
                    code: error.enrichment.first_name.empty
                    message: First name cannot be empty
                LastNameNotSet:
                  value:
                    code: error.enrichment.last_name.empty
                    message: Last name cannot be empty
                DomainNotSet:
                  value:
                    code: error.enrichment.domain.empty
                    message: Domain cannot be empty
                EnrichFieldsNotSet:
                  value:
                    code: error.enrichment.enrich_fields.empty
                    message: enrichFields cannot be empty
                EnrichFieldValue:
                  value:
                    code: error.enrichment.enrich_field.value
                    message: enrichField 'xxxx' not valid must be contact.work_emails or contact.phones or contact.personal_emails
                CustomKeyExceeded:
                  value:
                    code: error.enrichment.custom.key.exceeded
                    message: 'Custom field contains too many keys (max: 10 keys)'
                CustomKeyValueExceeded:
                  value:
                    code: error.enrichment.custom.value.exceeded
                    message: 'Custom field value max len exceeded (max: 100 character)'
        '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
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                RateLimitExceeded:
                  value:
                    code: error.rate.limit
                    message: Too many requests. Try again in 1m
      security:
      - BearerAuth: []
      tags:
      - Contact Enrichment
  /contact/enrich/bulk/{enrichment_id}:
    get:
      summary: Get Bulk Enrich Results
      description: Use this endpoint to retrieve the result from an enrich.
      operationId: GetContactBulkEnrichByID
      parameters:
      - name: enrichment_id
        in: path
        required: true
        description: The unique identifier returned when the enrichment was started
        schema:
          type: string
        example: 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
      - name: forceResults
        in: query
        schema:
          type: boolean
        description: Default = False. This parameter forces the API to return what has been found so far, even if the enrichment is not finished. This may result in missing information and is not recommended for regular use.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseGetContactBulkEnrich'
              example:
                id: 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
                name: Sales Operations in London
                status: FINISHED
                cost:
                  credits: 14
                data:
                - input:
                    first_name: John
                    last_name: Snow
                    company_domain: example.com
                    company_name: Example Inc
                    professional_network_url: https://www.linkedin.com/in/demoge/
                  custom:
                    user_id: '12584'
                  contact_info:
                    most_probable_work_email:
                      email: john.snow@example.com
                      status: DELIVERABLE
                    most_probable_personal_email:
                      email: johnsnow@gmail.com
                      status: DELIVERABLE
                    most_probable_phone:
                      number: +1 555-123-4567
                      region: US
                    work_emails:
                    - email: john.snow@example.com
                      status: DELIVERABLE
                    personal_emails:
                    - email: johnsnow@gmail.com
                      status: DELIVERABLE
                    phones:
                    - number: +1 555-123-4567
                      region: US
                    - number: +33 6 12 34 56 78
                      region: FR
                  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:
                        id: 1234
                        url: https://www.linkedin.com/in/john-doe
                        handle: john-doe
                        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/example-inc
                              handle: example-inc
                              connection_count: 12000
                          logo_url: https://app.fullenrich.com/logo/company/handle/example-inc
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InProgress:
                  value:
                    code: error.enrichment.in_progress
                    message: Enrichment not ready, try again in 30 seconds
        '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/ResponseGetContactBulkEnrich'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                EnrichmentNotFound:
                  value:
                    code: error.enrichment.not_found
                    message: Enrichment ID not found
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                RateLimitExceeded:
                  value:
                    code: error.rate.limit
                    message: Too many requests. Try again in 1m
      security:
      - BearerAuth: []
      tags:
      - Contact Enrichment
components:
  schemas:
    ContactEnrichedInformation:
      type: object
      description: Contact information found during enrichment
      properties:
        most_probable_work_email:
          description: The most reliable work email found
          $ref: '#/components/schemas/Email'
        most_probable_personal_email:
          description: The most reliable personal email found
          $ref: '#/components/schemas/Email'
        most_probable_phone:
          description: The most reliable mobile phone number found
          $ref: '#/components/schemas/Phone'
        work_emails:
          type: array
          description: All work emails found
          items:
            $ref: '#/components/schemas/Email'
        personal_emails:
          type: array
          description: All personal emails found
          items:
            $ref: '#/components/schemas/Email'
        phones:
          type: array
          description: All mobile phone numbers found
          items:
            $ref: '#/components/schemas/Phone'
    Cost:
      type: object
      properties:
        credits:
          type: integer
          format: int64
          description: Number of credits consumed for this enrichment
          examples:
          - 1
          - 0
    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
    ContactEnrichmentInput:
      type: object
      description: The input data originally provided for this contact enrichment
      properties:
        first_name:
          type: string
          description: First name of the contact
          examples:
          - John
        last_name:
          type: string
          description: Last name of the contact
          examples:
          - Snow
        full_name:
          type: string
          description: Full name of the contact
          examples:
          - John Snow
        company_domain:
          type: string
          description: Domain of the contact's company
          examples:
          - example.com
        company_name:
          type: string
          description: Name of the contact's company
          examples:
          - Example Inc
        professional_network_url:
          type: string
          description: Professional network profile URL of the contact
          examples:
          - https://www.linkedin.com/in/demoge
    RequestPostContactBulkEnrich:
      type: object
      example:
        name: Sales Operations in London
        webhook_url: https://example.com/webhook
        webhook_events:
          contact_finished: https://example.com/webhook/contact
        data:
        - first_name: John
          last_name: Snow
          domain: example.com
          company_name: Example Inc
          professional_network_url: https://www.linkedin.com/in/demoge/
          enrich_fields:
          - contact.work_emails
          - contact.personal_emails
          - contact.phones
          custom:
            user_id: '12584'
      properties:
        name:
          type: string
          description: A readable name for this enrichment (visible in your dashboard)
        webhook_url:
          type: string
          description: URL that will receive a POST request when the entire enrichment is finished (all contacts processed).
        webhook_events:
          type: object
          description: Optional webhook URLs for specific events during enrichment
          properties:
            contact_finished:
              type: string
              description: URL that receives a POST request each time a single contact is enriched, without waiting for the entire batch to complete. Useful for real-time updates.
        data:
          type: array
          items:
            $ref: '#/components/schemas/RequestPostContactBulkEnrichContact'
      required:
      - name
      - data
    RequestPostContactBulkEnrichContact:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        domain:
          type: string
        company_name:
          type: string
        linkedin_url:
          type: string
          description: Supports standard LinkedIn profile URLs (e.g., https://www.linkedin.com/in/demoge) as well as LinkedIn Sales Navigator URLs (e.g., https://www.linkedin.com/in/ACwAACLLwaIBKi655883b).
        enrich_fields:
          type: array
          items:
            type: string
            enum:
            - contact.work_emails
            - contact.phones
            - contact.personal_emails
        custom:
          type: object
          description: Returned in the enrichment result. Use it to identify a user, a CRM contact, or to pass any other information. All values must be strings. Limited to 20 entries.
    ResponseGetContactBulkEnrich:
      type: object
      properties:
        id:
          type: string
          format: uuid
          examples:
          - 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
        name:
          type: string
          examples:
          - Sales Operations in London
        status:
          type: string
          examples:
          - FINISHED
          enum:
          - CREATED
          - IN_PROGRESS
          - CANCELED
          - CREDITS_INSUFFICIENT
          - FINISHED
          - RATE_LIMIT
          - UNKNOWN
        data:
          type: array
          items:
            $ref: '#/components/schemas/RecordEnrichment'
        cost:
          $ref: '#/components/schemas/Cost'
    Email:
      type: object
      properties:
        email:
          type: string
          examples:
          - john.snow@example.com
        status:
          type: string
          examples:
          - DELIVERABLE
          enum:
          - DELIVERABLE
          - HIGH_PROBABILITY
          - CATCH_ALL
          - INVALID
          - INVALID_DOMAIN
    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
    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
    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'
    Phone:
      type: object
      properties:
        number:
          type: string
          description: Phone number in international format (E.164)
          examples:
          - +33 6 76 78 90 65
        region:
          type: string
          description: ISO 3166-1 alpha-2 country code where the phone number is registered (e.g., FR for France, US for United States)
          examples:
          - FR
    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
    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'
    ResponsePostContactBulkEnrich:
      type: object
      properties:
        enrichment_id:
          type: string
          format: uuid
          examples:
          - 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
    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
    RecordEnrichment:
      type: object
      description: A single enriched contact record
      properties:
        input:
          description: The original input data provided for this contact
          $ref: '#/components/schemas/ContactEnrichmentInput'
        custom:
          type: object
          description: Custom fields passed during enrichment request, returned unchanged
          examples:
          - user_id: '12584'
        contact_info:
          description: Contact information found during enrichment (emails and phone numbers)
          $ref: '#/components/schemas/ContactEnrichedInformation'
        profile:
          description: Full professional profile of the person (returned when linkedin_url was provided)
          $ref: '#/components/schemas/Person'
    EmploymentCompany:
      type: o

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fullenrich/refs/heads/main/openapi/fullenrich-contact-enrichment-api-openapi.yml