REST API v1

API Documentation

Build powerful integrations with the LeadForm REST API. Manage forms, retrieve entries, configure webhooks, and automate your lead collection workflow programmatically.

Authentication

The LeadForm API uses Bearer token authentication. Include your API key in the Authorization header of every request. All API requests must be made over HTTPS. Calls made over plain HTTP will be rejected.

Your API Key
your-api-key-here
Log in or create an account to see your real API key.
Example Request Header 
Authorization: Bearer your-api-key-here
Content-Type:  application/json
Accept:        application/json
ℹ
Base URL: All API endpoints are relative to https://flow.profluxus.com/api/v1/

Forms

Forms are the core resource in LeadForm. Use these endpoints to create, read, update, and delete forms, as well as retrieve their entries.

GET /api/v1/forms

Returns a paginated list of all forms belonging to your account. Results are ordered by creation date (newest first).

Query Parameters
NameTypeRequiredDescription
page integer optional Page number for pagination. Default: 1
per_page integer optional Items per page (1-100). Default: 20
status string optional Filter by status: active, draft, archived
search string optional Search forms by name
Example Request 
curl -X GET https://flow.profluxus.com/api/v1/forms?page=1&per_page=10 \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Accept: application/json"
Example Response 200 OK 
{
  "data": [
    {
      "id": 1,
      "name": "Contact Form",
      "slug": "contact-form",
      "status": "active",
      "entries_count": 342,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-02-01T14:22:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 24,
    "last_page": 3
  }
}
POST /api/v1/forms

Creates a new form. The form will be in draft status by default.

Body Parameters
NameTypeRequiredDescription
name string required Form name (max 255 characters)
description string optional Form description for internal reference
fields array optional Array of field objects defining the form structure
settings object optional Form settings (notifications, redirect URL, theme, etc.)
status string optional draft or active. Default: draft
Example Request 
curl -X POST https://flow.profluxus.com/api/v1/forms \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Signup",
    "description": "Collect email subscribers",
    "fields": [
      {
        "type": "email",
        "label": "Your Email",
        "required": true,
        "placeholder": "[email protected]"
      },
      {
        "type": "text",
        "label": "Full Name",
        "required": true
      }
    ],
    "settings": {
      "redirect_url": "https://example.com/thank-you",
      "notification_email": "[email protected]"
    },
    "status": "active"
  }'
Example Response 201 Created 
{
  "data": {
    "id": 25,
    "name": "Newsletter Signup",
    "slug": "newsletter-signup",
    "status": "active",
    "fields": [
      {
        "id": "fld_a1b2c3",
        "type": "email",
        "label": "Your Email",
        "required": true,
        "placeholder": "[email protected]"
      },
      {
        "id": "fld_d4e5f6",
        "type": "text",
        "label": "Full Name",
        "required": true
      }
    ],
    "settings": {
      "redirect_url": "https://example.com/thank-you",
      "notification_email": "[email protected]"
    },
    "public_url": "https://flow.profluxus.com/f/newsletter-signup",
    "entries_count": 0,
    "created_at": "2025-03-10T09:15:00Z",
    "updated_at": "2025-03-10T09:15:00Z"
  }
}
GET /api/v1/forms/{id}

Retrieves the full details for a single form, including its fields and settings.

Path Parameters
NameTypeRequiredDescription
id integer required The form ID
Example Request 
curl -X GET https://flow.profluxus.com/api/v1/forms/25 \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Accept: application/json"
Example Response 200 OK 
{
  "data": {
    "id": 25,
    "name": "Newsletter Signup",
    "slug": "newsletter-signup",
    "status": "active",
    "fields": [ /* ... field objects ... */ ],
    "settings": { /* ... settings object ... */ },
    "public_url": "https://flow.profluxus.com/f/newsletter-signup",
    "entries_count": 142,
    "created_at": "2025-03-10T09:15:00Z",
    "updated_at": "2025-03-12T16:40:00Z"
  }
}
PUT /api/v1/forms/{id}

Updates an existing form. Only the fields you include in the request body will be updated; omitted fields remain unchanged.

Path Parameters
NameTypeRequiredDescription
id integer required The form ID
Body Parameters
NameTypeRequiredDescription
name string optional Updated form name
description string optional Updated description
fields array optional Replace entire fields array
settings object optional Merge with existing settings
status string optional draft, active, or archived
Example Request 
curl -X PUT https://flow.profluxus.com/api/v1/forms/25 \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Signup v2",
    "status": "active"
  }'
Example Response 200 OK 
{
  "data": {
    "id": 25,
    "name": "Newsletter Signup v2",
    "slug": "newsletter-signup",
    "status": "active",
    "updated_at": "2025-03-15T11:20:00Z"
  }
}
DELETE /api/v1/forms/{id}

Permanently deletes a form and all its associated entries. This action cannot be undone.

