Documentazione API di Flusia

Returns the organization and the token's permissions. Any valid token can call it.

curl https://api.flusia.it/me -H "Authorization: Bearer flusia_your_token_here"

{
  "organization": { "id": "0b7c1e52-3f1a-4c55-9d1e-6a1f2b3c4d5e", "name": "Example Srl" },
  "token": {
    "id": "5d2f0c1a-8b7e-4c3d-9a10-2b3c4d5e6f70",
    "name": "My integration",
    "permissions": { "leads": { "read": true, "write": true, "delete": false } }
  },
  "authenticated": true
}

Same check on the API v1 host path. Response:

{
  "organization_id": "0b7c1e52-3f1a-4c55-9d1e-6a1f2b3c4d5e",
  "token_id": "5d2f0c1a-8b7e-4c3d-9a10-2b3c4d5e6f70",
  "permissions": { "leads": { "read": true, "write": true, "delete": false } }
}

Response: { "data": [ ... ] }. Unknown kinds return 404; a token without the permission listed below gets 403.

curl "https://api.flusia.it/crm/v1/lookups/stages?pipeline_id=7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" \
  -H "Authorization: Bearer flusia_your_token_here"

{
  "data": [
    { "id": "c3d4e5f6-0000-4000-8000-000000000001", "name": "New", "pipeline_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "pipeline_name": "Sales", "is_won": false, "is_lost": false },
    { "id": "c3d4e5f6-0000-4000-8000-000000000002", "name": "Won", "pipeline_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "pipeline_name": "Sales", "is_won": true, "is_lost": false }
  ]
}

Exact search by email and/or phone, for "find or create" flows. Email matching is case-insensitive. Phone matching compares the last 9 digits against both phone and whatsapp_number (at least 6 digits required). Returns up to 5 matches, email matches first, then most recently updated.

Query parameters

At least one is required, otherwise 400 {"error": "Provide email and/or phone"}. Response: { "data": [ lead, ... ] } (empty array when nothing matches).

curl "https://api.flusia.it/crm/v1/leads/find?email=mario.rossi%40example.com" \
  -H "Authorization: Bearer flusia_your_token_here"

Returns one lead or client in the public shape: { "data": lead }.

Adds tags to a lead or client, by tag id or by name (case-insensitive), without removing existing tags. Adding a tag starts the "tag added" automations configured in Flusia.

Body

If some tags do not exist (and create_missing is false, or an unknown id is given) the answer is 400 with error, missing (list) and a hint. On success: { "data": lead } with the updated tags.

curl -X POST https://api.flusia.it/crm/v1/leads/2f516d26-bc55-4e8e-a1d6-959bff44cffe/tags \
  -H "Authorization: Bearer flusia_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["VIP", "Trade fair 2026"], "create_missing": true}'

Removes one tag (id or name, URL-encoded) from the lead or client. Response: { "removed": true }, or { "removed": false } if the tag was not assigned.

Sets custom field values, addressed by field key or definition id (see the custom-fields lookup). Values are validated by type: number fields need a number, date fields a date (YYYY-MM-DD), select fields one of the allowed options (case-insensitive). Other types are stored as text; arrays are joined with commas. null or an empty string clears the value. Fields not listed are left unchanged.

Body

{ "values": { "budget": 1500, "sector": "Construction", "visit_date": "2026-11-03" } }

Unknown fields or invalid values return 400 with {"error": "Invalid custom fields", "details": "..."} and nothing is written. On success: { "data": lead }.

The latest 100 notes of the lead or client, newest first.

{
  "data": [
    {
      "id": "d4e5f6a7-0000-4000-8000-000000000040",
      "content": "Called back, interested in the premium plan",
      "created_at": "2026-10-18T09:12:00.000Z",
      "updated_at": "2026-10-18T09:12:00.000Z",
      "author_id": "9e8d7c6b-0000-4000-8000-000000000020",
      "author_name": "Anna Bianchi"
    }
  ]
}

Adds a note to the lead or client timeline. Body: { "content": "..." } (1 to 20,000 characters). Response 201:

{ "data": { "id": "d4e5f6a7-0000-4000-8000-000000000041", "content": "Sent brochure", "created_at": "2026-10-19T10:00:00.000Z" } }

The event catalog, with allowed telling whether this token has the permission needed to subscribe.

{
  "events": [
    { "event": "lead.created", "entity": "lead", "resource": "leads", "label": "New lead or client", "description": "A lead or client is created", "allowed": true }
  ]
}

Subscribes a URL to one event. The token needs read on the event's resource (see the table above).

Body

Response 201. The signing secret is returned only here: store it to verify signatures. An organization can have at most 200 active subscriptions (429 beyond that).

curl -X POST https://api.flusia.it/crm/v1/hooks \
  -H "Authorization: Bearer flusia_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"event": "lead.stage_changed", "target_url": "https://example.com/flusia-webhook"}'

{
  "id": "e5f6a7b8-0000-4000-8000-000000000050",
  "event": "lead.stage_changed",
  "target_url": "https://example.com/flusia-webhook",
  "source": null,
  "is_active": true,
  "created_at": "2026-10-19T10:00:00.000Z",
  "secret": "whsec_EXAMPLEexampleEXAMPLEexample00"
}

Lists the subscriptions created with this token (a token never sees subscriptions created by other tokens), newest first.

{
  "data": [
    {
      "id": "e5f6a7b8-0000-4000-8000-000000000050",
      "event": "lead.stage_changed",
      "target_url": "https://example.com/flusia-webhook",
      "source": null,
      "is_active": true,
      "consecutive_failures": 0,
      "disabled_reason": null,
      "last_delivery_at": "2026-10-19T10:05:12.000Z",
      "created_at": "2026-10-19T10:00:00.000Z"
    }
  ]
}

Deletes a subscription created with this token. Response: { "deleted": true, "id": "..." }; 404 if it does not exist or belongs to another token.

Returns the most recent records in exactly the payload shape of a webhook, to test an integration without waiting for a real event. Query: event (required), limit (1 to 25, default 3). The id of each sample is sample-<record id>.

curl "https://api.flusia.it/crm/v1/hooks/sample?event=deal.status_changed&limit=3" \
  -H "Authorization: Bearer flusia_your_token_here"

Lists leads and clients.

Query parameters

curl "https://api.flusia.it/api/api-leads?search=rossi&limit=20&sort_by=updated_at" \
  -H "Authorization: Bearer flusia_your_token_here"

{
  "data": [
    {
      "id": "2f516d26-bc55-4e8e-a1d6-959bff44cffe",
      "business_name": "Mario Rossi",
      "entity_type": "individual",
      "email": "mario.rossi@example.com",
      "phone": "+39 333 000 0000",
      "stato_cliente": "a1b2c3d4-0000-4000-8000-000000000010",
      "pipeline_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "pipeline_stage_id": "c3d4e5f6-0000-4000-8000-000000000001",
      "assigned_to": "9e8d7c6b-0000-4000-8000-000000000020",
      "lead_source": "Website",
      "opportunity_value": 2500,
      "created_at": "2026-10-15T08:30:00.000Z",
      "updated_at": "2026-10-18T14:02:11.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1 }
}

Returns one record with all its fields: { "data": { ... } }. 404 {"error": "Lead not found"} if it does not exist. For a version with readable pipeline, stage, state, owner, tags and custom fields use GET /crm/v1/leads/{id}.

Creates a lead. No field is strictly required. Response 201 with { "data": { ... } }. Creating a lead starts the "lead created" automations configured in Flusia, and an automatic owner is assigned when assigned_to is omitted and assignment rules exist.

Main body fields

Other fields of the lead record can be sent too (for example sales_rep_id, default_payment_method_id, operational_address); unknown fields are rejected. To set custom fields use PUT /crm/v1/leads/{id}/custom-fields.

Duplicates

With dedup_mode: "create_new" a new lead is always created. With dedup_mode: "update" Flusia first looks for an existing lead with the same email (case-insensitive) or, failing that, the same phone (last 9 digits of phone or whatsapp_number). If one is found, only its empty fields are filled in, the new tags and interests are added, a note with the submitted data is added to its timeline and its owner is notified. Owner, pipeline, stage, state, source, score and value are not changed. The answer is then 200 with "deduplicated": true:

{ "data": { "id": "2f516d26-bc55-4e8e-a1d6-959bff44cffe", "business_name": "Mario Rossi", "...": "..." }, "deduplicated": true }

curl -X POST https://api.flusia.it/api/api-leads \
  -H "Authorization: Bearer flusia_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Mario Rossi",
    "entity_type": "individual",
    "email": "mario.rossi@example.com",
    "phone": "+39 333 000 0000",
    "lead_source": "Website",
    "pipeline_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "selected_tags": ["f1e2d3c4-0000-4000-8000-000000000060"],
    "dedup_mode": "update"
  }'

Partial update with the same fields as create (except dedup_mode). Note that selected_tags, selected_interest_categories and contacts, when present, replace the current lists. Changing pipeline_stage_id or stato_cliente starts the "state changed" automations. Response: { "data": { ... } }; 404 if the record does not exist.

curl -X PUT https://api.flusia.it/api/api-leads/2f516d26-bc55-4e8e-a1d6-959bff44cffe \
  -H "Authorization: Bearer flusia_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"pipeline_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "pipeline_stage_id": "c3d4e5f6-0000-4000-8000-000000000002"}'

Permanently deletes the record. Response: { "message": "Lead deleted successfully" }; 404 if it does not exist.

Query parameters

Each item has all deal fields plus client ({ id, business_name, email, phone }), assigned_user ({ id, full_name, email }) and deal_services (service lines).

{
  "data": [
    {
      "id": "9b1c7a3e-1d2f-4f7a-8f1c-1a2b3c4d5e6f",
      "title": "Website redesign",
      "status": "sent",
      "amount": 4800,
      "closing_probability": 60,
      "client_id": "2f516d26-bc55-4e8e-a1d6-959bff44cffe",
      "assigned_to": "9e8d7c6b-0000-4000-8000-000000000020",
      "created_at": "2026-10-16T10:00:00.000Z",
      "client": { "id": "2f516d26-bc55-4e8e-a1d6-959bff44cffe", "business_name": "Mario Rossi", "email": "mario.rossi@example.com", "phone": "+39 333 000 0000" },
      "assigned_user": { "id": "9e8d7c6b-0000-4000-8000-000000000020", "full_name": "Anna Bianchi", "email": "anna@example.com" },
      "deal_services": [ { "service_id": "aa11bb22-0000-4000-8000-000000000070", "amount": 4800, "quantity": 1 } ]
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1, "total_pages": 1 }
}

One deal with client (including vat_number), assigned_user, payment_method ({ id, name, payment_type }) and deal_services, each with its service ({ id, title, description }). 404 {"error": "Deal not found"}.

Body

Response 201 { "data": { ..., "client": {...}, "deal_services": [...] } }. Unknown client_id: 400.

curl -X POST https://api.flusia.it/api/api-deals \
  -H "Authorization: Bearer flusia_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "2f516d26-bc55-4e8e-a1d6-959bff44cffe",
    "title": "Website redesign",
    "amount": 4800,
    "status": "draft",
    "services": [ { "service_id": "aa11bb22-0000-4000-8000-000000000070", "amount": 4800, "quantity": 1 } ]
  }'

Partial update with the same fields as create. When services is present it replaces all service lines (an empty array removes them). Response: { "data": { ... } }; 404 if the deal (or a new client_id) does not exist. To change only the status prefer the endpoint below.

Changes the status. Body: { "status": "accepted" }, one of draft, sent, accepted, rejected (otherwise 400). accepted and rejected also set closed_at. Response: { "data": { ... } }.

curl -X PATCH https://api.flusia.it/api/api-deals/9b1c7a3e-1d2f-4f7a-8f1c-1a2b3c4d5e6f/status \
  -H "Authorization: Bearer flusia_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted"}'

Deletes the deal and its service lines. Response: { "message": "Deal deleted successfully" }.

Newest first. Query: page, limit, and exact filters client_id, lead_id, deal_id, type, status, assigned_to.

Each item: id, title, description, type, status, due_date, client_id, deal_id, lead_id, user_id, assigned_to, outcome, completed_at, created_at, updated_at, plus client, lead ({ id, business_name, email }), deal ({ id, title }) and assignee ({ id, full_name, email }).

One sales task (client and lead include phone; deal includes status and amount). 404 {"error": "Activity not found"}.

Body

Only these fields are stored. A client_id, lead_id or deal_id outside your organization returns 404. Response 201 { "data": { ... } }.

curl -X POST https://api.flusia.it/api/api-activities \
  -H "Authorization: Bearer flusia_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Follow-up call",
    "type": "call",
    "due_date": "2026-10-21T09:00:00.000Z",
    "client_id": "2f516d26-bc55-4e8e-a1d6-959bff44cffe",
    "lead_id": "2f516d26-bc55-4e8e-a1d6-959bff44cffe"
  }'

