Floweet API coverage simulations

On this page

Good to know
Example: from prospect to pitch
The SimulationSummary object
The Simulation object
The Pitch object
Coverage simulations of the organization, most recently updated first
Create a zone simulation: network coverage around a point for a client
A simulation: zone, coverage, competitors, client
Change the sales status or the name of a simulation
Write the sales pitch of a simulation (AI when available, otherwise a template)

A simulation measures your organization's network coverage around a client: how many of your network's stations lie within a given radius of its site, against competing networks. It then tracks the deal's sales status, and the API writes the sales pitch to hand to the client.

Good to know

Creating a simulation computes a zone's results right away: the organization's network stations within the radius (stationCount), the total listed (networkTotal), coverage (coveragePct) and a confidence level. A network absent from the zone gives 0% coverage.
The client is given by SIRET (companySiret, linked to the directory) or by name (companyName). The simulation is created for the API account's designated member, and shows up in the application.
Statuses: todo, progress, won, lost, archived; change them with PATCH. The API creates zone simulations; routes and multi-site simulations are prepared in the application.
The pitch is written by AI with an fw_live_ key, when AI is available and under the organization's daily cap; otherwise, and always with an fw_test_ key, it comes from the template. generator tells which. Each call replaces the pitch saved on the simulation.
Pitch texts use reduced Markdown (**bold**, ==highlight==, numbered lists), in the Accept-Language language.
These operations need the Simulation module in the organization's plan (see plans and AI).

Example: from prospect to pitch

Find the establishment in the directory, geocode its address with geocoding, create the simulation with its SIRET and those coordinates, then write the pitch. When the deal is signed, set the simulation to won.

The SimulationSummary object

Field	Type	Description
`id`always present	`string (uuid)`
`name`always present	`string`
`mode`always present	`"zone" \| "trajet" \| "multi"`
`status`always present	`"todo" \| "progress" \| "won" \| "lost" \| "archived"`
`confidence`always present	`"high" \| "med" \| "low"`
`coveragePct`always present	`number \| null`
`stationCount`always present	`number \| null`
`companyId`always present	`string (uuid) \| null`
`createdAt`always present	`string (date-time)`
`updatedAt`always present	`string (date-time)`

SimulationSummary

{
  "id": "ffffffff-0000-0000-0000-000000000001",
  "name": "Transports Bonin · Zone 50 km",
  "mode": "zone",
  "status": "todo",
  "confidence": "high",
  "coveragePct": 98,
  "stationCount": 30,
  "companyId": "cccccccc-0000-0000-0000-000000000001",
  "createdAt": "2026-07-06T09:24:53.171192+00:00",
  "updatedAt": "2026-07-09T22:05:45.68844+00:00"
}

The Simulation object

Field	Type	Description
`id`always present	`string (uuid)`
`name`always present	`string`
`mode`always present	`"zone" \| "trajet" \| "multi"`
`status`always present	`"todo" \| "progress" \| "won" \| "lost" \| "archived"`
`confidence`always present	`"high" \| "med" \| "low"`
`coveragePct`always present	`number \| null`
`stationCount`always present	`number \| null`
`companyId`always present	`string (uuid) \| null`
`createdAt`always present	`string (date-time)`
`updatedAt`always present	`string (date-time)`
`productId`always present	`string (uuid) \| null`
`zone`always present	`object \| null`
`zone.center`always present	`object`
`zone.center.label`always present	`string`
`zone.center.lat`always present	`number`
`zone.center.lng`always present	`number`
`zone.radiusKm`always present	`number`
`fuels`always present	`string[]`
`services`always present	`string[]`
`competitors`always present	`object[]`
`competitors[].name`always present	`string`
`competitors[].pct`always present	`number`
`competitors[].stations`always present	`number`
`networkTotal`always present	`number \| null`
`savingsPerMonth`always present	`integer \| null`	Estimated savings, cents per month.
`recommendation`always present	`string \| null`
`company`always present	`object \| null`
`company.id`always present	`string (uuid)`
`company.name`always present	`string`
`company.siret`always present	`string \| null`
`company.city`always present	`string \| null`

Simulation

