Start an enrichment job

POST

/api/v1/enrich-csv

• Production

Cost: Per lead, by the fields you request — the response explains the charge

Multipart upload. Every row needs a website/domain or an email; name/title/company columns are detected. Credits for all requested cells are held up front (standard fields 1/cell, custom_* 2/cell, full_email free); empty cells are refunded when the job settles. Copy is written from the company website; rows whose site could not be read are marked in “Website Read” and left blank.

Try it

curl https://app.leadsonar.io/api/v1/enrich-csv \
  -H "X-API-Key: $LS_KEY" \
  -F "file=@leads.csv" \
  -F "fields=icp_grading,icp" \
  -F "target_icp=Agencies and B2B companies that run cold email outreach and need sending infrastructure"

Authorizations

• ApiKeyAuth

Request Body ^required

object

file

required

.csv file

string format: binary

fields

required

Comma-separated field ids. Allowed: opener, icp_grading, icp, subject_lines, full_email, custom_simplified_job_title, custom_who_they_work_with, custom_recent_professional_achievement, custom_subject_line, custom_personalized_opener, custom_ps_line, custom_two_liner, custom_got_me_thinking, custom_full_email_v1, custom_full_email_v2, custom_company_type, custom_buyer_personas

string

Example

icp_grading,icp,opener,subject_lines

target_icp

Who you sell to (1-2 sentences). Required with icp_grading.

string

<= 500 characters

seller_offer

What you sell; used to write copy.

string

<= 500 characters

user_tag

Your own label, echoed on the job.

string

Example

{
  "file": "(binary) leads.csv",
  "fields": "icp_grading,icp",
  "target_icp": "Agencies and B2B companies that run cold email outreach and need sending infrastructure"
}

Responses

201

Job created

object

id

string format: uuid

status

string

total_rows

integer

credits_charged

number

Example

{
  "id": "540894a7-8fb6-44b6-91ba-d0a56a8f5c11",
  "backend_job_id": "ec-de1bef6b7c",
  "status": "queued",
  "total_rows": 2,
  "fields": ["icp_grading", "icp"],
  "target_icp": "Agencies and B2B companies that run cold email outreach and need sending infrastructure",
  "seller_offer_set": false,
  "user_tag": null,
  "credits_charged": 4,
  "cost_explained": "2 rows × 2 enrichment types = 4 credits",
  "estimated_seconds": 5,
  "created_at": "2026-10-06T10:30:37.328Z",
  "poll_url": "/api/v1/enrich-csv/jobs/540894a7-8fb6-44b6-91ba-d0a56a8f5c11",
  "download_url_when_done": "/api/v1/enrich-csv/jobs/540894a7-8fb6-44b6-91ba-d0a56a8f5c11/csv"
}

400

Invalid fields, missing target_icp, or rows without website/email (response lists the row numbers)

401

Missing or invalid API key

402

Insufficient credits; nothing charged

502

AI service unavailable; hold refunded