Flow9 API guide

Getting Started

Base URL

https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api

All endpoints are versioned under /v1.

Building an integration? Start with objects.md. GET /v1/objects and GET /v1/objects/{object}/schema let you discover the available entities and their fields at runtime, including fields the tenant has added or disabled — so you do not have to hard-code a field list that a customer can invalidate. Then see records.md for reading and writing those records, and webhooks.md for receiving events in real time.

Authentication

Every request (except the public endpoints /v1/health, /v1/onboarding and /v1/availability) must carry a credential — an API key in the x-api-key header, or an OAuth 2.1 access token as Authorization: Bearer <jwt> (see auth.md):

x-api-key: f9_live_your_key_here

Keys are f9_live_… (real data) or f9_test_… (sandbox — see test-mode.md). API keys are created in Settings > API Keys within the CRM dashboard, or headlessly via POST /v1/api-keys. Each key has:

Scopes that control which endpoints it can access
Rate limits (per minute and per hour — see rate-limits.md)
Optional IP allowlist (supports CIDR notation)
Optional expiration date

Request Format

All request bodies must be valid JSON with Content-Type: application/json
Maximum request body size: 100 KB
Maximum JSON nesting depth: 5 levels
Maximum keys per JSON object: 100

Response Format

All responses use a consistent envelope: Success:

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-02-15T10:00:00.000Z",
    "rate_limit": {
      "limit": 60,
      "remaining": 58,
      "reset": 1718400060000
    }
  }
}

Error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "fields": {
        "first_name": "First name is required"
      }
    }
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-02-15T10:00:00.000Z"
  }
}

Response Headers

Every response includes:

Header	Description
`X-Request-Id`	Unique request identifier for support inquiries
`X-RateLimit-Limit`	Maximum requests per minute for this key
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp (ms) when the window resets
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`Strict-Transport-Security`	HSTS header

On 429 responses, Retry-After is also included (seconds to wait).

Rate Limiting

Rate limits are enforced per API key at two windows:

Window	Default	Scope
Per minute	60	Per endpoint
Per hour	1,000	Global per key

Both windows use a sliding window algorithm. If either is exceeded, you’ll receive a 429 response.

Handling 429 Responses

const response = await fetch(url, options);
if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  // Retry the request
}

Best Practices

Respect Retry-After headers — don’t retry immediately
Monitor X-RateLimit-Remaining to pace your requests
Use exponential backoff for retries
Batch operations where possible instead of individual calls

Endpoints

Health Check

Check if the API is operational. No authentication required.

GET /v1/health

Response:

{
  "success": true,
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "timestamp": "2026-02-15T10:00:00.000Z"
  }
}

Onboard Company

Create a new company with an admin user and default configuration.

POST /v1/onboard

Required scope: onboarding Request body:

Field	Type	Required	Description
`company.name`	string	Yes	Company name (2-200 chars)
`company.email`	string	Yes	Company email
`company.phone`	string	No	Phone number
`company.website`	string	No	Website URL
`company.address`	string	No	Street address
`company.city`	string	No	City
`company.state`	string	No	State/province
`company.country`	string	No	Country
`company.postal_code`	string	No	Postal code
`admin_user.email`	string	Yes	Admin email
`admin_user.full_name`	string	Yes	Admin name (2+ chars)
`admin_user.password`	string	No	Password (8+ chars). Auto-generated if omitted.
`region`	string	Yes	`middle_east`, `europe`, or `america`
`industry`	string	Yes	Industry name (2-100 chars, e.g. `travel`, `real-estate`, `hospitality`)
`send_welcome_email`	boolean	No	Send welcome email (default: `true`)
`metadata`	object	No	Arbitrary metadata stored on user record

Example:

curl -X POST \
  'https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api/v1/onboard' \
  -H 'x-api-key: f9_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "company": {
      "name": "Acme Travel",
      "email": "info@acmetravel.com",
      "city": "Dubai",
      "country": "UAE"
    },
    "admin_user": {
      "email": "admin@acmetravel.com",
      "full_name": "John Smith"
    },
    "region": "middle_east",
    "industry": "travel"
  }'

What gets created:

