openapi: 3.1.0
info:
  title: Leadspace Discovery Authorization Enrichment API
  description: The Leadspace Discovery (Expansion) API finds net-new contacts inside target accounts. A bulk request expands up to 500 accounts, ranking discovered people against persona, region, and required-contact-information criteria, and returns a polling URI for asynchronous retrieval. This document was generated by API Evangelist from Leadspace's published technical specifications; Leadspace does not publish a machine-readable OpenAPI definition.
  version: '2.0'
  contact:
    name: Leadspace Support
    url: https://support.leadspace.com/hc/en-us
    email: support@leadspace.com
  termsOfService: https://www.leadspace.com/service-support-terms
servers:
- url: https://apigw.leadspace.com
  description: Leadspace API gateway (production)
security:
- bearerAuth: []
tags:
- name: Enrichment
  description: Single and bulk person and company enrichment
paths:
  /enrichment/enrich/single:
    post:
      operationId: enrichSingleRecord
      summary: Enrich a single person and/or company record
      description: Synchronously enriches one record. Account enrichment requires a company name. Person enrichment requires first name, last name, and one of company name, email address, or website.
      tags:
      - Enrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleEnrichmentRequest'
      responses:
        '200':
          description: The enrichment request was successfully processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          description: Invalid HTTP method
        '415':
          description: Bad or missing HTTP headers
        '427':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
  /enrichment/enrich/bulk:
    post:
      operationId: enrichBulkRecords
      summary: Submit a bulk enrichment job
      description: Accepts up to 500 records per request and returns a polling URI. An optional callbackUrl receives a notification when processing completes.
      tags:
      - Enrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkEnrichmentRequest'
      responses:
        '202':
          description: The bulk job was successfully accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '427':
          $ref: '#/components/responses/InsufficientCredits'
        '500':
          $ref: '#/components/responses/ServerError'
      callbacks:
        bulkComplete:
          '{$request.body#/callbackUrl}':
            post:
              operationId: bulkCompleteCallback
              summary: Bulk completion callback
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/BulkCallback'
              responses:
                '200':
                  description: Callback acknowledged