{
  "id": "ffffffff-0000-0000-0000-000000000001",
  "name": "Transports Bonin · Zone 50 km",
  "mode": "zone",
  "status": "todo",
  "confidence": "high",
  "coveragePct": 98,
  "stationCount": 30,
  "companyId": "cccccccc-0000-0000-0000-000000000001",
  "createdAt": "2026-07-06T09:24:53.171192+00:00",
  "updatedAt": "2026-07-09T22:05:45.68844+00:00",
  "productId": "eeeeeeee-0000-0000-0000-000000000001",
  "zone": {
    "center": {
      "label": "Lyon 7e — Siège social",
      "lat": 45.7485,
      "lng": 4.8467
    },
    "radiusKm": 50
  },
  "fuels": [
    "B7",
    "SP95_E10",
    "SP98"
  ],
  "services": [
    "LAVAGE_PL",
    "PARKING_PL",
    "RESTAURATION"
  ],
  "competitors": [
    {
      "name": "Carbu Express",
      "pct": 98,
      "stations": 30
    },
    {
      "name": "TotalEnergies Pro",
      "pct": 98,
      "stations": 18
    },
    {
      "name": "BP+",
      "pct": 98,
      "stations": 18
    }
  ],
  "networkTotal": 160,
  "savingsPerMonth": null,
  "recommendation": null,
  "company": {
    "id": "cccccccc-0000-0000-0000-000000000001",
    "name": "Transports Bonin",
    "siret": "43219876500017",
    "city": "Lyon"
  }
}

The Pitch object

Field	Type	Description
`title`always present	`string \| null`
`sections`always present	`object[]`
`sections[].heading`always present	`string`
`sections[].body`always present	`string`	Markdown: bold, ==highlight==, numbered lists.
`nextStep`always present	`string \| null`
`sources`always present	`string[]`
`generator`always present	`"gemini" \| "template"`	gemini: written by AI; template: fallback template (always with an fw_test_ key).

Pitch

{
  "title": "Why Carbu Express is the right partner for your fleet",
  "sections": [
    {
      "heading": "Your current situation",
      "body": "You operate your fleet around Lyon 7e in the transports routiers de fret interurbains sector. Our simulation over a 50 km radius shows a ==coverage of 98%== of your activity by our current network (**30 stations** out of 160 listed in the zone) — solid, but with room to improve."
    },
    {
      "heading": "Three key benefits",
      "body": "1. Measurable savings from the first month — our average diesel price in the zone is competitive against the major networks present.\n2. 30 stations in the immediate vicinity of your rounds — your drivers save time on technical stops.\n3. A multi-energy card starting today — 3 energies covered (B7, SP95_E10, SP98), to anticipate the transition of your next renewals without changing supplier."
    },
    {
      "heading": "And what about the less covered areas?",
      "body": "This is our point of attention. Some secondary routes remain less covered. To compensate, we offer the Card + 24/7 breakdown assistance bundle — at no extra cost — and our network plan includes new openings in the area."
    }
  ],
  "nextStep": "Propose a 30-day trial on 5 vehicles to validate the actual savings before full rollout.",
  "sources": [
    "50 km zone simulation · 12:46 PM",
    "Carbu Express network: stations listed in Floweet",
    "Public prices: prix-carburants.gouv.fr"
  ],
  "generator": "template"
}

Coverage simulations of the organization, most recently updated first

GET/v1/simulationsScope simulations:read

Parameters

Field	In	Type	Description
`limit`optional	query	`integer`from 1 to 100 · default 20	Number of items per page (1 to 100, 20 by default).
`cursor`optional	query	`string`at most 400 characters	Opaque cursor: the `nextCursor` value of the previous page.
`status`optional	query	`"todo" \| "progress" \| "won" \| "lost" \| "archived"`
`mode`optional	query	`"zone" \| "trajet" \| "multi"`
`q`optional	query	`string`at most 100 characters	Search in the name.

Response 200

OK — A page of SimulationSummary { data, nextCursor, hasMore }

Errors

HTTP	Meaning
`400`	Invalid request
`401`	Missing, invalid or revoked API key
`403`	Forbidden (scope, plan or account status)
`404`	Resource not found
`429`	Too many requests
`500`	Internal error

