Integrating with External Systems

Overview

Installer.com is the backbone of data for an installation business. It matchmakes the parties involved (operator, contractor, end customer), runs the order through a configurable workflow, and collects the data that those parties produce along the way. Once the data is in the platform, it can be pushed to any external system you operate (CRM, ERP, finance, ticketing) or pulled by an external system on demand.

This guide explains the mental model for integrating an external system such as a CRM (Salesforce, HubSpot, Dynamics), an ERP, an accounting tool, or an internal ops system. It does not assume any platform-specific connector. The integration surface is the public API and webhooks.

How integrations work

There are three traffic patterns to think about:

The end-user channels are listed for completeness, but they target people, not systems. When you want to integrate with another system, use the inbound and outbound channels.

Bringing data in

Create orders early with a prefilled offer

The most common inbound pattern is to create an order early in the customer journey, well before the lead is "converted" in your CRM, and let the end customer convert by accepting the prefilled offer and paying through the platform. Conversion is measured by the offer being accepted and payment captured in Installer.com, not by a status change in your CRM.

A typical inbound order includes:

• Customer contact details and installation address
• The workflow template (workflowId) the order should follow
• Custom field values for anything the workflow needs (panel count, vehicle model, meter type)
• A prefilled offer with line items priced from your product catalogue

curl -X POST https://api.installer.com/api/v1/order \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "...",
    "contactPersonName": "...",
    "email": "...",
    "phoneNumber": "...",
    "address": "...",
    "postalCode": "...",
    "countryCode": "NO",
    "offer": {
      "name": "EV charger install",
      "payer": "client",
      "lines": [
        { "externalId": "evc-7kw", "quantity": 1 }
      ]
    },
    "customFields": [
      { "customId": "panel-count", "value": "12" }
    ]
  }'

Custom fields are the extension surface. Any field your CRM holds that doesn't fit the standard schema can be modelled as a custom field on the order template, then referenced by its custom ID from both the API and from webhook or background event payloads.

See the Quick Start for a step-by-step walkthrough, and the Create Order endpoint for the full schema.

Webforms for no-code intake

If you want to capture orders from people directly (a partner, a marketplace, or an end customer) without building an API integration, configure a webform in the Routing App and share the link. The webform renders in the browser, collects the fields you configure, and creates an order on submit using the same workflow template you'd use with the API. It's the right option when the data is coming from a human rather than another system.

Configure webforms under Settings → Webforms in the Routing App.

File uploads

Attach photos, contracts, and surveys to an order with the Upload File endpoint. The returned file ID can be referenced from other API calls and from outbound payloads.

Workflow steps as integration points

Every order follows a workflow that is configured in a workflow template. Each step in the workflow produces data when its state changes. These state transitions are the stable integration points: subscribe to them and you receive the data the step produced.

The table below maps common step types to the data they produce and the typical action an external system takes when that step transitions to done:

Steps are completed by the assigned actor: the contractor organisation and user responsible for that step, the operator running the order, or an automated agent acting on their behalf. Whether completion happens through the contractor app, a background event, or an API call from your own system is an integration choice, not a platform constraint.

Pushing data out

Webhooks

Webhooks are configured on an individual workflow step and fire when that step enters a configured state (active, done, rejected, cancelled, and others). The payload is a JSON body that you write yourself using Handlebars, so you control exactly which fields and shape the receiving system gets.

{
  "orderId": "{{order.id}}",
  "displayId": "{{order.displayId}}",
  "customer": {
    "name": "{{order.contactPersonName}}",
    "email": "{{order.email}}"
  },
  "step": "{{step.type}}",
  "state": "{{state}}",
  "installer": "{{actor.installer.organizationName}}"
}

Full reference: Webhooks guide.

Background events

Background events are similar to webhooks but designed for outbound calls that need to wait for a response and act on it. They support polling, terminal status detection, and auto-completion of the workflow step. Use a background event when your external system is the source of truth for whether a step is done (for example, a regulator approving an application).

See the DNO Integration for a canonical example: it submits an application, stores the response on the workflow, polls until a terminal status is returned, and auto-completes or auto-rejects the step.

Notifications to humans

The platform also sends SMS, email, and push notifications to customers, installers, and operators. These are configured on workflow steps alongside webhooks. They are not API integrations, but worth knowing about so you do not duplicate notifications already sent by Installer.com (for example, a booking confirmation SMS).

Automation

Installer.com is designed to be automated as far as your operation allows. Any step can be driven by software, by a person, or by a combination of both. The platform provides several first-class automation primitives:

Prefer modelling automated decisions as background events the platform controls, rather than calling an API to mark a step done from outside. Background events respect the workflow state machine and its guardrails. Direct API mutations on steps bypass those checks and are easy to get wrong.

Reliability

When you wire a webhook or background event to a production system, design for the realities of distributed delivery:

See Webhooks → Retry policy for the exact retry schedule.

Common patterns

Installer.com as the backbone (recommended)

The typical setup is to run orders, offers, products, payments, and bookings inside Installer.com as the single source of truth. The Routing App is where operators manage day-to-day work, the contractor app is where installers execute it, and the client portal is where end customers accept offers, pay, and track their job. External systems plug in around the edges (lead capture, accounting exports, regulatory submissions) without owning the operational data.

This setup gives you:

• One product catalogue with per-partnership pricing and split payouts.
• Payments captured and reconciled in one place, with operator and installer payouts handled automatically.
• A single workflow timeline per order that all parties can see.
• No reconciliation work between operational systems.

Most customers stay on this pattern. The integrations described below are useful additions, not replacements for it.

Syncing data to external systems

If you do need the data in another system (a finance team's ERP, a BI warehouse, a partner's portal), use webhooks and background events to push it out as orders progress. Two common shapes:

Lead-capture sync. A CRM owns the top of the funnel and creates orders in Installer.com when a lead is ready for quoting. The CRM subscribes to webhooks on OfferCreate.done, Payment.done, BookingCreate.done, and Installation.done and reflects the operational state back onto the lead record. Conversion is measured by acceptance and payment in Installer.com.

Accounting / finance sync. A webhook on OfferCreate.done pushes the offer to the accounting system as a quote. A webhook on Payment.done posts the transaction to the ledger. A webhook on Installation.done triggers final invoicing. The data still lives in Installer.com, the accounting system gets a copy on the events it cares about.

Regulatory or third-party verification

Some workflows include a step that requires approval from an external authority. Use a background event to submit the application, poll for status, and auto-complete or auto-reject the step on a terminal response. Downstream steps activate automatically once the gate is passed.

This is exactly how the DNO integration works against ENA Connect.

Next steps