abm-dev Enrichment API

openapi: 3.2.0
info:
  version: 2.0.0
  title: ABM.dev Enrichment API
  description: The account-based marketing API for AI agents. Search, Source, Enrich, and Create over B2B people and companies, every field cited with a source and confidence score.
  contact:
    name: ABM.dev
    url: https://abm.dev
servers:
- url: https://api.abm.dev
  description: Production
- url: https://api-dev.abm.dev
  description: Staging
security:
- ApiKeyAuth: []
tags:
- name: Enrichment
  description: Core enrichment operations - enrich persons and companies with data from multiple sources
paths:
  /v1/enrichments:
    post:
      operationId: createEnrichment
      tags:
      - Enrichment
      summary: Create enrichment
      description: Submit a new enrichment request. Returns 202 while processing completes asynchronously.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - input
              properties:
                type:
                  type: string
                  enum:
                  - person
                  - company
                  description: Entity type to enrich. For 'person' supply name/email/linkedInUrl; for 'company' supply companyName + domain or website (or linkedInCompanyPage).
                input:
                  $ref: '#/components/schemas/EnrichmentInput'
      responses:
        '202':
          description: Enrichment accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: listEnrichments
      tags:
      - Enrichment
      summary: List enrichments
      parameters:
      - name: status
        in: query
        schema:
          type: string
      - name: skip
        in: query
        schema:
          type: integer
          default: 0
        description: Number of records to skip
      - name: take
        in: query
        schema:
          type: integer
          default: 20
        description: Number of records to return
      responses:
        '200':
          description: Paginated list of enrichments
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/EnrichmentSummary'
                  total:
                    type: integer
  /v1/enrichments/stats:
    get:
      operationId: getEnrichmentStats
      tags:
      - Enrichment
      summary: Get enrichment statistics
      responses:
        '200':
          description: Enrichment statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  by_status:
                    type: object
                    additionalProperties:
                      type: integer
                  by_source:
                    type: object
                    additionalProperties:
                      type: integer
  /v1/enrichments/{id}:
    get:
      operationId: getEnrichment
      tags:
      - Enrichment
      summary: Get enrichment by ID
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Enrichment with result data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentResult'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: cancelEnrichment
      tags:
      - Enrichment
      summary: Cancel enrichment
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Enrichment cancelled
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/enrichments/{id}/stream:
    get:
      operationId: streamEnrichment
      tags:
      - Enrichment
      summary: Stream enrichment progress via SSE
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Server-Sent Events stream
          content:
            text/event-stream:
              schema:
                type: string
  /v1/enrichments/{id}/approve:
    post:
      operationId: approveEnrichment
      tags:
      - Enrichment
      summary: Approve enrichment and trigger CRM writeback
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                field_overrides:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Enrichment approved and CRM writeback initiated
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/enrichments/{id}/sources:
    get:
      operationId: getEnrichmentSources
      tags:
      - Enrichment
      summary: Get source breakdown for enrichment
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Source attribution breakdown
  /v1/enrichments/{id}/fields:
    get:
      operationId: getEnrichmentFields
      tags:
      - Enrichment
      summary: Get field attribution for enrichment
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Field-level source attribution
  /v1/enrichments/{id}/writeback-preview:
    get:
      operationId: getWritebackPreview
      tags:
      - Enrichment
      summary: Preview CRM diff before writeback
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: CRM field diff preview
  /v1/enrichments/{id}/export/excel:
    get:
      operationId: exportEnrichmentExcel
      tags:
      - Enrichment
      summary: Export enrichment as Excel
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Excel file download
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
  /v1/enrichments/batches/preview:
    post:
      operationId: previewBatch
      tags:
      - Enrichment
      summary: Preview a batch enrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - list_id
              - platform
              properties:
                list_id:
                  type: string
                platform:
                  type: string
      responses:
        '200':
          description: Batch preview with member count and credit estimate
  /v1/enrichments/batches/confirm:
    post:
      operationId: confirmBatch
      tags:
      - Enrichment
      summary: Confirm and start a batch enrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - batch_id
              properties:
                batch_id:
                  type: string
      responses:
        '202':
          description: Batch confirmed and processing started
  /v1/enrichments/batches:
    get:
      operationId: listBatches
      tags:
      - Enrichment
      summary: List enrichment batches
      responses:
        '200':
          description: List of enrichment batches
  /v1/enrichments/batches/{batchId}:
    get:
      operationId: getBatch
      tags:
      - Enrichment
      summary: Get enrichment batch
      parameters:
      - name: batchId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Batch details with status and progress
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/enrichments/batches/{batchId}/members:
    get:
      operationId: getBatchMembers
      tags:
      - Enrichment
      summary: Get batch members
      parameters:
      - name: batchId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of batch member enrichments
  /v1/enrichments/batches/{batchId}/approve:
    post:
      operationId: approveBatch
      tags:
      - Enrichment
      summary: Approve all enrichments in a batch
      parameters:
      - name: batchId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Batch approved
  /v1/enrichments/batches/{batchId}/export/excel:
    get:
      operationId: exportBatchExcel
      tags:
      - Enrichment
      summary: Export batch as Excel
      parameters:
      - name: batchId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Excel file download
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
  /v1/enrichments/{id}/writeback:
    post:
      operationId: executeWriteback
      tags:
      - Enrichment
      summary: Execute CRM writeback
      description: Push enriched data for a single enrichment to the connected CRM. The enrichment must be in approved status.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                field_overrides:
                  type: object
                  additionalProperties: true
                  description: Optional field-level overrides before writing
                create_if_missing:
                  type: boolean
                  default: false
                  description: Create a new CRM contact if no match found
      responses:
        '200':
          description: Writeback completed successfully
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/enrichments/bulk-writeback:
    post:
      operationId: bulkWriteback
      tags:
      - Enrichment
      summary: Bulk writeback to CRM
      description: Push enriched data for multiple enrichments to the connected CRM in a single operation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - enrichment_ids
              properties:
                enrichment_ids:
                  type: array
                  items:
                    type: integer
                  description: List of enrichment IDs to write back
                create_if_missing:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Bulk writeback results
          content:
            application/json:
              schema:
                type: object
                properties:
                  succeeded:
                    type: integer
                  failed:
                    type: integer
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        enrichment_id:
                          type: integer
                        error:
                          type: string
  /v1/enrichments/batches/upload:
    post:
      operationId: uploadBatchFile
      tags:
      - Enrichment
      summary: Upload file for batch enrichment
      description: Upload an Excel or CSV file containing contacts to enrich. Returns a preview of parsed rows and credit estimate.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Excel (.xlsx) or CSV file
      responses:
        '200':
          description: File parsed with preview
          content:
            application/json:
              schema:
                type: object
                properties:
                  upload_id:
                    type: string
                    format: uuid
                  row_count:
                    type: integer
                  columns_detected:
                    type: array
                    items:
                      type: string
                  preview_rows:
                    type: array
                    items:
                      type: object
                  estimated_credits:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
  /v1/enrichments/batches/upload/confirm:
    post:
      operationId: confirmUploadBatch
      tags:
      - Enrichment
      summary: Confirm uploaded batch
      description: Confirm a previously uploaded file and start batch enrichment processing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - upload_id
              properties:
                upload_id:
                  type: string
                  format: uuid
                column_mapping:
                  type: object
                  additionalProperties:
                    type: string
                  description: Map file columns to enrichment input fields
      responses:
        '202':
          description: Batch confirmed and processing started
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    EnrichmentInput:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        company:
          type: string
        companyName:
          type: string
        firmName:
          type: string
        linkedInUrl:
          type: string
          format: uri
        linkedInCompanyPage:
          type: string
          format: uri
        domain:
          type: string
        website:
          type: string
          format: uri
        crmId:
          type: string
    EnrichmentResult:
      allOf:
      - $ref: '#/components/schemas/EnrichmentSummary'
      - type: object
        properties:
          input:
            $ref: '#/components/schemas/EnrichmentInput'
          result_data:
            type: object
            description: Enriched data from all sources
          sources:
            type: array
            items:
              type: string
          completed_at:
            type: string
            format: date-time
    EnrichmentSummary:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - approved
          - writeback_pending
          - synced
          - failed
          - cancelled
          - partial_success
        type:
          type: string
        created_at:
          type: string
          format: date-time
  responses:
    NotFound:
      description: Resource not found
    Unauthorized:
      description: Missing or invalid API key
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              details:
                type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Clerk-issued JWT. Used for dashboard/portal requests and for the `/v1/organizations/signup` bootstrap endpoint.
x-tagGroups:
- name: Core API
  tags:
  - Enrichment
  - People Finder
  - Campaigns
- name: Configuration
  tags:
  - Field Configuration
  - Enrichment Config
- name: Integrations
  tags:
  - LinkedIn
  - CRM
  - Webhooks
- name: Account
  tags:
  - Organization
  - Health