Request

curl "https://api.floweet.com/v1/simulations" \
  -H "Authorization: Bearer $FLOWEET_API_KEY"

Response 200

{
  "data": [
    {
      "id": "ffffffff-0000-0000-0000-000000000002",
      "name": "Garage Mercier & Fils · Zone 30 km",
      "mode": "zone",
      "status": "won",
      "confidence": "low",
      "coveragePct": 36,
      "stationCount": 14,
      "companyId": "cccccccc-0000-0000-0000-000000000009",
      "createdAt": "2026-07-05T08:24:53.171192+00:00",
      "updatedAt": "2026-09-28T20:47:50.083018+00:00"
    },
    {
      "id": "ffffffff-0000-0000-0000-000000000001",
      "name": "Transports Bonin · Zone 50 km",
      "mode": "zone",
      "status": "todo",
      "confidence": "high",
      "coveragePct": 98,
      "stationCount": 30,
      "companyId": "cccccccc-0000-0000-0000-000000000001",
      "createdAt": "2026-07-06T09:24:53.171192+00:00",
      "updatedAt": "2026-07-09T22:05:45.68844+00:00"
    }
  ],
  "nextCursor": "eyJwIjoyLCJzIjoyfQ",
  "hasMore": true
}

Create a zone simulation: network coverage around a point for a client

POST/v1/simulationsScope simulations:write

Parameters

Field	In	Type	Description
`Idempotency-Key`optional	header	`string`at most 255 characters	Unique key for this request (a new UUID v4, kept for its retries): the first response is replayed for 24 hours.

Request body `SimulationInput`

Field	Type	Description
`name`optional	`string`1 to 200 characters	Default: « <company> · Zone <radius> km ».
`companySiret`optional	`string`	SIRET of the client (directory); otherwise `companyName`.
`companyName`optional	`string`1 to 200 characters
`center`required	`object`
`center.label`required	`string`at most 300 characters
`center.lat`required	`number`from -90 to 90
`center.lng`required	`number`from -180 to 180
`radiusKm`required	`number`from 1 to 300
`fuels`optional	`string[]`at most 20 items	Fuel codes the client needs (B7, GNV…).
`services`optional	`string[]`at most 20 items
`competitors`optional	`string[]`at most 10 items

Response 201

Simulation created — A Simulation object

Errors

HTTP	Meaning
`400`	Invalid request
`401`	Missing, invalid or revoked API key
`403`	Forbidden (scope, plan or account status)
`404`	Resource not found
`422`	Unprocessable request
`429`	Too many requests
`500`	Internal error
`502`	Upstream service error

Request

curl -X POST "https://api.floweet.com/v1/simulations" \
  -H "Authorization: Bearer $FLOWEET_API_KEY" \
  -H "Idempotency-Key: 6f1c2b0e-8d4a-4f7e-9a51-3c2d1e0f9b87" \
  -H "Content-Type: application/json" \
  -d '{
  "companyName": "Transports Bonin",
  "center": {
    "label": "Lyon 7e — Siège social",
    "lat": 45.7485,
    "lng": 4.8467
  },
  "radiusKm": 50,
  "fuels": [
    "B7",
    "SP95_E10",
    "SP98"
  ]
}'

Response 201

{
  "id": "ffffffff-0000-0000-0000-000000000001",
  "name": "Transports Bonin · Zone 50 km",
  "mode": "zone",
  "status": "todo",
  "confidence": "high",
  "coveragePct": 98,
  "stationCount": 30,
  "companyId": "cccccccc-0000-0000-0000-000000000001",
  "createdAt": "2026-07-06T09:24:53.171192+00:00",
  "updatedAt": "2026-07-09T22:05:45.68844+00:00",
  "productId": "eeeeeeee-0000-0000-0000-000000000001",
  "zone": {
    "center": {
      "label": "Lyon 7e — Siège social",
      "lat": 45.7485,
      "lng": 4.8467
    },
    "radiusKm": 50
  },
  "fuels": [
    "B7",
    "SP95_E10",
    "SP98"
  ],
  "services": [
    "LAVAGE_PL",
    "PARKING_PL",
    "RESTAURATION"
  ],
  "competitors": [
    {
      "name": "Carbu Express",
      "pct": 98,
      "stations": 30
    },
    {
      "name": "TotalEnergies Pro",
      "pct": 98,
      "stations": 18
    },
    {
      "name": "BP+",
      "pct": 98,
      "stations": 18
    }
  ],
  "networkTotal": 160,
  "savingsPerMonth": null,
  "recommendation": null,
  "company": {
    "id": "cccccccc-0000-0000-0000-000000000001",
    "name": "Transports Bonin",
    "siret": "43219876500017",
    "city": "Lyon"
  }
}

