Leadspace Enrichment API

openapi: 3.1.0
info:
  title: Leadspace Enrichment API v4
  description: >-
    The Leadspace Enrichment API enriches person (lead/contact) and company
    (account) records against the Leadspace Universal Graph (v4 data graph).
    Single Direct requests are synchronous; Bulk requests accept up to 500
    records per POST and are retrieved asynchronously by polling a results
    endpoint or via a callback URL. This document was generated by API
    Evangelist from Leadspace's published technical specifications; Leadspace
    does not publish a machine-readable OpenAPI definition.
  version: '4.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
externalDocs:
  description: Leadspace Single Direct API v4 - Technical Specifications
  url: https://support.leadspace.com/hc/en-us/articles/23687993264284-Leadspace-Single-Direct-API-v4-Technical-Specifications
servers:
  - url: https://apigw.leadspace.com
    description: Leadspace API gateway (production)
tags:
  - name: Authorization
    description: OAuth 2.0 token issuance and refresh
  - name: Enrichment
    description: Single and bulk person and company enrichment
  - name: Results
    description: Polling for asynchronous bulk results
security:
  - bearerAuth: []
paths:
  /oauth/authorize:
    post:
      operationId: createAuthorizationToken
      summary: Request an OAuth 2.0 access token
      description: >-
        Exchanges the Program ID and authentication secret supplied by Leadspace
        for a bearer token. Tokens expire every 24 hours.
      tags:
        - Authorization
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationRequest'
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: refreshAuthorizationToken
      summary: Refresh an OAuth 2.0 access token
      description: Exchanges a refreshToken for a new bearer token.
      tags:
        - Authorization
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
      responses:
        '200':
          description: Token refreshed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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
  /v3/enrichment/results/{bulkId}:
    get:
      operationId: getBulkEnrichmentResults
      summary: Poll for bulk enrichment results
      description: Retrieves the results of a previously submitted bulk enrichment job.
      tags:
        - Results
      parameters:
        - name: bulkId
          in: path
          required: true
          description: The Leadspace bulk identifier returned when the job was accepted
          schema:
            type: string
      responses:
        '200':
          description: The request is done
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResults'
        '204':
          description: The request is still processing
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The results are not found
        '500':
          $ref: '#/components/responses/ServerError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization header in the form 'Bearer API_KEY'. The API key is either
        a perpetual token issued by Leadspace or an OAuth 2.0 token obtained
        from POST /oauth/authorize.
  responses:
    BadRequest:
      description: >-
        The request failed due to insufficient basic input, or the JSON format
        is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    AuthorizationRequest:
      type: object
      required: [user, pass, audience]
      properties:
        user:
          type: string
          description: The Program ID Leadspace provided in the credentials email
        pass:
          type: string
          description: The authentication secret Leadspace provided in the credentials email
        audience:
          type: string
          description: For API v4 services use API_GATEWAY
          examples: ['API_GATEWAY']
    RefreshRequest:
      type: object
      required: [user, refreshToken]
      properties:
        user:
          type: string
        refreshToken:
          type: string
    AuthorizationResponse:
      type: object
      properties:
        token:
          type: string
          description: The generated token to use in API v4 enrichment requests
        refreshToken:
          type: string
          description: Value to use in refresh token requests
        expiration:
          type: integer
          description: Epoch seconds of the expiration moment
    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
    AddressInput:
      type: object
      properties:
        country:
          type: string
        state:
          type: string
        city:
          type: string
        street:
          type: string
        postalcode:
          type: string
    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'
    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'
    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
    EnrichmentResult:
      type: object
      properties:
        status:
          type: string
          enum: [success, failure]
        external_id:
          type: string
        data:
          $ref: '#/components/schemas/EnrichedRecord'
    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
    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
    EnrichedAddress:
      type: object
      properties:
        country:
          type: string
        state:
          type: string
        city:
          type: string
        region:
          type: string
        address:
          type: string
        zipcode:
          type: string
    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'
    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
    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
    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
    ProfileScore:
      type: object
      properties:
        profile_name:
          type: string
        score:
          type: object
          properties:
            value:
              type: number
            bucket:
              type: string
              enum: [A, B, C, D]
    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']
    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
    BulkResults:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/EnrichmentResult'
    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