leadmagic-io Batch API

openapi: 3.2.0
info:
  title: Leadmagic Io Batch API
  version: 1.4.35
  contact:
    name: LeadMagic Support
    email: support@leadmagic.io
    url: https://leadmagic.io
  termsOfService: https://leadmagic.io/legal/terms
  description: 'Operations tagged Batch across 2 of this provider''s published API definitions: leadmagic-io-leadmagic-openapi-3-1-openapi.json, leadmagic-io-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.leadmagic.io
  description: Production API Server
security:
- ApiKeyAuth: []
tags:
- name: Batch
  description: Campaign-oriented batch enrichment with budgets, clients, suppression lists, and webhooks
paths:
  /v1/batch:
    get:
      summary: List Batches
      description: List batches across all products for the authenticated organization.
      operationId: batch-list
      tags:
      - Batch
      parameters:
      - name: product
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: client_id
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        '200':
          description: Paginated batch list.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Submit a Mixed-Product Batch
      description: Submit a batch containing items for one or more enrichment products.
      operationId: batch-submit
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  description: Batch items. Each item carries `product` (required for mixed-product batches), `input`, and optional `client_id`, `client_name`, and `metadata`.
                  minItems: 1
                  maxItems: 500
                  items:
                    type: object
                    properties:
                      product:
                        type: string
                        description: Product to run this item against.
                      input:
                        type: object
                        description: Product-specific input fields.
                      client_id:
                        type: string
                      client_name:
                        type: string
                      metadata:
                        type: object
                idempotencyKey:
                  type: string
                  description: Submitting the same key twice returns the original batch instead of creating a duplicate.
                metadata:
                  type: object
                  description: Arbitrary metadata stored with the batch.
                client_id:
                  type: string
                  description: Associate the whole batch with a client record.
                client_name:
                  type: string
                  description: Client name recorded alongside the batch.
                budget_user_id:
                  type: string
                  description: Charge the batch against this member's credit budget.
                webhook_url:
                  type: string
                  format: uri
                  description: HTTPS URL notified when the batch completes. SSRF-validated — must resolve to a public IP.
                priority:
                  type: string
                  description: Queue priority for this batch.
                  enum:
                  - normal
                  - low
      responses:
        '202':
          description: Batch accepted.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/{batchId}:
    get:
      summary: Get Batch Status
      description: Return status, progress, cost, and metadata for a mixed-product batch.
      operationId: batch-status
      tags:
      - Batch
      parameters:
      - name: batchId
        in: path
        required: true
        description: Identifier of the batch returned when it was submitted.
        schema:
          type: string
      responses:
        '200':
          description: Batch status.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/{product}/batch/{batchId}:
    patch:
      summary: Update Batch Metadata
      description: Update batch metadata or its associated client within the mutable window.
      operationId: batch-update
      tags:
      - Batch
      parameters:
      - name: product
        in: path
        required: true
        description: Enrichment product slug, e.g. `email-finder`. Hyphens and underscores are both accepted.
        schema:
          type: string
      - name: batchId
        in: path
        required: true
        description: Identifier of the batch returned when it was submitted.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  additionalProperties: true
                client_id:
                  type: string
      responses:
        '200':
          description: Updated batch.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/campaign/{campaignId}/metrics:
    get:
      summary: Get Campaign Metrics
      description: Aggregate usage and success metrics across batches in a campaign.
      operationId: batch-campaign-metrics
      tags:
      - Batch
      parameters:
      - name: campaignId
        in: path
        required: true
        description: Campaign identifier used to group related batches.
        schema:
          type: string
      responses:
        '200':
          description: Campaign metrics.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/clients:
    get:
      summary: List Batch Clients
      description: List client records for the authenticated organization.
      operationId: batch-client-list
      tags:
      - Batch
      responses:
        '200':
          description: Client list.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create a Batch Client
      description: Create an organization-scoped client for segmenting downstream batch work.
      operationId: batch-client-create
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: Unique client identifier (slug). Lowercase, alphanumeric with hyphens.
                display_name:
                  type: string
                  description: Human-readable display name.
                contact_email:
                  type: string
                  format: email
                  description: Contact email for notifications.
                billing_rate:
                  type: number
                  description: Optional billing rate applied to this client.
                notes:
                  type: string
                  description: Internal notes.
                industry:
                  type: string
                  description: Industry classification.
                website:
                  type: string
                  description: Client website.
                phone:
                  type: string
                  description: Phone number.
                address:
                  type: object
                  description: Physical address object.
                custom_fields:
                  type: object
                  description: Arbitrary custom fields stored with the client.
      responses:
        '201':
          description: Client created.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/clients/{clientId}/metrics:
    get:
      summary: Get Batch Client Metrics
      description: Return aggregate batch usage and success metrics for a client.
      operationId: batch-client-metrics
      tags:
      - Batch
      parameters:
      - name: clientId
        in: path
        required: true
        description: UUID of the client record, returned when the client was created.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Client metrics.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/clients/{clientId}/webhooks:
    get:
      summary: List Batch Client Webhooks
      description: List delivery webhooks configured for a client.
      operationId: batch-client-webhook-list
      tags:
      - Batch
      parameters:
      - name: clientId
        in: path
        required: true
        description: UUID of the client record, returned when the client was created.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Client webhook list.
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create a Batch Client Webhook
      description: Register a webhook for client batch lifecycle events.
      operationId: batch-client-webhook-create
      tags:
      - Batch
      parameters:
      - name: clientId
        in: path
        required: true
        description: UUID of the client record, returned when the client was created.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '201':
          description: Webhook created.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/providers:
    get:
      summary: List External Batch Providers
      description: List external enrichment providers registered by the organization.
      operationId: batch-provider-list
      tags:
      - Batch
      responses:
        '200':
          description: Provider list with credentials redacted.
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create an External Batch Provider
      description: Register an HTTPS external enrichment provider.
      operationId: batch-provider-create
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - baseUrl
              - authType
              - authCredentialName
              - authCredentialValue
              properties:
                name:
                  type: string
                  description: Display name for the provider.
                baseUrl:
                  type: string
                  format: uri
                  description: HTTPS endpoint to call. Private IP addresses are rejected.
                authType:
                  type: string
                  description: How the credential is presented to the provider.
                  enum:
                  - api_key
                  - bearer
                  - header
                authCredentialName:
                  type: string
                  description: Header or parameter name carrying the credential.
                authCredentialValue:
                  type: string
                  description: Credential value. Redacted in every response.
                defaultMethod:
                  type: string
                  description: HTTP method used for provider calls.
                  enum:
                  - GET
                  - POST
                defaultHeaders:
                  type: object
                  description: Extra headers sent with every provider call.
                rateLimitRpm:
                  type: integer
                  description: Requests per minute ceiling for this provider.
                responseMapping:
                  type: object
                  description: Maps provider response fields onto LeadMagic output columns.
                healthCheckUrl:
                  type: string
                  format: uri
                  description: URL polled to determine provider health.
                healthCheckExpectedStatus:
                  type: integer
                  description: HTTP status treated as healthy.
      responses:
        '201':
          description: Provider created with credentials redacted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