A simulation: zone, coverage, competitors, client

GET/v1/simulations/{id}Scope simulations:read

Parameters

Field	In	Type	Description
`id`required	path	`string (uuid)`

Response 200

OK — A Simulation object

Errors

HTTP	Meaning
`400`	Invalid request
`401`	Missing, invalid or revoked API key
`403`	Forbidden (scope, plan or account status)
`404`	Resource not found
`429`	Too many requests
`500`	Internal error

Request

curl "https://api.floweet.com/v1/simulations/7d0c1f8e-2a4b-4c6d-9e8f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $FLOWEET_API_KEY"

Response 200

{
  "id": "ffffffff-0000-0000-0000-000000000001",
  "name": "Transports Bonin · Zone 50 km",
  "mode": "zone",
  "status": "todo",
  "confidence": "high",
  "coveragePct": 98,
  "stationCount": 30,
  "companyId": "cccccccc-0000-0000-0000-000000000001",
  "createdAt": "2026-07-06T09:24:53.171192+00:00",
  "updatedAt": "2026-07-09T22:05:45.68844+00:00",
  "productId": "eeeeeeee-0000-0000-0000-000000000001",
  "zone": {
    "center": {
      "label": "Lyon 7e — Siège social",
      "lat": 45.7485,
      "lng": 4.8467
    },
    "radiusKm": 50
  },
  "fuels": [
    "B7",
    "SP95_E10",
    "SP98"
  ],
  "services": [
    "LAVAGE_PL",
    "PARKING_PL",
    "RESTAURATION"
  ],
  "competitors": [
    {
      "name": "Carbu Express",
      "pct": 98,
      "stations": 30
    },
    {
      "name": "TotalEnergies Pro",
      "pct": 98,
      "stations": 18
    },
    {
      "name": "BP+",
      "pct": 98,
      "stations": 18
    }
  ],
  "networkTotal": 160,
  "savingsPerMonth": null,
  "recommendation": null,
  "company": {
    "id": "cccccccc-0000-0000-0000-000000000001",
    "name": "Transports Bonin",
    "siret": "43219876500017",
    "city": "Lyon"
  }
}

Change the sales status or the name of a simulation

PATCH/v1/simulations/{id}Scope simulations:write

Parameters

Field	In	Type	Description
`id`required	path	`string (uuid)`

Request body `SimulationUpdate`

Field	Type	Description
`status`optional	`"todo" \| "progress" \| "won" \| "lost" \| "archived"`
`name`optional	`string`1 to 200 characters

Response 200

OK — A Simulation object

Errors

HTTP	Meaning
`400`	Invalid request
`401`	Missing, invalid or revoked API key
`403`	Forbidden (scope, plan or account status)
`404`	Resource not found
`429`	Too many requests
`500`	Internal error

Request

curl -X PATCH "https://api.floweet.com/v1/simulations/7d0c1f8e-2a4b-4c6d-9e8f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $FLOWEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "won"
}'

Response 200

