> For the complete documentation index, see [llms.txt](https://fluid-crm.gitbook.io/fluid-crm-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fluid-crm.gitbook.io/fluid-crm-docs/features/api-and-webhooks.md). # API & Webhooks Connect Fluid to any tool that speaks HTTP. Cold email platforms, lead capture tools, automation services, internal scripts, ops dashboards. The API is workspace-level and intended for integrations, not daily manual use. ### What you can build with the Fluid API Common use cases include: * Creating deals automatically from form submissions on your website * Pushing booked meetings into Fluid as new deals * Auto-creating deals from positive replies in cold email tools (Smartlead, Instantly) * Updating deal stages based on external events (payment received, contract signed) * Syncing pipeline data with internal dashboards or BI tools * Building internal tools that read from or write to Fluid The API exists to remove repetitive work and keep Fluid as the execution layer in your stack. Compatible with any platform that supports HTTP requests: * Make.com * n8n * Zapier * Pabbly * Booking and scheduling tools * Outbound and cold email platforms * Marketing automation tools * Internal tools and custom scripts ### API endpoints The Fluid API covers the full data model. Six objects with full read and write, plus lead ingestion and three reference endpoints. **Objects** Each supports GET (list, or `?id=` for one), POST (create), PATCH `?id=` (update) and DELETE `?id=`: * `/api-contacts` * `/api-companies` * `/api-deals` * `/api-activities` * `/api-reminders` * `/api-labels` (GET, POST and DELETE. POST and DELETE attach or remove labels on a deal or contact) **POST /api-ingest** Creates a deal and auto-creates or updates the contact by email. Built for cold email replies and form submissions. Accepts: * `stage_id` (required) * Contact: name and email required, plus company, phone, website, social * Deal: title, value, label, source, expected close date, notes, next action * Custom field values * An external source and id, so the same lead never creates a duplicate deal **Reference endpoints** * `GET /api-pipelines`: all active pipelines in your workspace * `GET /api-stages`: all stages, with an optional `?pipeline_id=` filter. Use a stage id as `stage_id` when creating deals * `GET /api-custom-fields`: custom field definitions. Pass `?entity_type=deal`, `contact` or `organization` **Limits and conventions** * Reads: 300 per minute per key * Writes: 60 per minute per key * Lead ingestion: 60 per minute per key * List endpoints use cursor pagination, 50 per page by default, 200 max Full request and response examples are in the [API reference](https://fluidcrm.io/api-docs). ### Authentication All API requests use Bearer token authentication. * Generate API keys from Settings, then Automations, then API * Pass the key in the Authorization header on every request * Format: `Authorization: Bearer YOUR_API_KEY` ### API keys From the API settings page you can: * Create a new API key * View existing keys * See when each key was created * See when each key was last used * Delete keys that are no longer needed Important security rules: * An API key is shown only once at creation * You must store the key securely * Lost keys cannot be recovered and must be regenerated * Anyone with the key has full API access for your workspace Treat API keys like passwords. ### Security best practices When using the Fluid API: * Store API keys in environment variables or secure vaults * Do not hard-code keys into client-side code or public repos * Rotate keys if you believe they are compromised * Delete unused keys regularly * Use separate keys for different integrations so you can revoke individually Fluid does not expose API keys again after creation to reduce risk. ### Webhooks Webhooks send real-time notifications to external services when deals or contacts change in Fluid. Use webhooks when you want external systems to react instantly to changes, instead of polling the API on a schedule. Common use cases: * Notify a Slack channel when a deal moves to "Won" * Trigger an onboarding workflow in another tool when a deal is created * Sync contact updates to your email marketing platform * Log deal events to your internal data warehouse * Trigger Make.com or Zapier flows on specific events ### Webhook events Fluid supports 16 webhook events across deals, contacts, companies, activities, reminders and forms. * **Deal events**: Created, Updated, Stage Changed, Won, Lost, Reopened, Deleted * **Contact events**: Created, Updated, Deleted * **Company events**: Created, Updated, Deleted * **Activity events**: Activity Created * **Reminder events**: Reminder Due * **Lead form events**: Form Submitted ### Setting up a webhook To create a webhook: * Go to Settings, then Automations, then Webhooks * Click Add Webhook * Enter the endpoint URL where Fluid should send events * (Optional) Add an Authorization Header token if your receiver requires it. Required by some services like Make.com * Select which events to subscribe to * Click Create Webhook After creation, Fluid begins sending HTTP POST requests to your endpoint when the subscribed events fire. ### Webhook payload Each delivery includes: * The event name * A timestamp * A unique delivery id * Your workspace id * The full record for the affected deal, contact or company * Any custom field values on that record * The previous stage, on stage change events Every delivery is signed. Fluid sends an HMAC signature in the `X-Fluid-Signature` header so you can confirm the request came from Fluid and not from someone who guessed your URL. Sample verification code is in the API reference. Respond with HTTP 200 quickly to acknowledge. ### **Delivery and retries** A failed delivery (network error or 5xx) is retried up to 3 times with backoff. The same delivery id is reused, so make your handler idempotent on it. 4xx responses are not retried. A webhook is auto-disabled after a 404, or after three straight 403 or 410 responses. ### Authorization header for webhooks If your receiver requires an auth token (Make.com requires this for some workflow types), enter the token value in the Authorization Header field when setting up the webhook. Fluid will include it as `Authorization: YOUR_TOKEN` on every delivery to that endpoint. This protects your receiver from accepting unsolicited requests. ### Managing webhooks From the Webhooks tab you can: * View all configured webhooks * See which events each subscribes to * Edit endpoint URL, auth header or event subscriptions * Pause a webhook temporarily * Delete a webhook permanently ### What API & Webhooks do not do The API and webhooks: * Do not replace the UI for daily work * Do not provide reporting or analytics dashboards * Do not automatically sync data without your automation logic * Do not include a built-in marketplace of pre-built integrations The API and webhooks are building blocks, not a full integration platform by itself. You build the integration logic in your tool of choice (Make.com, Zapier, n8n, custom code). ### Why this matters Most CRMs at Fluid's price point either: * Do not have an API at all * Hide the API behind the enterprise plan * Charge per-call or per-integration fees Fluid puts the full API on every account, documents the endpoints publicly and includes webhooks at no extra cost. Build what you need without an upgrade conversation. ### What to read next * Lead forms, embeddable forms that auto-create deals via the API * Customize data fields, configure custom fields that the API can write to * Customize pipeline, structure stages before automating --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://fluid-crm.gitbook.io/fluid-crm-docs/features/api-and-webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.