Skip to content
FlowNurture
Start free
Home/API Documentation

REST API Reference

Manage contacts, tags, workflows, segments, and enrollments programmatically. All endpoints use API key authentication and are scoped to your organization.

Base URL: https://api.flownurture.com/api/v1Version: v1

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. API keys are scoped to your organization — every request is automatically filtered to your data.

Request header
Authorization: Bearer fn_your_api_key_here

API keys start with the fn_ prefix. Create and manage keys from Settings > API Keys in the FlowNurture dashboard.

API Keys

Each API key has one or more scopes that control what it can access. Only assign the scopes your integration needs.

ScopePermission
contacts:readList and retrieve contacts
contacts:writeCreate and update contacts
tags:writeAdd and remove tags from contacts
workflows:readList and retrieve workflows
segments:readList and retrieve segments
enrollments:writeEnroll contacts in workflows

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with a message field.

Error response
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}
CodeMeaning
200Success
201Created
400Bad request — invalid parameters or body
401Unauthorized — missing or invalid API key
403Forbidden — insufficient scope or access
404Not found — resource doesn't exist in your organization
409Conflict — duplicate record (e.g. contact email already exists)
429Too many requests — rate limit exceeded
500Internal server error

Rate Limits

API requests are rate-limited to protect service stability. Current limits:

  • 60 requests per minute per API key
  • Exceeding the limit returns 429 Too Many Requests
  • Retry after the Retry-After header value (in seconds)

Contacts

GET/api/v1/contactsScope: contacts:read

List all contacts in your organization. Supports pagination and search.

Query parameters:

  • page — Page number (default: 1)
  • limit — Items per page (default: 25, max: 100)
  • search — Filter by name or email
Example request
curl -H "Authorization: Bearer fn_your_key" \
  "https://api.flownurture.com/api/v1/contacts?page=1&limit=10"
Response
[
  {
    "id": "clx1abc...",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "Acme Inc",
    "lifecycleStage": "LEAD",
    "createdAt": "2026-03-15T10:00:00.000Z"
  }
]
GET/api/v1/contacts/:idScope: contacts:read

Retrieve a single contact by ID.

Example request
curl -H "Authorization: Bearer fn_your_key" \
  "https://api.flownurture.com/api/v1/contacts/clx1abc..."
POST/api/v1/contactsScope: contacts:write

Create a new contact. Email is required and must be unique within your organization.

Request body
{
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Smith",
  "company": "Acme Inc",
  "jobTitle": "Marketing Manager",
  "lifecycleStage": "LEAD"
}

Lifecycle stages: SUBSCRIBER LEAD MQL SQL CUSTOMER

PATCH/api/v1/contacts/:idScope: contacts:write

Update an existing contact. Only include the fields you want to change.

Request body
{
  "company": "New Company",
  "lifecycleStage": "MQL"
}

Tags

POST/api/v1/contacts/:contactId/tags/addScope: tags:write

Add a tag to a contact. If the tag is already applied, this is a no-op.

Request body
{
  "tagId": "clx2def..."
}
Response
{ "success": true }
POST/api/v1/contacts/:contactId/tags/removeScope: tags:write

Remove a tag from a contact.

Request body
{
  "tagId": "clx2def..."
}
Response
{ "success": true }

Workflows

GET/api/v1/workflowsScope: workflows:read

List all workflows in your organization with step and enrollment counts.

Response
[
  {
    "id": "clx3ghi...",
    "name": "Welcome Sequence",
    "status": "ACTIVE",
    "createdAt": "2026-03-10T08:00:00.000Z",
    "_count": { "steps": 5, "enrollments": 142 }
  }
]
GET/api/v1/workflows/:idScope: workflows:read

Retrieve a single workflow with all its steps.

Response
{
  "id": "clx3ghi...",
  "name": "Welcome Sequence",
  "status": "ACTIVE",
  "steps": [
    { "id": "...", "type": "SEND_EMAIL", "order": 0 },
    { "id": "...", "type": "DELAY", "order": 1, "delayAmount": 2, "delayUnit": "DAYS" },
    { "id": "...", "type": "SEND_EMAIL", "order": 2 }
  ]
}

Segments

GET/api/v1/segmentsScope: segments:read

List all segments in your organization.

Response
[
  {
    "id": "clx4jkl...",
    "name": "High-intent leads",
    "createdAt": "2026-03-20T12:00:00.000Z"
  }
]
GET/api/v1/segments/:idScope: segments:read

Retrieve a single segment with its groups and rules.

Enrollments

POST/api/v1/enrollmentsScope: enrollments:write

Enroll a contact in an active workflow. The contact will begin receiving the workflow steps immediately.

Requirements:

  • Workflow must have status ACTIVE
  • Workflow must have at least one step
  • Contact must not already be actively enrolled in the same workflow
Request body
{
  "contactId": "clx1abc...",
  "workflowId": "clx3ghi..."
}
Response
{
  "id": "clx5mno...",
  "contactId": "clx1abc...",
  "workflowId": "clx3ghi...",
  "status": "ACTIVE",
  "createdAt": "2026-04-09T14:00:00.000Z"
}

Ready to integrate?

Create your API key from Settings > API Keys in the FlowNurture dashboard and start building.