{
  "id": "ffffffff-0000-0000-0000-000000000001",
  "name": "Transports Bonin · Zone 50 km",
  "mode": "zone",
  "status": "todo",
  "confidence": "high",
  "coveragePct": 98,
  "stationCount": 30,
  "companyId": "cccccccc-0000-0000-0000-000000000001",
  "createdAt": "2026-07-06T09:24:53.171192+00:00",
  "updatedAt": "2026-07-09T22:05:45.68844+00:00",
  "productId": "eeeeeeee-0000-0000-0000-000000000001",
  "zone": {
    "center": {
      "label": "Lyon 7e — Siège social",
      "lat": 45.7485,
      "lng": 4.8467
    },
    "radiusKm": 50
  },
  "fuels": [
    "B7",
    "SP95_E10",
    "SP98"
  ],
  "services": [
    "LAVAGE_PL",
    "PARKING_PL",
    "RESTAURATION"
  ],
  "competitors": [
    {
      "name": "Carbu Express",
      "pct": 98,
      "stations": 30
    },
    {
      "name": "TotalEnergies Pro",
      "pct": 98,
      "stations": 18
    },
    {
      "name": "BP+",
      "pct": 98,
      "stations": 18
    }
  ],
  "networkTotal": 160,
  "savingsPerMonth": null,
  "recommendation": null,
  "company": {
    "id": "cccccccc-0000-0000-0000-000000000001",
    "name": "Transports Bonin",
    "siret": "43219876500017",
    "city": "Lyon"
  }
}

Write the sales pitch of a simulation (AI when available, otherwise a template)

POST/v1/simulations/{id}/pitchScope simulations:write

With an fw_test_ key the pitch always comes from the template: no AI call is made.

Parameters

Field	In	Type	Description
`id`required	path	`string (uuid)`
`Idempotency-Key`optional	header	`string`at most 255 characters	Unique key for this request (a new UUID v4, kept for its retries): the first response is replayed for 24 hours.

Response 200

OK — A Pitch object

Errors

HTTP	Meaning
`400`	Invalid request
`401`	Missing, invalid or revoked API key
`403`	Forbidden (scope, plan or account status)
`404`	Resource not found
`429`	Too many requests
`500`	Internal error

Request

curl -X POST "https://api.floweet.com/v1/simulations/7d0c1f8e-2a4b-4c6d-9e8f-0a1b2c3d4e5f/pitch" \
  -H "Authorization: Bearer $FLOWEET_API_KEY" \
  -H "Idempotency-Key: 6f1c2b0e-8d4a-4f7e-9a51-3c2d1e0f9b87"

Response 200

{
  "title": "Why Carbu Express is the right partner for your fleet",
  "sections": [
    {
      "heading": "Your current situation",
      "body": "You operate your fleet around Lyon 7e in the transports routiers de fret interurbains sector. Our simulation over a 50 km radius shows a ==coverage of 98%== of your activity by our current network (**30 stations** out of 160 listed in the zone) — solid, but with room to improve."
    },
    {
      "heading": "Three key benefits",
      "body": "1. Measurable savings from the first month — our average diesel price in the zone is competitive against the major networks present.\n2. 30 stations in the immediate vicinity of your rounds — your drivers save time on technical stops.\n3. A multi-energy card starting today — 3 energies covered (B7, SP95_E10, SP98), to anticipate the transition of your next renewals without changing supplier."
    },
    {
      "heading": "And what about the less covered areas?",
      "body": "This is our point of attention. Some secondary routes remain less covered. To compensate, we offer the Card + 24/7 breakdown assistance bundle — at no extra cost — and our network plan includes new openings in the area."
    }
  ],
  "nextStep": "Propose a 30-day trial on 5 vehicles to validate the actual savings before full rollout.",
  "sources": [
    "50 km zone simulation · 12:46 PM",
    "Carbu Express network: stations listed in Floweet",
    "Public prices: prix-carburants.gouv.fr"
  ],
  "generator": "template"
}

Coverage simulations

Good to know

Example: from prospect to pitch

The SimulationSummary object

The Simulation object

The Pitch object

Coverage simulations of the organization, most recently updated first

Parameters

Response 200

Errors

Create a zone simulation: network coverage around a point for a client

Parameters

Request body SimulationInput

Response 201

Errors

A simulation: zone, coverage, competitors, client

Parameters

Response 200

Errors

Change the sales status or the name of a simulation

Parameters

Request body SimulationUpdate

Response 200

Errors

Write the sales pitch of a simulation (AI when available, otherwise a template)

Parameters

Response 200

Errors

Request body `SimulationInput`

Request body `SimulationUpdate`