Silent bulk import

Add an existing list to your audience without the signup pipeline, the same operation as the dashboard's CSV upload, callable from code. It reuses that exact pipeline underneath (ProcessAudienceImport → chunked loader → finalize), so behavior matches the dashboard exactly: deduplication against the audience, referral graph stitching, custom fields, and a downloadable report of anything rejected.

This is silent, not a signup. Nobody on the list receives an email. There is no signup.created event, and none of these contacts enroll in an automation. When the whole run finishes, one audience.imported event fires, never a per-row event.

Scope#

Both verbs sit under imports:write, there is no separate read scope. A key that may bulk-write the audience this way may also poll what it just queued.

Create an import#

POST /v1/imports

Queues the import and returns immediately. status starts at processing; poll GET /v1/imports/{import} for the outcome.

The contact input#

Every row needs an identity: email, phone, or identifier + identifier_type (email or phone, the importer has no other identity kinds, so identifier_type: username is refused).

Subscription in a file#

status is your answer for the whole list. A row can carry its own consent instead, which wins for that row:

People who already exist are left as they are, including their subscription, even with duplicates: update. To let a file change it, also send update_subscription: true. Then, for rows that have a consent:

• subscribed subscribes a contact who is not subscribed, and lifts an unsubscribe a teammate made.
• unsubscribed unsubscribes them.
• unconfirmed does nothing. A file never moves someone back to not subscribed.
• A person who unsubscribed themselves, marked an email as spam, bounced or is blocked stays as they are. They are counted in subscription_kept_count.

Check an import#

GET /v1/imports/{import}

Returns the current counts and, once completed, up to 100 rejected rows parsed as { row, identifier, reason } plus a report_url: a signed link to the full reject CSV, valid for 15 minutes. row is the row's 1-based position in the contacts array you sent.

{
    "object": "import",
    "id": "imp_9phm4rtx2kqd",
    "project": "prj_7Qk2mN4pR8",
    "status": "completed",
    "row_count": 2,
    "imported_count": 1,
    "updated_count": 0,
    "skipped_count": 0,
    "invalid_count": 1,
    "error": null,
    "rejected": [
        { "row": 2, "identifier": "not-an-email", "reason": "Invalid email address" }
    ],
    "report_url": "https://…/imports/…-report.csv?signature=…",
    "completed_at": "2026-09-24T09:25:47+00:00",
    "created_at": "2026-09-24T09:24:11+00:00"
}

Deliberately never reports anything about deliverability. This endpoint only ever answers with the same validation/dedupe reasons the dashboard's own failure report shows (an invalid identity, an unrecognized stage, "already in your audience").

List imports#

GET /v1/imports

Cursor-paginated (pagination), newest first. Requires a project query parameter, imports are listed one project at a time.

curl "https://api.getlaunchlist.com/v1/imports?project=prj_7Qk2mN4pR8&limit=25" \
  -H "Authorization: Bearer llk_live_8xKq3Rp9Wm2Nz7Vt6yL1cG5dH0jA4sE8uNqB2fXk"

Rate limit#

POST /v1/imports carries its own limiter on top of the per-workspace throttle:api budget: a handful a minute, and a modest hourly cap. One call materializes a CSV and dispatches the whole chunked import pipeline, nowhere near the cost the request-rate limit is sized for.

The import object#

Errors#

Next#

• MCP server: import_contacts and get_import do the same thing for an agent, with a lower per-call cap and a required status (an agent must ask the founder about consent rather than default to one answer)
• Webhooks: subscribe to audience.imported instead of polling
• Create a contact: the signup pipeline, for a person actually signing up right now rather than an existing list