Nidaflow

API

Introduction

The Nidaflow REST API is a small, stable surface over the same engine the app uses — find companies, enrich contacts, and read your saved lists. Every paid call spends your workspace credits, success-only: a lookup that returns nothing costs nothing.

Just want working code?

Grab a key in Settings → Developers and jump straight to Search companies.

Base URL

https://app.nidaflow.com/api/v1

Authentication

Authenticate every request with a Bearer API key in the Authorization header. Create and revoke keys in Settings → Developers. A key is shown once — store it safely. Keys are scoped to your workspace and spend its shared credit pool.

Authorization: Bearer ndf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate limits

Requests are limited to 120 per minute per key. Exceeding it returns 429. See Errors for the full list.

Credits & pricing

Paid endpoints spend credits on success only. Each response echoes charged_credits so you can reconcile spend.

Action	Cost	Endpoint
Company / people search	1 / result	POST /search/companies · /search/people
Email found	2 / email	POST /enrich/contacts
Phone found	25 / phone	POST /enrich/contacts
Find posts (run)	5 / run	POST /clients/{id}/find-posts
Enroll into sequence	2 / new contact	POST /sequences/{id}/enroll
Read endpoints	Free	GET /credits, /clients, /runs, /lists …

Endpoints

GET/creditsFree

Your workspace's current credit balance, monthly allowance, plan, and the per-action price list.

curl https://app.nidaflow.com/api/v1/credits \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY"

{
  "balance": 1982,
  "allowance": 2000,
  "plan": "starter",
  "costs": { "lead_result": 1, "email_found": 2, "phone_found": 25 }
}

POST/search/companies1 credit / result

Relevance-ranked company search from a natural-language query. count is 1–100 (default 25). Charges 1 credit per company returned — nothing on zero results.

curl https://app.nidaflow.com/api/v1/search/companies \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "marketing agencies in Dubai", "count": 3 }'

{
  "count": 3,
  "charged_credits": 3,
  "results": [
    {
      "name": "GPS Marketing Agency",
      "url": "https://gpsmarketing.agency/",
      "location": "Dubai",
      "industry": "",
      "linkedin_url": ""
    }
  ]
}

POST/search/people1 credit / result

Relevance-ranked prospect search. Returns profile fields (name, title, company, LinkedIn) — pass results to /enrich/contacts to resolve emails. Charges 1 credit per person returned.

curl https://app.nidaflow.com/api/v1/search/people \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "heads of growth at B2B SaaS in London", "count": 5 }'

{
  "count": 2,
  "charged_credits": 2,
  "results": [
    { "name": "Aboo Backer", "title": "Head of Growth",
      "company_name": "Metabolic", "linkedin_url": "" }
  ]
}

POST/enrich/contacts2 / email · 25 / phone

Find a work email (and optionally direct phone) for up to 50 contacts. Provide your own idper contact — it's the key in the results map. Charges only for hits.

curl https://app.nidaflow.com/api/v1/enrich/contacts \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contacts": [{ "id": "1", "first": "Jane", "last": "Doe", "domain": "acme.com" }], "email": true }'

{
  "emails_found": 1,
  "phones_found": 0,
  "charged_credits": 2,
  "results": {
    "1": {
      "email": "jane@acme.com",
      "email_status": "verified",
      "personal_email": "",
      "phone": ""
    }
  }
}

Post-finding

Add a client (an offer profile), trigger a run, and the engine finds LinkedIn posts worth engaging and drafts a comment for each. Runs are async — trigger, then poll the run for its found posts.

GET/clientsFree

Your discovery clients (offer profiles) and their status.

curl https://app.nidaflow.com/api/v1/clients \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY"

[
  { "id": "ab24...", "name": "Acme Engagement Engine",
    "status": "active", "is_active": true }
]

POST/clients/{client_id}/find-posts5 credits / run

Kick off a background run that finds posts and drafts comments for this client. Charges 5 credits. Then poll /clients/{id}/runs for status and /runs/{run_id}/posts for the drafted comments.

curl -X POST https://app.nidaflow.com/api/v1/clients/ab24.../find-posts \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY"

{ "status": "started", "client_id": "ab24..." }

GET/clients/{client_id}/runsFree

Recent runs for a client, newest first. Poll until status is shipped or aborted.

curl https://app.nidaflow.com/api/v1/clients/ab24.../runs \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY"

[
  { "id": "a926...", "status": "shipped", "kept_count": 22,
    "target": 30, "floor": 20, "stats": { "scanned": 535 } }
]

GET/runs/{run_id}/postsFree

The found posts + drafted comments for a run, with each post's score, tier, and gate status.

curl https://app.nidaflow.com/api/v1/runs/a926.../posts \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY"

[
  {
    "author_name": "Darek Kociecki",
    "company": "",
    "post_url": "https://www.linkedin.com/feed/update/...",
    "comment_text": "Establishing a local entity after a decade...",
    "comment_language": "en",
    "score": 9, "tier": "A",
    "gate_status": "passed", "review_status": "pending"
  }
]