{ "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "title": "Follow-up call", "type": "call", "status": "pending", "due_date": "2026-10-21T09:00:00+00:00", "...": "..." } }

Partial update of title, description, type, status, due_date, client_id, deal_id, lead_id, assigned_to, outcome. Response: { "data": { ... } }.

Response: { "message": "Activity deleted successfully" }.

Query parameters

Each item has all task fields plus project ({ id, name }), assigned_user, created_by_user ({ id, full_name, email }) and tags ([{ tag: { id, name, color } }]).

One task with project, assigned_user, created_by_user, comments, checklist and attachments. 404 {"error": "Task not found"}.

Body

Response 201 { "data": { ... } }.

curl -X POST https://api.flusia.it/api/api-tasks \
  -H "Authorization: Bearer flusia_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "eeeeeeee-0000-4000-8000-000000000001",
    "title": "Prepare kickoff meeting",
    "priority": "high",
    "due_date": "2026-10-24T16:00:00.000Z",
    "checklist": [ { "title": "Send agenda" }, { "title": "Book room", "is_required": true } ]
  }'

Partial update with the same fields as create, except checklist and tag_ids (use the sub-resources below). Moving to another project_id requires a project of your organization. Response: { "data": { ... } }.

Marks the task as completed (status completed, 100%, completed_at now). No body.