Company record with active status
Default branch (“Main Branch”)
Auth user (with auto-generated password if not provided)
User record linked to company and branch
Company_Admin role assignment
6 default deal statuses (New, Contacted, Qualified, Proposal, Won, Lost)
5 default lead statuses (New, Contacted, Qualified, Converted, Disqualified)
10 default activity types (Call, Email, Meeting, Note, Task, LinkedIn, WhatsApp, SMS, Postal Mail, Other)
Welcome email (unless send_welcome_email: false)
Audit log entry

Rollback: If user creation fails, the company is automatically deleted.

Get Customer by ID

Retrieve a customer profile with optional related data.

GET /v1/customers/:id?include=contacts,deals_count

Required scope: customers:read Path parameters:

Parameter	Type	Description
`id`	UUID	Customer ID

Query parameters:

Parameter	Type	Default	Description
`include`	string	`contacts`	Comma-separated: `contacts`, `deals_count`, `leads_count`, `activities_count`, `custom_fields`

Example:

curl 'https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api/v1/customers/550e8400-e29b-41d4-a716-446655440000?include=contacts,deals_count,custom_fields' \
  -H 'x-api-key: f9_live_your_key_here'

Lookup Customer by Email

Find a customer by their email address.

GET /v1/customers?email=sarah@example.com

Required scope: customers:read Query parameters:

Parameter	Type	Required	Description
`email`	string	Yes	Customer email to search

Example:

curl 'https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api/v1/customers?email=sarah@example.com' \
  -H 'x-api-key: f9_live_your_key_here'

Create Lead

Create a new lead with optional assignment, tags, and custom fields.

POST /v1/leads

Required scope: leads:write Request body:

Field	Type	Required	Description
`first_name`	string	Yes	First name (1-100 chars)
`last_name`	string	No	Last name
`email`	string	Conditional	At least one of `email` or `mobile` required
`mobile`	string	Conditional	At least one of `email` or `mobile` required
`inquiry_details`	string	No	Inquiry details (max 5000 chars)
`notes`	string	No	Notes (max 5000 chars)
`source`	string	No	Lead source name (resolved against configured sources)
`priority`	integer	No	1 (highest) to 4 (lowest), default: 3
`origin`	string	No	Lead origin
`assigned_to_email`	string	No	Email of assignee (must be active company user)
`lead_status`	string	No	Status name (resolved against configured statuses, defaults to first)
`custom_fields`	object	No	Key-value custom fields
`tags`	string[]	No	Array of tag names
`metadata`	object	No	Arbitrary metadata (stored in audit log)

Example:

curl -X POST \
  'https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api/v1/leads' \
  -H 'x-api-key: f9_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "Sarah",
    "last_name": "Connor",
    "email": "sarah@example.com",
    "mobile": "+971501234567",
    "inquiry_details": "Interested in Maldives package",
    "source": "website",
    "priority": 2,
    "lead_status": "New",
    "tags": ["vip", "corporate"]
  }'

Notes:

If the company has duplicate detection enabled, a 409 is returned when a lead with the same email exists
The lead_status and source fields are resolved by name (case-insensitive) against the company’s configured values
If assigned_to_email is omitted, the lead is assigned to the first active company user

Create Activity

Log a new activity against a deal or lead.

POST /v1/activities

Required scope: activities:write Request body:

Field	Type	Required	Description
`entity_type`	string	Yes	`deal` or `lead`
`entity_id`	UUID	Yes	ID of the deal or lead
`activity_type`	string	Yes	Must match configured type (e.g. `call`, `email`, `meeting`)
`summary`	string	Yes	Activity summary (1-500 chars)
`details`	string	No	Extended details (max 10,000 chars)
`performed_by_email`	string	No	Performer’s email (defaults to first active user)
`performed_at`	ISO 8601	No	When it occurred (defaults to now, cannot be future)
`followup_at`	ISO 8601	No	Scheduled follow-up (must be in the future)
`metadata`	object	No	Arbitrary metadata

Example:

