leadmagic-io Cost Control API

openapi: 3.2.0
info:
  title: Leadmagic Io Cost Control 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 Cost Control 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: Cost Control
  description: Preview costs, manage credit budgets, and maintain suppression lists to control spend
paths:
  /v1/batch/preview-cost:
    post:
      summary: Preview Batch Cost
      description: Estimate the credit cost and budget impact of a batch enrichment without reserving or consuming credits. FREE dry-run.
      operationId: preview-cost-mixed
      tags:
      - Cost Control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewCostRequest'
      responses:
        '200':
          description: Cost estimate returned (no credits consumed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewCostResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/budgets:
    post:
      summary: Create Credit Budget
      description: Create a new credit budget to cap spend per scope.
      operationId: create-budget
      tags:
      - Cost Control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - scope
              - scope_value
              - max_credits
              properties:
                scope:
                  type: string
                scope_value:
                  type: string
                max_credits:
                  type: number
                period:
                  type: string
                alert_threshold_pct:
                  type: number
                  minimum: 0
                  exclusiveMinimum: 0
                  maximum: 1
                  exclusiveMaximum: 1
                alert_email:
                  type: string
                  format: email
      responses:
        '201':
          description: Budget created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Budget'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    get:
      summary: List Credit Budgets
      description: List all credit budgets for the authenticated account.
      operationId: list-budgets
      tags:
      - Cost Control
      responses:
        '200':
          description: List of budgets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Budget'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/budgets/status:
    get:
      summary: Get Budget Status
      description: Consumption status for all budgets.
      operationId: budget-status
      tags:
      - Cost Control
      responses:
        '200':
          description: Budget consumption status.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BudgetStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/budgets/{id}:
    patch:
      summary: Update Credit Budget
      description: Update max_credits, period, alert_threshold_pct, and/or alert_email.
      operationId: update-budget
      tags:
      - Cost Control
      parameters:
      - name: id
        in: path
        required: true
        description: Identifier of the credit budget.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                max_credits:
                  type: number
                period:
                  type: string
                alert_threshold_pct:
                  type: number
                alert_email:
                  type: string
      responses:
        '200':
          description: Updated budget.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Budget'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete Credit Budget
      description: Hard-delete a credit budget.
      operationId: delete-budget
      tags:
      - Cost Control
      parameters:
      - name: id
        in: path
        required: true
        description: Identifier of the credit budget.
        schema:
          type: string
      responses:
        '200':
          description: Budget deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/suppression-lists:
    post:
      summary: Create Suppression List
      description: Create a new suppression list with initial emails. Emails are SHA-256 hashed server-side.
      operationId: create-suppression-list
      tags:
      - Cost Control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - list_id
              - emails
              properties:
                list_id:
                  type: string
                emails:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Suppression list created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuppressionList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      summary: List Suppression Lists
      description: List all suppression lists for the authenticated account.
      operationId: list-suppression-lists
      tags:
      - Cost Control
      responses:
        '200':
          description: List of suppression lists.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SuppressionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/suppression-lists/{listId}:
    get:
      summary: Get Suppression List
      description: Get list details and paginated email hashes.
      operationId: get-suppression-list
      tags:
      - Cost Control
      parameters:
      - name: listId
        in: path
        required: true
        description: Identifier of the suppression list.
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 200
          maximum: 1000
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: List details with paginated hashes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuppressionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      summary: Delete Suppression List
      description: Delete an entire suppression list.
      operationId: delete-suppression-list
      tags:
      - Cost Control
      parameters:
      - name: listId
        in: path
        required: true
        description: Identifier of the suppression list.
        schema:
          type: string
      responses:
        '200':
          description: List deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
  /v1/batch/suppression-lists/{listId}/emails:
    post:
      summary: Add Emails to Suppression List
      description: Add emails to an existing suppression list. Emails are SHA-256 hashed server-side.
      operationId: add-suppression-emails
      tags:
      - Cost Control
      parameters:
      - name: listId
        in: path
        required: true
        description: Identifier of the suppression list.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Emails added.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      summary: Remove Emails from Suppression List
      description: Remove emails from a suppression list.
      operationId: remove-suppression-emails
      tags:
      - Cost Control
      parameters:
      - name: listId
        in: path
        required: true
        description: Identifier of the suppression list.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Emails removed.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.leadmagic.io
      description: Production API Server
components:
  schemas:
    RateLimitExceededError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    SuppressionList:
      type: object
      properties:
        list_id:
          type: string
        count:
          type: integer
        created_at:
          type: string
          format: date-time
    ProfileNotFoundError:
      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)
    InvalidApiKeyError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    ResourceNotFoundError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    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'
    BudgetStatus:
      type: object
      properties:
        scope:
          type: string
        scopeValue:
          type: string
        maxCredits:
          type: number
        remainingCredits:
          type: number
        isExceeded:
          type: boolean
    PreviewCostRequest:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 10000
          items:
            type: object
            properties:
              product:
                type: string
                description: Required for mixed-product mode. Omitted for per-product mode.
              input:
                type: object
                additionalProperties: true
              client_id:
                type: string
              client_name:
                type: string
              metadata:
                type: object
                additionalProperties: true
        budget_user_id:
          type: string
          description: User ID to check against configured Credit Budgets.
        client_id:
          type: string
        client_name:
          type: string
        metadata:
          type: object
          additionalProperties: true
    PreviewCostResponse:
      type: object
      required:
      - totalItems
      - totalCredits
      - estimatedCostUsd
      - perProduct
      - willExceedBudget
      properties:
        totalItems:
          type: integer
        creditsPerItem:
          type: number
          nullable: true
        totalCredits:
          type: number
        estimatedCostUsd:
          type: number
        perProduct:
          type: array
          items:
            type: object
            properties:
              product:
                type: string
              items:
                type: integer
              creditsPerItem:
                type: number
              credits:
                type: number
        clientCreditRemaining:
          type: string
          nullable: true
        willExceedBudget:
          type: boolean
    Budget:
      type: object
      properties:
        id:
          type: string
        scope:
          type: string
        scope_value:
          type: string
        max_credits:
          type: number
        period:
          type: string
        alert_threshold_pct:
          type: number
        alert_email:
          type: string
    MissingAuthenticationError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
    RateLimitExceededError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse_2'
      example:
        success: false
        errors:
        - type: https://api.leadmagic.io/errors/rate_limit_exceeded
          title: Email product allowance exceeded. Wait for Retry-After before retrying.
          status: 429
          code: rate_limit_exceeded
          detail: You have exceeded the maximum allowed request rate. Please wait before making additional requests.
          action: Wait 42 seconds before retrying. Consider implementing exponential backoff.
          docs: https://leadmagic.io/docs/v1/making-api-calls#rate-limits
          context:
            limit: 600
            window: 1 minute
            remaining: 0
            reset_at: 1706745642
            retry_after_seconds: 42
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    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'
    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
    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'
    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'
    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'
    InternalServerError_2:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse_2'
      example:
        success: false
        errors:
        - type: https://api.leadmagic.io/errors/INTERNAL_ERROR
          title: Something went wrong on our end. Our team has been notified and is investigating.
          status: 500
          code: INTERNAL_ERROR
          detail: This is a temporary server error. The issue has been automatically reported to our team.
          action: Wait 30 seconds and retry your request. If the problem persists, contact support@leadmagic.io
          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'
    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'
    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'
  responses:
    RateLimitExceeded:
      description: 'Too Many Requests - Rate limit exceeded.


        **Action required:** Check the `Retry-After` header for when to retry.


        **Headers returned:**

        - `Retry-After`: Seconds until you can retry

        - `RateLimit-Limit`: Your limit per minute

        - `RateLimit-Remaining`: Remaining requests this minute

        - `RateLimit-Reset`: Seconds until limit resets

        '
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per minute
        RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests this minute
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until limit resets
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/RateLimitExceededError'
    InternalServerError:
      description: 'Internal Server Error - Something went wrong on our end.


        **Action required:** Wait 30 seconds and retry. If the problem persists, contact support@leadmagic.io

        '
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
    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'
    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'
    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'
    RateLimitExceeded_2:
      description: 'Too Many Requests - Rate limit exceeded.


        **Action required:** Check the `Retry-After` header for when to retry.


        Also returned when the same rejected API key (`401 invalid_api_key` or `402 org_closed`)

        is retried 10 or more times within 10 minutes. The key is paused for 15 minutes, then

        1 hour, then 24 hours if retries continue. Fix the key or resubscribe instead of retrying.


        **Headers returned:**

        - `Retry-After`: Seconds until you can retry

        - `RateLimit-Limit`: Your limit per minute

        - `RateLimit-Remaining`: Remaining requests this minute

        - `RateLimit-Reset`: Seconds until limit resets

        '
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per minute
        RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests this minute
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until limit resets
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/RateLimitExceededError_2'
  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