API reference

Check a key

GET /api/whoami

Answers with the workspace the key belongs to and how the request authenticated. Touches no data, so it is the safe way to confirm a key works before wiring anything to it.

Request

curl https://luminnaleads.com.ng/api/whoami \
  -H "Authorization: Bearer lum_..."

Response

{
  "tenantId": "0e2c…",
  "authenticatedVia": "api_key"
}

List leads

GET /api/leads

Newest first. Without filters this returns the most recent 200; the ceiling is 1000 per call.

Request

curl "https://luminnaleads.com.ng/api/leads?status=valid&limit=50" \
  -H "Authorization: Bearer lum_..."

Response

[
  {
    "id": "…",
    "fullName": "Ada Okafor",
    "email": "ada@acme.com",
    "title": "Head of Operations",
    "emailStatus": "valid",
    "companyName": "Acme Ltd",
    "companyDomain": "acme.com",
    "listId": "…",
    "createdAt": "2026-09-21T09:12:00.000Z"
  }
]

Add a lead

POST /api/leads

Creates one lead and files it in the warehouse at the same time, under the company its address belongs to. An address that already exists answers 409 rather than merging quietly.

Request

curl -X POST https://luminnaleads.com.ng/api/leads \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@acme.com","firstName":"Ada","title":"Head of Operations","companyName":"Acme Ltd","country":"NG"}'

Response

{ "id": "…", "email": "ada@acme.com", "fullName": "Ada" }

List lists

GET /api/lead-lists

Newest first, each with how many leads it holds.

Request

curl https://luminnaleads.com.ng/api/lead-lists \
  -H "Authorization: Bearer lum_..."

Response

[
  { "id": "…", "name": "Apify Master List", "notes": null, "count": 6129 }
]

Create a list

POST /api/lead-lists

Returns 201 with the new list.

Request

curl -X POST https://luminnaleads.com.ng/api/lead-lists \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Nigeria — agencies"}'

Response

{ "id": "…", "name": "Nigeria — agencies" }

Search the warehouse

GET /api/warehouse/search

Returns a page of rows and, when asked, counts for every filter dimension. Paginate with the cursor rather than an offset: a cursor costs the same on page 500 as on page 1.

Request

curl "https://luminnaleads.com.ng/api/warehouse/search?mode=contact&country=NG&emailStatus=valid&limit=50&facets=0" \
  -H "Authorization: Bearer lum_..."

Response

{
  "rows": [ { "id": "…", "fullName": "Ada Okafor", "title": "Director", "email": "ada@acme.com", "companyName": "Acme Ltd" } ],
  "total": 23176,
  "nextCursor": "eyJ…",
  "facets": { "country": [ { "value": "NG", "count": 412 } ] }
}

Upload a file

POST /api/warehouse/imports/upload

Multipart. Reads the header and a sample, and answers with a batch id and a suggested column mapping. Nothing is written to the warehouse yet.

Request

curl -X POST https://luminnaleads.com.ng/api/warehouse/imports/upload \
  -H "Authorization: Bearer lum_..." \
  -F "file=@leads.csv"

Response

{ "batchId": "…", "headers": ["Name","Email"], "mapping": { "Email": "contact_email" } }

Start the import

POST /api/warehouse/imports/{batchId}/start

Runs the batch with the mapping you confirm. At least one of company_name, domain or website_url must be mapped — rows need something to identify the business by. Duplicates are merged, not doubled: a company matches on domain, a person on their address.

Request

curl -X POST https://luminnaleads.com.ng/api/warehouse/imports/BATCH_ID/start \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"mapping":{"Email":"contact_email","Company":"company_name"},"listName":"March import"}'

Response

{ "batchId": "…", "jobId": "…" }

List campaigns

GET /api/campaigns

Every campaign in the workspace with its steps, most recently updated first.

Request

curl https://luminnaleads.com.ng/api/campaigns \
  -H "Authorization: Bearer lum_..."

Response

[
  { "id": "…", "name": "Q4 agencies", "status": "active", "dailyCap": 80, "steps": [ { "order": 0, "type": "email", "subject": "…" } ] }
]

Get a campaign

GET /api/campaigns/{id}

One campaign with its steps.

Request

curl https://luminnaleads.com.ng/api/campaigns/CAMPAIGN_ID \
  -H "Authorization: Bearer lum_..."

Campaign stats

GET /api/campaigns/{id}/stats

Sends, opens, clicks and replies for one campaign.

Request

curl https://luminnaleads.com.ng/api/campaigns/CAMPAIGN_ID/stats \
  -H "Authorization: Bearer lum_..."

Deliverability read

GET /api/campaigns/{id}/analysis

The same analysis the dashboard shows: what is helping or hurting this campaign’s delivery.

Request

curl https://luminnaleads.com.ng/api/campaigns/CAMPAIGN_ID/analysis \
  -H "Authorization: Bearer lum_..."

Create a campaign

POST /api/campaigns

Creates it as a draft. It does not send — see the note on launching below.

Request

curl -X POST https://luminnaleads.com.ng/api/campaigns \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Q4 agencies","dailyCap":80,"sendWindowStart":"09:00","sendWindowEnd":"17:00","sendWindowTimezone":"Africa/Lagos"}'