Moves the task. Body: { "order": 3, "section": "..." } (both optional).

Deletes the task with its comments, attachments and checklist. Response: { "message": "Task deleted successfully" }.

Comments, oldest first, each with created_by_user.

Body { "content": "..." } (required). Response 201.

Body { "content": "..." }. Only comments written by the token's user can be edited (403 otherwise); system comments cannot be edited.

Same ownership rule as edit.

Items ordered by sort_order: id, title, description, is_completed, is_required, sort_order, ...

Body: title (required, max 255), description, is_required (default false), sort_order (default last). Response 201.

Partial update of the item.

Body { "is_completed": true }: sets the item as done (with completion time and user) or not done.

Deletes the item.

Assigned tags: [{ id, name, color, sort_order, assignment_id, assigned_at }].

Body { "tag_ids": ["..."] }: adds tags of the task's project (see project tags); already assigned tags are skipped. Tags of other projects return 400 with invalid_tag_ids. Returns the assigned tags.

Removes the tag from the task.

Body { "project_id": "...", "tasks": [ { "title": "...", ... } ] }. Supported task fields: title, description, section, priority, assigned_to, due_date, start_date, status, order, is_header, recurrence fields, checklist, tag_ids. Items without a title are skipped. Response 201 (400 if nothing was created): { "data": [...], "summary": { "created": 2, "errors": [] } }.