components:
  schemas:
    EnrichedCompany:
      type: object
      properties:
        ug_company_id:
          type: string
          description: Leadspace unique company identifier
        ls_id:
          type: string
          description: Legacy v3 company identifier that mirrors ug_company_id; scheduled for sunset in 2026
        name:
          type: string
        original_name:
          type: string
        description:
          type: string
        website:
          type: string
        phone:
          type: string
        industry:
          type: string
        sub_industry:
          type: string
        sic:
          type: string
        sicDescription:
          type: string
        naics:
          type: string
        naicsDescription:
          type: string
        ownership:
          type: string
        linkedin_profile:
          type: string
        latitude:
          type: string
        longitude:
          type: string
        primary_location:
          type: string
        address:
          $ref: '#/components/schemas/EnrichedAddress'
        employees:
          type: object
          properties:
            exact:
              type: number
            range:
              type: string
        revenue_dollar:
          type: object
          properties:
            exact:
              type: number
            range:
              type: string
        matching_confidence:
          type: object
          properties:
            level:
              type: string
              enum:
              - HIGH
              - MEDIUM
              - LOW
              - VERY LOW
        family_tree:
          $ref: '#/components/schemas/CompanyFamilyTree'
        department_size:
          $ref: '#/components/schemas/DepartmentSize'
        funding:
          $ref: '#/components/schemas/CompanyFunding'
        investors:
          $ref: '#/components/schemas/CompanyInvestors'
        signals:
          type: object
          properties:
            fortune_500_rank:
              type: number
            fortune_1000_rank:
              type: number
            g2k_rank:
              type: number
        intent_modeling_v4:
          $ref: '#/components/schemas/IntentModeling'
        domain_intent:
          type: string
        specialties:
          type: array
          items:
            type: string
        analytics:
          type: object
          properties:
            installed_base_technologies:
              type: array
              items:
                type: string
            web_site_technologies:
              type: array
              items:
                type: string
            company_technologies_categories:
              type: array
              items:
                type: string
            customTechnologiesCategories:
              type: array
              items:
                type: string
    CompanyFamilyTree:
      type: object
      description: The company hierarchy in addition to the matched company
      properties:
        companies:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - DU
                - GU
                - SITE
                - PARENT
                - HQ
                - SU
              name:
                type: string
              ls_id:
                type: string
              website:
                type: string
              phone:
                type: string
              sic:
                type: string
              naics:
                type: string
              address:
                $ref: '#/components/schemas/EnrichedAddress'
    CompanyFunding:
      type: object
      properties:
        last_round_investor_count:
          type: number
        total_rounds_count:
          type: number
        last_round_date:
          type: string
        last_round_money_raised:
          type: string
        last_round_type:
          type: string
        cb_url:
          type: string
    BulkCallback:
      type: object
      properties:
        bulkId:
          type: string
        callbackMethod:
          type: object
          properties:
            callbackUrl:
              type: string
            pollingUrl:
              type: string
        bulkStatus:
          type: string
          enum:
          - COMPLETED
          - INSUFFICIENT_CREDITS
          - INTERNAL_ERROR
        successRecords:
          type: integer
        personEnriched:
          type: integer
        companyEnriched:
          type: integer
    CustomField:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    SingleEnrichmentRequest:
      type: object
      properties:
        person:
          $ref: '#/components/schemas/PersonInput'
        company:
          $ref: '#/components/schemas/CompanyInput'
        external_id:
          type: string
          description: External identifier echoed back on the result. Not used for processing.
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
    CompanyInvestors:
      type: object
      properties:
        cb_url:
          type: string
        last_investor_name:
          type: string
        company_investors:
          type: string
    IntentModeling:
      type: object
      properties:
        model:
          type: string
        model_level:
          type: array
          items:
            type: string
            enum:
            - High
            - Medium
            - Low
            - NO_INTENT
        source:
          type: string
          description: Either LS Intent or Bombora
        cadence:
          type: string
        new_high_intent:
          type: string
        industries:
          type: array
          items:
            type: string
        top_metros:
          type: array
          items:
            type: string
        domain_origins:
          type: array
          items:
            type: string
    AddressInput:
      type: object
      properties:
        country:
          type: string
        state:
          type: string
        city:
          type: string
        street:
          type: string
        postalcode:
          type: string
    BulkEnrichmentRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          maxItems: 500
          description: Up to 500 records per POST
          items:
            $ref: '#/components/schemas/SingleEnrichmentRequest'
        callbackUrl:
          type: string
          description: URL Leadspace calls back when bulk processing completes
        external_bulk_id:
          type: string
    EnrichedRecord:
      type: object
      properties:
        person:
          $ref: '#/components/schemas/EnrichedPerson'
        company:
          $ref: '#/components/schemas/EnrichedCompany'
        enrichment_status:
          type: string
          enum:
          - Not Enriched
          - Company Enriched
          - Person Enriched
          - Person & Company Enriched
        cdi_matched:
          type: string
        total_scores:
          type: array
          items:
            $ref: '#/components/schemas/ProfileScore'
        max_positive_total_score_profiles:
          type: array
          items:
            type: string
    ProfileScore:
      type: object
      properties:
        profile_name:
          type: string
        score:
          type: object
          properties:
            value:
              type: number
            bucket:
              type: string
              enum:
              - A
              - B
              - C
              - D
    EnrichedAddress:
      type: object
      properties:
        country:
          type: string
        state:
          type: string
        city:
          type: string
        region:
          type: string
        address:
          type: string
        zipcode:
          type: string
    EnrichedPerson:
      type: object
      properties:
        ug_person_id:
          type: string
          description: Unique Leadspace person identifier
        first_name:
          type: string
        last_name:
          type: string
        title:
          type: string
        department:
          type: string
        level:
          type: string
          enum:
          - C Level
          - Board Level
          - VP Level
          - Director Level
          - Manager Level
          - Staff Level
        email:
          type: string
        original_email:
          type: string
        original_email_verification_status:
          type: string
          enum:
          - VALID
          - INVALID
          - UNKNOWN
          - CATCH-ALL
        verification_status:
          type: string
          enum:
          - Moved
          - Verified
          - Not Verified
        verification_source:
          type: string
          enum:
          - Social
          - Email
          - Social & Email
        linkedin_profile:
          type: string
        phone:
          type: string
        is_retired:
          type: string
        address:
          $ref: '#/components/schemas/EnrichedAddress'
        analytics:
          type: object
          properties:
            job_functions:
              type: array
              items:
                type: string
            technologies:
              type: array
              items:
                type: string
            scores:
              type: array
              items:
                $ref: '#/components/schemas/ProfileScore'
            max_positive_score_profiles:
              type: array
              items:
                type: string
    DepartmentSize:
      type: object
      properties:
        hr:
          type: number
        sales:
          type: number
        mgmt:
          type: number
        product_mgmt:
          type: number
        it:
          type: number
        administration:
          type: number
        marketing:
          type: number
        operations:
          type: number
        rnd:
          type: number
        business_dev:
          type: number
        finance:
          type: number
    BulkAccepted:
      type: object
      properties:
        id:
          type: string
          description: The polling endpoint URI to extract the bulk results
          examples:
          - /v3/enrichment/results/a4b6e123-8905-4dff-a966-50c3ce8f78ft
    EnrichmentResult:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - failure
        external_id:
          type: string
        data:
          $ref: '#/components/schemas/EnrichedRecord'
    CompanyInput:
      type: object
      properties:
        lsid:
          type: string
          description: Leadspace company identifier; when supplied it is matched on first
        ugLsid:
          type: string
          description: Universal Graph company identifier
        name:
          type: string
        website:
          type: string
        companyLinkedinUrl:
          type: string
        address:
          $ref: '#/components/schemas/AddressInput'
    PersonInput:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        title:
          type: string
        person_phone:
          type: string
        person_country:
          type: string
        linkedinUrl:
          type: string
    Error:
      type: object
      description: General Leadspace JSON error envelope
      properties:
        error:
          type: string
          description: Error description
        tracking_id:
          type: string
          description: Leadspace tracking identifier for further inspection
        request_timestamp:
          type: string
          description: Timestamp assigned when the request reached Leadspace servers
        details:
          type: string
  responses:
    Unauthorized:
      description: Unauthorized request (wrong credentials or credentials have expired)
    InsufficientCredits:
      description: Insufficient credits, or the program ID is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimitExceeded:
      description: Rate limit was exceeded
    BadRequest:
      description: The request failed due to insufficient basic input, or the JSON format is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Authorization header in the form 'Bearer API_KEY'
externalDocs:
  description: Leadspace Discovery API documentation
  url: https://support.leadspace.com/hc/en-us/articles/360011926619-Leadspace-Discovery-API