> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate Enrichment Run

> Submits a batch of candidate profile IDs for deep background enrichment. Returns immediately with a requestId and status 'processing'. Results are delivered via webhook (ENRICH_COMPLETED / ENRICH_FAILED) or polled at GET /sourcing/enrich/{id}/results. Consumes 1 credit per successfully enriched profile.

Submits a batch of candidate profile IDs for deep enrichment. Returns immediately with a `requestId` and `status: "processing"`. Results are delivered via webhook or polled at [GET /sourcing/enrich/{id}/results](/api-reference/sourcing/get-enrich-results).

## Overview

Enrichment performs a deep background evaluation of each profile against external indexing platforms, scrapes publicly available portfolios, and attempts to discover **verified email contact addresses**. Each successfully enriched profile consumes **1 credit**.

### Resilience Behaviour

* **Per-profile timeout**: 10 seconds per candidate.
* **Isolated failures**: if a single profile times out or fails, it is isolated and marked as failed. The remaining profiles in the batch continue processing.
* **Billing**: only successfully enriched profiles are billed.

## Billing Pre-Flight

* **Prepaid accounts**: your credit balance must be ≥ the number of requested profile IDs. If insufficient, the API returns `402 Payment Required` before any enrichment starts.
* **Postpaid accounts**: the run starts immediately; credits are recorded and invoiced at end of the billing cycle.

## Webhook Delivery

Pass a `webhookId` referencing a `WebhookConfig` that subscribes to at least one of `ENRICH_COMPLETED` or `ENRICH_FAILED`. The webhook config must belong to the same company as the API key.

## Examples

### Request

```json theme={null}
{
  "profileIds": ["prof_a9238f82-a723", "prof_e8321c12-b912"],
  "webhookId": "3f9a12c7-44b8-4d32-b71f-e29a7d1e0f5c"
}
```

### Response (202 Accepted)

```json theme={null}
{
  "success": true,
  "requestId": "enr_550e8400-e29b-41d4-a716-446655440001",
  "status": "processing",
  "message": "Enrichment run accepted and queued for processing.",
  "webhookId": "3f9a12c7-44b8-4d32-b71f-e29a7d1e0f5c",
  "createdAt": "2026-05-20T13:21:00.000Z"
}
```

## Error Responses

### 402 — Insufficient Credits (Prepaid)

```json theme={null}
{
  "statusCode": 402,
  "error": "INSUFFICIENT_FUNDS",
  "message": "Insufficient credits. Need 2, have 0."
}
```

### 422 — Webhook Not Subscribed to Enrichment Events

```json theme={null}
{
  "statusCode": 422,
  "error": "WEBHOOK_EVENT_NOT_SUBSCRIBED",
  "message": "Webhook configuration must subscribe to at least one enrich event (ENRICH_COMPLETED or ENRICH_FAILED)."
}
```


## OpenAPI

````yaml POST /sourcing/enrich
openapi: 3.0.0
info:
  title: InstaView API
  description: |-
    InstaView API Documentation

    ## Authentication

    All endpoints require API key authentication using Bearer token:
    ```
    Authorization: Bearer sk_your_api_key_here
    ```

    ## API Key Management

    The API Key module provides comprehensive key management for:
    - **Direct Client Keys**: Company-scoped keys for your applications
    - **ATS Partner Keys**: Resource-scoped keys for ATS integrations

    ### Key Features
    - HMAC-SHA256 hashing for API key storage
    - Configurable rate limiting
    - Comprehensive audit logging
    - Company-level isolation
    - Resource scoping for ATS partners
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.instaview.sk
    description: Production API Gateway
security: []
tags: []
paths:
  /sourcing/enrich:
    post:
      tags:
        - Public Sourcing
      summary: Initiate enrichment run
      description: >-
        Submits a batch of candidate profile IDs for deep background enrichment.
        Returns immediately with a requestId and status 'processing'. Results
        are delivered via webhook (ENRICH_COMPLETED / ENRICH_FAILED) or polled
        at GET /sourcing/enrich/{id}/results. Consumes 1 credit per successfully
        enriched profile.
      operationId: PublicSourcingController_enrichProfiles_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicEnrichProfilesDto'
      responses:
        '202':
          description: Enrichment run accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicInitiateEnrichResponseDto'
        '400':
          description: Bad Request - Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - Insufficient prepaid credit balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Insufficient scope or webhook company mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Webhook config not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - Webhook not subscribed to enrich events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearer: []
components:
  schemas:
    PublicEnrichProfilesDto:
      type: object
      properties:
        profileIds:
          type: array
          description: Array of profile IDs to enrich. Maximum 10 per request.
          items:
            type: string
          minItems: 1
          maxItems: 10
          example:
            - profile_abc123
            - profile_def456
        webhookId:
          type: string
          format: uuid
          description: >-
            UUID of a WebhookConfig to notify when the enrichment run completes
            or fails. The webhook must belong to the same company and subscribe
            to at least one enrich event (ENRICH_COMPLETED or ENRICH_FAILED).
          example: 123e4567-e89b-12d3-a456-426614174000
      required:
        - profileIds
    PublicInitiateEnrichResponseDto:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was accepted for processing.
          example: true
        requestId:
          type: string
          description: Unique identifier for this enrichment run.
          example: enr_550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          description: Current status of the enrichment run.
          enum:
            - processing
            - completed
            - failed
          example: processing
        message:
          type: string
          description: Human-readable message.
          example: Enrichment run accepted and queued for processing.
        webhookId:
          type: string
          description: >-
            UUID of the webhook configuration that will receive completion
            events.
          example: 123e4567-e89b-12d3-a456-426614174000
        createdAt:
          type: string
          description: ISO 8601 timestamp when the run was created.
          example: '2025-01-01T00:00:00.000Z'
      required:
        - success
        - requestId
        - status
        - message
        - createdAt
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
          example: Validation failed
        error:
          type: string
          example: Bad Request
      required:
        - statusCode
        - message
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key for authentication using Bearer scheme

````