Sequences

Enroll contacts into an email + LinkedIn sequence and read its analytics. Sends go out through your own connected accounts.

GET/sequencesFree

Your sequences (excluding templates), with enrolled counts.

curl https://app.nidaflow.com/api/v1/sequences \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY"

[
  { "id": "906f...", "name": "Q3 outbound",
    "status": "active", "enrolled": 128 }
]

POST/sequences/{sequence_id}/enroll2 / new contact

Add contacts to a sequence. Pass a stable ref per contact to make enroll idempotent — duplicates are skipped free. Charges 2 credits per newly enrolled contact.

curl https://app.nidaflow.com/api/v1/sequences/906.../enroll \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contacts": [{ "name": "Jane Doe", "email": "jane@acme.com", "ref": "crm-42" }] }'

{ "enrolled": 1, "skipped": 0, "charged_credits": 2 }

GET/sequences/{sequence_id}/analyticsFree

Enrollment analytics for a sequence.

curl https://app.nidaflow.com/api/v1/sequences/906.../analytics \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY"

{
  "enrolled": 128, "pending": 40, "completed": 80, "stopped": 8,
  "sent": 0, "opened": 0, "replied": 0
}

GET/listsFree

Your saved lists (from searches, imports, and enrichments), newest first.

curl https://app.nidaflow.com/api/v1/lists \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY"

[
  {
    "id": "9f3c...",
    "title": "Marketing agencies in Casablanca",
    "kind": "companies",
    "count": 686
  }
]

GET/lists/{list_id}Free

Full people + companies for one saved list.

curl https://app.nidaflow.com/api/v1/lists/9f3c... \
  -H "Authorization: Bearer $NIDAFLOW_API_KEY"

{
  "id": "9f3c...",
  "title": "Marketing agencies in Casablanca",
  "people": [],
  "companies": [
    { "name": "Leyton Maroc", "url": "leyton.com" }
  ]
}

Errors

Errors use standard HTTP status codes with a JSON detail message.

401	Missing, malformed, or revoked API key.
402	Out of credits for the current month.
404	Resource not found (e.g. unknown list id).
422	Invalid request body / parameters.
429	Rate limit exceeded (120 / min per key).

SDKs & tools

There's no dedicated SDK yet — the API is plain REST + JSON, so any HTTP client works (the examples above cover cURL, Python, and JavaScript). Need a language binding or an MCP server for your AI agent? Tell us.

Ready to build?

Create a key and make your first call in under a minute.

Get an API key

Introduction

Just want working code?

Grab a key in Settings → Developers and jump straight to Search companies.

Base URL

https://app.nidaflow.com/api/v1

Authentication

Authorization: Bearer ndf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Credits & pricing

Paid endpoints spend credits on success only. Each response echoes charged_credits so you can reconcile spend.

Action	Cost	Endpoint
Company / people search	1 / result	POST /search/companies · /search/people
Email found	2 / email	POST /enrich/contacts
Phone found	25 / phone	POST /enrich/contacts
Find posts (run)	5 / run	POST /clients/{id}/find-posts
Enroll into sequence	2 / new contact	POST /sequences/{id}/enroll
Read endpoints	Free	GET /credits, /clients, /runs, /lists …

curl https://app.nidaflow.com/api/v1/search/companies \ -H "Authorization: Bearer $NIDAFLOW_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "marketing agencies in Dubai", "count": 3 }'

{ "count": 3, "charged_credits": 3, "results": [ { "name": "GPS Marketing Agency", "url": "https://gpsmarketing.agency/", "location": "Dubai", "industry": "", "linkedin_url": "" } ] }

curl https://app.nidaflow.com/api/v1/search/people \ -H "Authorization: Bearer $NIDAFLOW_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "heads of growth at B2B SaaS in London", "count": 5 }'

curl https://app.nidaflow.com/api/v1/enrich/contacts \ -H "Authorization: Bearer $NIDAFLOW_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contacts": [{ "id": "1", "first": "Jane", "last": "Doe", "domain": "acme.com" }], "email": true }'

{ "emails_found": 1, "phones_found": 0, "charged_credits": 2, "results": { "1": { "email": "jane@acme.com", "email_status": "verified", "personal_email": "", "phone": "" } } }

[ { "author_name": "Darek Kociecki", "company": "", "post_url": "https://www.linkedin.com/feed/update/...", "comment_text": "Establishing a local entity after a decade...", "comment_language": "en", "score": 9, "tier": "A", "gate_status": "passed", "review_status": "pending" } ]

curl https://app.nidaflow.com/api/v1/sequences/906.../enroll \ -H "Authorization: Bearer $NIDAFLOW_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contacts": [{ "name": "Jane Doe", "email": "jane@acme.com", "ref": "crm-42" }] }'