Body { "updates": [ { "id": "...", "data": { "status": "in_progress" } } ] }. The project of a task cannot be changed here. Response 200: { "data": [...], "summary": { "updated": 1, "errors": [] } }; check summary.errors for items that failed.

Body { "ids": ["...", "..."] }. Response: { "message": "2 tasks deleted successfully", "summary": { "deleted": 2, "errors": [] } }.

Query parameters

Each item has all project fields plus client, deal, project_manager, project_assignments and latest_status_update.

One project with client, deal, project_manager, tasks, project_assignments, project_task_tags and latest_status_update. 404 {"error": "Project not found"}.

Body: name (required), description, client_id, deal_id, status, urgency, start_date, due_date, estimated_delivery_date, project_type, objectives (array), project_manager_id, assigned_user_ids (users added as members). Response 201 { "data": { ..., "project_assignments": [...] } }.

curl -X POST https://api.flusia.it/api/api-projects \
  -H "Authorization: Bearer flusia_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Website redesign", "client_id": "2f516d26-bc55-4e8e-a1d6-959bff44cffe", "status": "planning", "assigned_user_ids": ["9e8d7c6b-0000-4000-8000-000000000020"]}'

Partial update with the same fields. assigned_user_ids, when present, replaces the members.

Body { "status": "completed" } (one of the statuses above, otherwise 400). completed also sets completed_at.