components:
  schemas:
    ErrorResponse:
      type: object
      description: RFC 9457 Problem Details error response
      required:
      - success
      - errors
      properties:
        success:
          type: boolean
          description: Always false for error responses
        errors:
          type: array
          description: Array of error details (typically one, but can be multiple)
          items:
            $ref: '#/components/schemas/ErrorDetail'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ProfileNotFoundError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    ErrorDetail:
      type: object
      description: RFC 9457 compliant error detail
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
          description: RFC 9457 - URI reference identifying the error type
        title:
          type: string
          description: RFC 9457 - Short human-readable summary
        status:
          type: integer
          description: RFC 9457 - HTTP status code
        detail:
          type: string
          description: RFC 9457 - Human-readable explanation specific to this occurrence
        instance:
          type: string
          format: uri-reference
          description: RFC 9457 - URI reference for this specific occurrence
        code:
          type: string
          description: Machine-readable error code for programmatic handling
        param:
          type: array
          description: Parameters that caused the error
          items:
            type: string
        action:
          type: string
          description: Suggested action to resolve the error
        docs:
          type: string
          format: uri
          description: Link to relevant documentation
        context:
          type: object
          description: Additional context specific to this error type. 404 route_not_found errors include suggested_endpoint (canonical path to use instead) in this object; validation errors include the offending field and received value.
          additionalProperties: true
    ResponseMeta:
      type: object
      description: Metadata included in all responses
      properties:
        request_id:
          type: string
          format: uuid
          description: Unique identifier for this request (use for debugging/support)
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the response was generated
        environment:
          type: string
          description: API environment (production, staging)
    ResourceNotFoundError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    MissingAuthenticationError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    InvalidApiKeyError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    ErrorResponse_2:
      type: object
      description: RFC 9457 Problem Details error response
      required:
      - success
      - errors
      properties:
        success:
          type: boolean
          example: false
          description: Always false for error responses
        errors:
          type: array
          description: Array of error details (typically one, but can be multiple)
          items:
            $ref: '#/components/schemas/ErrorDetail_2'
        meta:
          $ref: '#/components/schemas/ResponseMeta_2'
    ProfileNotFoundError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse_2'
      example:
        success: false
        errors:
        - type: https://api.leadmagic.io/errors/profile_not_found
          title: Profile not found or not accessible
          status: 404
          code: profile_not_found
          docs: https://leadmagic.io/docs/v1/making-api-calls#error-handling
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    ValidationError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse_2'
      example:
        success: false
        errors:
        - type: https://api.leadmagic.io/errors/validation_error
          title: Request validation failed. Check your input parameters.
          status: 400
          code: validation_error
          param:
          - email
          detail: 'Email format is invalid. Expected format: user@domain.com'
          action: Provide a valid email address in the 'email' field.
          docs: https://leadmagic.io/docs/v1/making-api-calls#error-handling
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    ErrorDetail_2:
      type: object
      description: RFC 9457 compliant error detail
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
          description: RFC 9457 - URI reference identifying the error type
          example: https://api.leadmagic.io/errors/validation_error
        title:
          type: string
          description: RFC 9457 - Short human-readable summary
          example: Request validation failed. Check your input parameters.
        status:
          type: integer
          description: RFC 9457 - HTTP status code
          example: 400
        detail:
          type: string
          description: RFC 9457 - Human-readable explanation specific to this occurrence
          example: The email field is required but was not provided.
        instance:
          type: string
          format: uri-reference
          description: RFC 9457 - URI reference for this specific occurrence
          example: /v1/people/email-validation#req_abc123
        code:
          type: string
          description: Machine-readable error code for programmatic handling
          example: validation_error
        param:
          type: array
          description: Parameters that caused the error
          items:
            type: string
          example:
          - email
        action:
          type: string
          description: Suggested action to resolve the error
          example: Provide a valid email address in the 'email' field.
        docs:
          type: string
          format: uri
          description: Link to relevant documentation
          example: https://leadmagic.io/docs/v1/making-api-calls#error-handling
        context:
          type: object
          description: Additional context specific to this error type. 404 route_not_found errors include suggested_endpoint (canonical path to use instead) in this object; validation errors include the offending field and received value.
          additionalProperties: true
    ResponseMeta_2:
      type: object
      description: Metadata included in all responses
      properties:
        request_id:
          type: string
          format: uuid
          description: Unique identifier for this request (use for debugging/support)
          example: ea6e3248-f4d2-437d-bca3-20881b529129
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the response was generated
          example: '2024-02-01T12:00:00.000Z'
        environment:
          type: string
          description: API environment (production, staging)
          example: production
    ResourceNotFoundError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse_2'
      example:
        success: false
        errors:
        - type: https://api.leadmagic.io/errors/resource_not_found
          title: Resource not found.
          status: 404
          code: resource_not_found
          docs: https://leadmagic.io/docs/v1/making-api-calls#error-handling
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    MissingAuthenticationError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse_2'
      example:
        success: false
        errors:
        - type: https://api.leadmagic.io/errors/missing_authentication
          title: Authentication required. Provide a valid API key in the X-API-Key header (case-insensitive).
          status: 401
          code: missing_authentication
          docs: https://leadmagic.io/docs/v1/authentication
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    InvalidApiKeyError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse_2'
      example:
        success: false
        errors:
        - type: https://api.leadmagic.io/errors/invalid_api_key
          title: Invalid API key. The key does not exist or is incorrect.
          status: 401
          code: invalid_api_key
          docs: https://leadmagic.io/docs/v1/authentication
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
  responses:
    NotFound:
      description: 'Not Found - The requested resource could not be found.


        **Common causes:**

        - Profile doesn''t exist or is not accessible

        - Company not found in our database

        - Invalid URL or identifier

        '
      content:
        application/problem+json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ResourceNotFoundError'
            - $ref: '#/components/schemas/ProfileNotFoundError'
    BadRequest:
      description: 'Bad Request - The request was malformed or contains invalid parameters.


        **Common causes:**

        - Missing required fields

        - Invalid field format (e.g., malformed email)

        - Invalid JSON syntax

        - Invalid parameter values

        '
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    Unauthorized:
      description: 'Unauthorized - Authentication failed.


        **Common causes:**

        - Missing X-API-Key header

        - Invalid or expired API key

        - Malformed API key

        '
      content:
        application/problem+json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/MissingAuthenticationError'
            - $ref: '#/components/schemas/InvalidApiKeyError'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your LeadMagic API key. Header name is case-insensitive (X-API-Key, X-API-KEY, x-api-key all work).
x-refined-from:
- leadmagic-io-leadmagic-openapi-3-1-openapi.json
- leadmagic-io-openapi.json