Preflight Enrichment
POST /enrichment/preflight
Check an enrichment request before running it. Free: nothing is written, queued or charged.
Errors for input a run could never use: an unknown mode (400
invalid_mode), zero or negative contact IDs (400 invalid_record_ids), a
list that is not in this organization (404 list_not_found), an unknown
target_field (400 unsupported_field), an unknown provider (400
unsupported_provider / unsupported_provider_for_field) and a missing AI
config (404 ai_config_not_found).
Otherwise returns what the run would do: the unique contact IDs (repeats are counted once), contacts that are not on the list, the providers that would run, and plain warnings such as “Lusha is not connected: add your key” or “No providers chosen: using your saved pipeline”.
Authorizations
Parameters
Header Parameters
Request Body required
Check an enrichment request before running it. Free: nothing is written, queued or charged.
Takes the same inputs as the MCP g8_enrich_contacts tool so a preview can
say up front whether the run would work.
object
Contact IDs to enrich (duplicates are counted once)
Add ZeroBounce email verification
List ID the contacts belong to
‘auto’ (AI when ai_group_id is set, else waterfall), ‘waterfall’ or ‘ai-research’
Responses
200
Successful Response
object
What a run with these inputs would do. Errors (unknown list, mode, field or provider, impossible contact IDs) come back as 400/404 instead.
object
Number of unique contacts (the count credits are estimated on)
Contact IDs that will be enriched: duplicates removed, order kept
How many repeated contact IDs were dropped
Providers whose step would be skipped because the org has no key for them
Resolved mode: ‘waterfall’ or ‘ai-research’
Contact IDs that are not on the list; the run skips them and does not charge for them
Providers that would run, in order (empty = the saved pipeline)
Per-step credential breakdown so callers can see, before running, which steps use graph8 system keys (charge credits) vs the org’s own BYOK key, and whether the required credential is actually present.
object
True if the step can actually run: system steps are always ready; BYOK steps are ready only when the org has an active key for that provider.
‘system’ = graph8-funded; ‘byok’ = org’s own key.
True = uses graph8-managed system key (charges credits). False = uses org BYOK key.
True when the list’s saved pipeline (or the graph8 default) would run
Plain-language advisories for the user
object
Whether there are more pages
Items per page
Current page number (1-indexed)
Total number of items
422
Validation Error