Create sales opportunities integration via Connect

All steps needed to integrate sales opportunities with a client CRM or sales platform using the Connect API.

Webhook setup

Configure a sales-opportunity webhook endpoint to listen to sales opportunity events generated by Clevergy.

Clevergy sends a webhook whenever a sales opportunity changes:

• CREATE : A new sales opportunity is generated (e.g. a user starts a contracting flow from the app)
• UPDATE : A sales opportunity is updated (status change)
• DELETE : A sales opportunity is deleted

note

Webhooks are event notifications only. Sales opportunity data must always be retrieved via the Connect API.

Currently, only CONTRACT product opportunities are supported. Other product values (SOLAR, HEATPUMP, BATTERY, DEVICES, EV, OTHER) are reserved for future use.

Sales opportunity statuses

Status	Meaning
STARTED	The user has initiated the opportunity by showing interest in a product (e.g. via a recommender or banner in the app).
POTENTIAL	The opportunity was proactively suggested by Clevergy based on energy data and user behavior, without direct user interaction.
FORMALIZED	The user has accepted a contract or proposal.
CONVERTED	The payment has been received and the product or service is being delivered (e.g. the contract has been signed).
REJECTED	The opportunity was lost, either because the user declined or stopped responding.

Sales opportunity flow

This section describes a typical end-to-end flow for a CONTRACT sales opportunity.

1. A sales opportunity is created
   • Webhook event: CREATE
2. Retrieve the opportunity details
   • When a sales opportunity webhook event is triggered, fetch the full details via the Connect API using the id included in the webhook payload.
   • For CONTRACT opportunities, this includes the contracting payload fields (contact data, CUPS, IBAN, invoice references, etc.).
3. List opportunities from your platform
   • Use the list endpoint to retrieve all sales opportunities for the tenant, optionally filtered by status or product.
4. Update the opportunity status
   • As the opportunity progresses through your sales process, update its status (e.g. to FORMALIZED or CONVERTED).
5. Reject or discard the opportunity (optional)
   • Update the status to REJECTED if the opportunity does not move forward.
6. Delete the opportunity (optional)
   • Hard-deletes the opportunity and cascades the deletion to its related notes.

Required endpoints

getSalesOpportunities

getContractSalesOpportunity

patchContractSalesOpportunity

deleteSalesOpportunity