Path Parameters
NameTypeRequiredDescription
id integer required The form ID
⚠
Destructive action. Deleting a form also permanently removes all of its entries. Consider archiving the form instead by setting status to archived.
Example Request 
curl -X DELETE https://flow.profluxus.com/api/v1/forms/25 \
  -H "Authorization: Bearer your-api-key-here"
Example Response 200 OK 
{
  "message": "Form deleted successfully."
}
GET /api/v1/forms/{id}/entries

Returns a paginated list of entries (submissions) for a specific form.

Path Parameters
NameTypeRequiredDescription
id integer required The form ID
Query Parameters
NameTypeRequiredDescription
page integer optional Page number. Default: 1
per_page integer optional Items per page (1-100). Default: 20
since string optional ISO 8601 date. Return entries created after this date.
until string optional ISO 8601 date. Return entries created before this date.
Example Request 
curl -X GET https://flow.profluxus.com/api/v1/forms/25/entries?per_page=5 \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Accept: application/json"
Example Response 200 OK 
{
  "data": [
    {
      "id": 1087,
      "form_id": 25,
      "fields": {
        "email": "[email protected]",
        "full_name": "Jane Doe"
      },
      "metadata": {
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0...",
        "referrer": "https://example.com/blog"
      },
      "created_at": "2025-03-14T08:22:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 5,
    "total": 142,
    "last_page": 29
  }
}

Entries

Entries represent individual form submissions. Use these endpoints to retrieve, create, or delete submission data.

GET /api/v1/entries/{id}

Retrieves the full details of a single entry, including all submitted field data and metadata.

Path Parameters
NameTypeRequiredDescription
id integer required The entry ID
Example Request 
curl -X GET https://flow.profluxus.com/api/v1/entries/1087 \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Accept: application/json"
Example Response 200 OK 
{
  "data": {
    "id": 1087,
    "form_id": 25,
    "form_name": "Newsletter Signup",
    "fields": {
      "email": "[email protected]",
      "full_name": "Jane Doe"
    },
    "metadata": {
      "ip": "203.0.113.42",
      "user_agent": "Mozilla/5.0...",
      "referrer": "https://example.com/blog",
      "country": "BR"
    },
    "is_complete": true,
    "created_at": "2025-03-14T08:22:00Z"
  }
}
POST /api/v1/entries

Programmatically creates a new entry for a specified form. Useful for importing data from external sources or building custom submission flows.

Body Parameters
NameTypeRequiredDescription
form_id integer required The target form ID
fields object required Key-value pairs of field data (use field labels or IDs as keys)
metadata object optional Custom metadata (IP, source, UTM tags, etc.)
Example Request 
curl -X POST https://flow.profluxus.com/api/v1/entries \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": 25,
    "fields": {
      "email": "[email protected]",
      "full_name": "John Smith"
    },
    "metadata": {
      "source": "csv_import",
      "utm_campaign": "spring_2025"
    }
  }'
Example Response 201 Created 
{
  "data": {
    "id": 1088,
    "form_id": 25,
    "fields": {
      "email": "[email protected]",
      "full_name": "John Smith"
    },
    "metadata": {
      "source": "csv_import",
      "utm_campaign": "spring_2025"
    },
    "is_complete": true,
    "created_at": "2025-03-15T12:00:00Z"
  }
}
DELETE /api/v1/entries/{id}

Permanently deletes an entry. This action cannot be undone.

Path Parameters
NameTypeRequiredDescription
id integer required The entry ID
Example Request 
curl -X DELETE https://flow.profluxus.com/api/v1/entries/1087 \
  -H "Authorization: Bearer your-api-key-here"
Example Response 200 OK 
{
  "message": "Entry deleted successfully."
}

Webhooks

Webhooks allow you to receive real-time HTTP POST notifications when events occur in your account, such as new form submissions. Configure target URLs and choose which events to subscribe to.

GET /api/v1/webhooks

Returns all webhooks configured for your account.

Example Request 
curl -X GET https://flow.profluxus.com/api/v1/webhooks \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Accept: application/json"
Example Response 200 OK 
{
  "data": [
    {
      "id": 12,
      "url": "https://example.com/hooks/leadform",
      "events": ["entry.created", "entry.updated"],
      "form_id": null,
      "is_active": true,
      "secret": "whsec_a1b2c3d4e5...",
      "created_at": "2025-02-20T10:00:00Z"
    }
  ]
}
POST /api/v1/webhooks

Creates a new webhook subscription. You can scope a webhook to a specific form or listen to events across all forms.

Body Parameters
NameTypeRequiredDescription
url string required The HTTPS endpoint URL that will receive webhook payloads
events array required Events to subscribe to: entry.created, entry.updated, entry.deleted, form.updated
form_id integer optional Scope webhook to a specific form. Omit for all forms.
secret string optional A signing secret for verifying payloads. Auto-generated if omitted.
Example Request 
curl -X POST https://flow.profluxus.com/api/v1/webhooks \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/leadform",
    "events": ["entry.created"],
    "form_id": 25
  }'
