Bulk enrichment and retrieval
Research many email addresses, phone numbers or other fields through one typed batch endpoint.
enrichment.start accepts 1–100 independent items per request through POST /api/v1/operations/enrichment.start. MCP clients use enrichment_start with the same arguments. Each item supplies a unique id, known facts in input, a question and a typed output. Questions and output types may differ within a batch.
The response contains batchId and jobs; acceptance does not mean the jobs are finished or every item found an answer. Keep your record ID in the item ID so answers can be joined back to your source. If data starts as CSV, your application or AI client can map its rows to items without an app import.
Request work emails and direct phones together
This example submits four items: an email request and a phone request for each of two people. Replace CONTACT_ONE and CONTACT_TWO with the actual professional profiles you intend to research, configure LEADBASE_API_KEY in your shell and choose a stable key for this batch. Running it starts potentially billable research.
Email and phone outputs are arrays of returned values. An empty array is not a delivered contact. Two items per person allow separate question, status and cost reporting: a batch can hold 50 people with both fields, or 100 people with one field each. To submit more, split into further batches with distinct keys and IDs. Each scalar input value may be a string, number, boolean or null; include relevant known names, company and domain when available.
Leadbase handles identity research and source selection within the same batch workflow. See contact details for the identifiers and questions that help produce useful results.
Retrieve the same batch
Replace the placeholder with the returned UUID. In MCP, call enrichment_get with that same batchId. The response returns jobs with jobId, itemId, status, result, errorCode, billingStatus and credits. Successful findings are in result.value, with explanation in result.summary and sources in result.sources.
Poll with a reasonable interval and backoff while jobs are queued or running. Execution is terminal at completed, failed or cancelled. A completed job with an empty email or phone array has not delivered that contact. Check each job independently and continue checking billing when it is pending or reconciliation_pending. Report final costs only after settlement; credits: null means unknown, not zero.
Enrich contacts already in a sheet
For saved rows, call sheets_enrich in MCP or POST /api/v1/operations/sheets.enrich through HTTP. Use column: {"columnId":"COLUMN_UUID"} for a configured column, or column: {"name":"Work email","question":"Find this person's work email.","type":"email"} for a new one. The full request also needs sheetId and idempotencyKey. Supply rowIds for a subset; omit them only for a request covering all existing rows, up to 10,000. Existing values and active cells are skipped.
Email and phone are separate columns and separate requests with separate retry keys. Use sheets_get_enrichment_status and sheets_query to inspect progress, saved values and evidence. The corresponding HTTP operations use dotted names. This sheet workflow has its own target limits; the 100-item limit above applies to enrichment.start.
Recover without creating new paid work
Save the exact start payload and idempotencyKey before dispatch. If the response is lost, recover with the identical payload and same key. Do not generate a fresh key for recovery. A new question, input or intentionally new batch needs a new key.
Stay within the 1 MiB JSON body limit and increase volume according to observed throughput and cost. Batch size, request rate and execution concurrency are different limits; submitting 100 items does not promise they all start together. See Activity and Credits.