leadmagic-io Batch API
Campaign-oriented batch enrichment with budgets, clients, suppression lists, and webhooks
Campaign-oriented batch enrichment with budgets, clients, suppression lists, and webhooks
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/leadmagic-io:leadmagic-io-batch-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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