Example Response 201 Created 
{
  "data": {
    "id": 13,
    "url": "https://example.com/hooks/leadform",
    "events": ["entry.created"],
    "form_id": 25,
    "is_active": true,
    "secret": "whsec_x9y8z7w6v5...",
    "created_at": "2025-03-15T14:30:00Z"
  }
}
PUT /api/v1/webhooks/{id}

Updates an existing webhook configuration. You can change the target URL, events, scope, or active status.

Path Parameters
NameTypeRequiredDescription
id integer required The webhook ID
Body Parameters
NameTypeRequiredDescription
url string optional Updated webhook endpoint URL
events array optional Updated list of events
is_active boolean optional Enable or disable the webhook
Example Request 
curl -X PUT https://flow.profluxus.com/api/v1/webhooks/13 \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["entry.created", "entry.deleted"],
    "is_active": true
  }'
Example Response 200 OK 
{
  "data": {
    "id": 13,
    "url": "https://example.com/hooks/leadform",
    "events": ["entry.created", "entry.deleted"],
    "form_id": 25,
    "is_active": true,
    "updated_at": "2025-03-15T15:10:00Z"
  }
}
DELETE /api/v1/webhooks/{id}

Deletes a webhook subscription. The endpoint will no longer receive event payloads.

Path Parameters
NameTypeRequiredDescription
id integer required The webhook ID
Example Request 
curl -X DELETE https://flow.profluxus.com/api/v1/webhooks/13 \
  -H "Authorization: Bearer your-api-key-here"
Example Response 200 OK 
{
  "message": "Webhook deleted successfully."
}

Account

Retrieve information about your account, subscription plan, and current usage statistics.

GET /api/v1/account

Returns your account details, including plan information and limits.

Example Request 
curl -X GET https://flow.profluxus.com/api/v1/account \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Accept: application/json"
Example Response 200 OK 
{
  "data": {
    "id": 42,
    "name": "Acme Corp",
    "email": "[email protected]",
    "plan": {
      "name": "Pro",
      "forms_limit": -1,
      "entries_limit": 10000,
      "api_access": true
    },
    "created_at": "2024-11-05T08:00:00Z"
  }
}
GET /api/v1/account/usage

Returns your current billing cycle usage, including form count, entry count, and API call statistics.

Query Parameters
NameTypeRequiredDescription
period string optional Usage period: current (default), previous, or ISO month 2025-03
Example Request 
curl -X GET https://flow.profluxus.com/api/v1/account/usage?period=current \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Accept: application/json"
Example Response 200 OK 
{
  "data": {
    "period": "2025-03",
    "forms": {
      "used": 12,
      "limit": -1
    },
    "entries": {
      "used": 4832,
      "limit": 10000
    },
    "api_calls": {
      "used": 12450,
      "limit": 100000
    },
    "storage_mb": {
      "used": 245,
      "limit": 5000
    }
  }
}

Rate Limiting

The API enforces rate limits to ensure fair usage and service stability. You can make up to 100 requests per minute per API key. Rate limit information is included in every response via HTTP headers.

ℹ
When you exceed the rate limit, the API responds with a 429 Too Many Requests status code. Wait until the X-RateLimit-Reset timestamp before retrying.
Header Description Example
X-RateLimit-Limit Maximum requests allowed per window 100
X-RateLimit-Remaining Requests remaining in the current window 87
X-RateLimit-Reset Unix timestamp when the window resets 1710500460
Retry-After Seconds to wait (only on 429 responses) 23
Rate Limit Exceeded Response 429 Too Many Requests 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 23 seconds.",
    "retry_after": 23
  }
}

Error Codes

The API uses standard HTTP status codes and returns consistent JSON error responses. Every error includes a machine-readable code and a human-readable message.

Standard Error Format 
{
  "error": {
    "code": "resource_not_found",
    "message": "The requested form was not found.",
    "details": {} // optional, additional context
  }
}
Status Code Description
200 - Request succeeded.
201 - Resource created successfully.
400 bad_request The request body is malformed or contains invalid JSON.
401 unauthorized Missing or invalid API key. Check the Authorization header.
403 forbidden Your plan does not include API access, or you lack permission for this resource.
404 resource_not_found The requested resource does not exist.
422 validation_error The request body failed validation. Check the details field for specifics.
429 rate_limit_exceeded Too many requests. Wait and retry after the Retry-After period.
500 internal_error An unexpected server error occurred. Contact support if it persists.
503 service_unavailable The API is temporarily unavailable for maintenance.
ℹ
For 422 validation errors, the details object contains field-level error messages:
Validation Error Example 422 Unprocessable Entity 
{
  "error": {
    "code": "validation_error",
    "message": "The given data failed validation.",
    "details": {
      "name": ["The name field is required."],
      "fields.0.type": ["The selected type is invalid."]
    }
  }
}
DEV
Erro