curl -X POST \
  'https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api/v1/activities' \
  -H 'x-api-key: f9_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "deal",
    "entity_id": "550e8400-e29b-41d4-a716-446655440000",
    "activity_type": "call",
    "summary": "Discussed pricing for Maldives package",
    "details": "Client interested in 5-night stay at Soneva Fushi",
    "followup_at": "2026-02-20T14:00:00.000Z"
  }'

Side effects:

Updates the entity’s last_contacted_at
Updates next_followup_at if followup_at is provided
Triggers SLA tracking update
Creates audit log entry

Update Activity

Update an existing activity.

PATCH /v1/activities/:id?entity_type=deal

Required scope: activities:update Path parameters:

Parameter	Type	Description
`id`	UUID	Activity ID

Query parameters:

Parameter	Type	Required	Description
`entity_type`	string	Yes*	`deal` or `lead` (*can also be in body)

Updatable fields: summary, details, activity_type, followup_at, performed_at At least one field must be provided. Example:

curl -X PATCH \
  'https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api/v1/activities/550e8400-e29b-41d4-a716-446655440000?entity_type=deal' \
  -H 'x-api-key: f9_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "summary": "Updated: client confirmed interest",
    "followup_at": "2026-02-22T10:00:00.000Z"
  }'

Notes:

Set followup_at to null to clear the scheduled follow-up
The activity must belong to an entity within your company

Error Code Reference

Code	HTTP Status	Description
`MISSING_API_KEY`	401	No `x-api-key` header provided
`AUTH_INVALID_KEY`	401	API key not found or invalid format
`API_KEY_EXPIRED`	403	API key has passed its expiration date
`API_KEY_REVOKED`	403	API key has been revoked
`FORBIDDEN_SCOPE`	403	API key doesn’t have the required scope
`IP_NOT_ALLOWED`	403	Client IP not in key’s allowlist
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`VALIDATION_ERROR`	400	Request body validation failed
`MISSING_REQUIRED_FIELD`	400	A required field is missing
`INVALID_FIELD_FORMAT`	400	A field has an invalid format
`VALIDATION_ERROR`	400	Request body is not valid JSON
`NOT_FOUND`	404	Requested resource not found
`ALREADY_EXISTS`	409	Resource already exists (duplicate)
`INTERNAL_ERROR`	500	Unexpected server error

Available Scopes

Scope	Endpoints
`onboarding`	`POST /v1/onboard`
`customers:read`	`GET /v1/customers/:id`, `GET /v1/customers?email=`
`leads:write`	`POST /v1/leads`
`activities:write`	`POST /v1/activities`
`activities:update`	`PATCH /v1/activities/:id`
`*`	All endpoints (wildcard)

Partial wildcards are also supported: leads:* matches leads:write and leads:read.

Changelog

v1.0.0 (2026-02-15)

Initial release
Endpoints: health, onboard, customers (by ID / by email), leads create, activities create/update
API key authentication with SHA-256 hashing
Multi-window rate limiting (per minute + per hour)
Input sanitization, security headers, IP allowlisting
Audit logging and abuse detection

Getting started

Working with data

Workspace administration

Communications & scheduling

Connect an application

Endpoints

Getting Started

Base URL

Authentication

Request Format

Response Format

Response Headers

Rate Limiting

Handling 429 Responses

Best Practices

Endpoints

Health Check

Onboard Company

Get Customer by ID

Lookup Customer by Email

Create Lead

Create Activity

Update Activity

Error Code Reference

Available Scopes

Changelog

v1.0.0 (2026-02-15)

​Getting Started

​Base URL

​Authentication

​Request Format

​Response Format

​Response Headers

​Rate Limiting

​Handling 429 Responses

​Best Practices

​Endpoints

​Health Check

​Onboard Company

​Get Customer by ID

​Lookup Customer by Email

​Create Lead

​Create Activity

​Update Activity

​Error Code Reference

​Available Scopes

​Changelog

​v1.0.0 (2026-02-15)

Getting Started

Base URL

Authentication

Request Format

Response Format

Response Headers

Rate Limiting

Handling 429 Responses

Best Practices

Endpoints

Health Check

Onboard Company

Get Customer by ID

Lookup Customer by Email

Create Lead

Create Activity

Update Activity

Error Code Reference

Available Scopes

Changelog

v1.0.0 (2026-02-15)