Archives or restores the project. No body.

Response: { "message": "Project deleted successfully" }.

Members: [{ id, user_id, role, assigned_at, assigned_by, user: { id, full_name, email, profile_image_url } }].

Body { "user_id": "..." }. 404 if the user is not in the organization, 400 if already a member. Response 201.

Removes the member.

Tags ordered by sort_order.

Body: name and color (required, for example #2383E2), sort_order, is_active. Response 201.

Updates name, color, sort_order, is_active.

Deletes the tag and removes it from all tasks.

Health updates, newest first, each with creator.

Only the latest update (or null).

Body: health_status (required: on_track, at_risk, delayed), description, next_steps, completion_percentage. Response 201.

Documents and links of the project brief.

Body: name and url (required), document_type (link default, or file), visible_to_client (default false). Response 201.

Partial update.

Deletes the document entry.

Body { "name": "Design" }. Response 201 with the header row; its section field is the section key.

Body { "name": "..." }: renames the section.

Deletes the section; its tasks are kept without a section.

All pipelines (not paginated): id, name, description, color, is_default, is_active, sort_order, ... Query: include_stages=true to embed lead_pipeline_stages; sort_order asc (default) or desc.

{
  "data": [
    { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "name": "Sales", "color": "#2383E2", "is_default": true, "is_active": true, "sort_order": 0 }
  ]
}

One pipeline with its lead_pipeline_stages. 404 {"error": "Pipeline not found"}.

Body: name (required, max 100), description, color (hex, for example #6B7280), is_default, is_active, sort_order (default last). Stages are added separately. Response 201.

Partial update with the same fields.

Deletes the pipeline and its stages. It fails while leads are still in the pipeline: move them first.

Reorders all pipelines; {id} can be the id of any of your pipelines. Body { "pipelines": [ { "id": "...", "sort_order": 0 }, { "id": "...", "sort_order": 1 } ] }.

Stages of the pipeline ordered by sort_order: id, pipeline_id, name, description, color, sort_order, is_active, is_won, is_lost.

Body: name (required), description, color, sort_order (default last), is_won, is_lost (not both true), is_active. Response 201.

Partial update.

Body { "stages": [ { "id": "...", "sort_order": 0 } ] }.

Deletes the stage. It fails while leads are still in the stage.

Ordered by title. Query: page, limit, category_id, service_type, search (title or description). Each item has all service fields plus category ({ id, name, color }).

{
  "data": [
    { "id": "aa11bb22-0000-4000-8000-000000000070", "title": "Website", "description": "Corporate website", "list_price": 4800, "service_type": "one_time", "category": { "id": "bb22cc33-0000-4000-8000-000000000080", "name": "Web", "color": "#2383E2" } }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1, "total_pages": 1 }
}

One service. 404 {"error": "Service not found"}.

Body: title (required), description, short_description, list_price (number), service_type (one_time, monthly, annual), category_id, terms_and_conditions, auto_invoice, requires_manual_renewal, renewal_notice_days. Response 201.

Partial update.

Response: { "message": "Service deleted successfully" }.

Newest first. Query: page, limit, status, deal_id, client_id (invoices of that client's deals). Each item has all invoice fields plus deal ({ id, title, client_id }) and client.

One invoice with its deal and the deal's client ({ id, business_name, email, vat_number }). 404 {"error": "Invoice not found"}.

Newest first. Query: page, limit, task_id.

One document. 404 {"error": "Document not found"}.

Removes the document entry. Response: { "message": "Document deleted successfully" }.