Delete a campaign

DELETE /api/campaigns/{id}

Removes the campaign and everything recorded against it — its steps, its enrolled recipients and their send history. There is no undo and no archive: if you only want it to stop, pause it instead.

Request

curl -X DELETE https://luminnaleads.com.ng/api/campaigns/CAMPAIGN_ID \
  -H "Authorization: Bearer lum_..."

Response

{ "ok": true }

Launch a campaign

POST /api/campaigns/{id}/launch

Starts the campaign sending.

Not available with an API key. A key lives in a script, a CI config and a shell history, and one leaking should not include the ability to start mailing a workspace’s entire list from its own domain. Launch from the dashboard instead.

Request

# Sign in to the dashboard and press Launch.

List templates

GET /api/email-templates

Newest first.

Request

curl https://luminnaleads.com.ng/api/email-templates \
  -H "Authorization: Bearer lum_..."

Response

[ { "id": "…", "name": "Agency intro", "subject": "quick question, {{first_name}}", "body": "…" } ]

Create a template

POST /api/email-templates

Bodies take the same variables the editor offers, so a template written here renders identically to one written in the dashboard: {{first_name}}, {{company}}, {{title}}, {{first_line}}. A variable with no value renders empty, so give it a fallback — {{title|there}}.

Request

curl -X POST https://luminnaleads.com.ng/api/email-templates \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Agency intro","subject":"quick question, {{first_name}}","body":"Hi {{first_name}} — saw {{company}} …"}'

Delete a template

DELETE /api/email-templates/{id}

Removes the template. Campaign steps already written from it keep their own copy of the wording — a step holds text, not a reference — so deleting one changes nothing that is already scheduled or sent.

Request

curl -X DELETE https://luminnaleads.com.ng/api/email-templates/TEMPLATE_ID \
  -H "Authorization: Bearer lum_..."

Response

{ "ok": true }

List pipelines

GET /api/pipelines

Each pipeline with its stages and the cards on them.

Request

curl https://luminnaleads.com.ng/api/pipelines \
  -H "Authorization: Bearer lum_..."

Response

[ { "id": "…", "name": "Cold outreach", "stages": [ { "name": "Enrolled", "cards": [] } ] } ]

Pipeline templates

GET /api/pipelines/templates

The starting layouts a new pipeline can be created from.

Request

curl https://luminnaleads.com.ng/api/pipelines/templates \
  -H "Authorization: Bearer lum_..."

Create a pipeline

POST /api/pipelines

From a template, and optionally bound to a campaign so its cards follow that campaign’s leads.

Request

curl -X POST https://luminnaleads.com.ng/api/pipelines \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Cold outreach","template":"cold-outreach"}'

Delete a pipeline

DELETE /api/pipelines/{id}

Removes the board, its stages and every card on it. The leads themselves are untouched — a card is a position, not the person — so deleting a board loses where everyone stood, not who they are.

Request

curl -X DELETE https://luminnaleads.com.ng/api/pipelines/PIPELINE_ID \
  -H "Authorization: Bearer lum_..."

Response

{ "ok": true }

List ICPs

GET /api/icps

Every saved ideal-customer profile.

Request

curl https://luminnaleads.com.ng/api/icps \
  -H "Authorization: Bearer lum_..."

Create an ICP

POST /api/icps

All fields optional except the name.

Request

curl -X POST https://luminnaleads.com.ng/api/icps \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"NG agencies","industry":"Marketing","companySize":"11-50","geography":"Nigeria"}'

Update an ICP

PATCH /api/icps/{id}

Same fields as creation. 404 when the id is not in this workspace.

Request

curl -X PATCH https://luminnaleads.com.ng/api/icps/ICP_ID \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"geography":"Nigeria and Ghana"}'

Delete an ICP

DELETE /api/icps/{id}

Removes the profile. Offers pointing at it are kept and unlinked rather than deleted with it — the response says how many — because an offer is a thing you sell and survives the audience definition it was written for.

Request

curl -X DELETE https://luminnaleads.com.ng/api/icps/ICP_ID \
  -H "Authorization: Bearer lum_..."

Response

{ "ok": true, "unlinkedOffers": 2 }

List offers

GET /api/offers

Every saved offer.

Request

curl https://luminnaleads.com.ng/api/offers \
  -H "Authorization: Bearer lum_..."

Create an offer

POST /api/offers

What you are selling, to which ICP, and how the email asks for the meeting.

Request

curl -X POST https://luminnaleads.com.ng/api/offers \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Warmup audit","whatItIs":"A 20-minute deliverability review","ctaText":"Worth a look?"}'

Update an offer

PATCH /api/offers/{id}

Same fields as creation. 404 when the id is not in this workspace.

Request

curl -X PATCH https://luminnaleads.com.ng/api/offers/OFFER_ID \
  -H "Authorization: Bearer lum_..." \
  -H "Content-Type: application/json" \
  -d '{"price":"₦250,000"}'

Delete an offer

DELETE /api/offers/{id}

Removes the offer. The ICP it was aimed at is left alone, and campaigns already written against it keep their copy.

Request

curl -X DELETE https://luminnaleads.com.ng/api/offers/OFFER_ID \
  -H "Authorization: Bearer lum_..."

Response

{ "ok": true }