Quick Start

Overview

This guide takes you from zero to a live order created via the API in three steps. You'll set up a workflow template in the Routing App, grab a ready-made example payload from the same screen, then post it to the Create Order endpoint with your API token.

Before you start, get an API token from Settings → Integrations in app.installer.com. See Authentication for details.

Steps

curl -X POST https://api.installer.com/api/v1/order \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @order.json

Actor assignment

If you already know which installer should perform the job (for example, you've assigned the lead to a specific partner in your CRM), pre-assign them on the order with actorAssignments:

{
  "workflowId": "...",
  "actorAssignments": [
    {
      "actorSlug": "installer",
      "organizationExternalId": "partner-acme-123"
    }
  ]
}

• actorSlug matches an actor configured on your workflow template (typically installer).
• Identify the organisation by either organizationId (Installer.com UUID) or organizationExternalId (the ID you use for the partner in your own system).

If you don't pre-assign, the order goes through your workflow's normal Dispatching step, where the operator (or auto-dispatch) selects an installer. Pre-assignment is the right choice when your CRM already owns that decision. Dispatching is the right choice when you want to broadcast the job or let the platform pick.

Offer prefill

Orders typically include an offer, which is the priced quote the end customer accepts and pays. Prefilling the offer at order creation means the customer sees pricing immediately, and acceptance plus payment in the platform becomes your conversion event.

There are two ways to populate offer lines, and one of them is strongly preferred.

Recommended: reference products from your catalogue

Pass a productId or externalId on each offer line. The platform matches against your product catalogue and pulls in pricing, payout, and tax configuration automatically:

{
  "offer": {
    "name": "EV charger install",
    "payer": "client",
    "lines": [
      { "externalId": "evc-7kw", "quantity": 1 },
      { "productId": "5f...uuid", "quantity": 2 }
    ]
  }
}

Why this matters:

• Pricing groups per installation partner: products in Installer.com support per-partnership pricing. The same product can be priced differently for different contractors, with the right unit amount, tax rate, and installer payout applied automatically when the order is dispatched.
• Payment and split payout: when the customer pays, the platform splits the payment between your organisation and the assigned installer based on the product's configured payout. This only works correctly when the offer line is tied to a product.
• Catalogue updates flow through: if you change a product's price, future orders reflect it without integration changes on your side.

Set up your product catalogue in Settings → Products in the Routing App, then reference products by externalId (recommended for stable cross-system identifiers) or productId.

Fallback: raw offer lines

You can also pass raw line details (name, unit amount, VAT rate, payout) directly without referencing a product:

{
  "offer": {
    "lines": [
      {
        "name": "EV charger",
        "quantity": 1,
        "currencyCode": "NOK",
        "payerUnitAmount": "1000000",
        "vatRate": "2500",
        "installerPayoutUnitAmount": "500000"
      }
    ]
  }
}

Next steps

• Integrating with External Systems for the broader integration model, including outbound webhooks and automation hooks.
• Webhooks to receive workflow state changes back in your system.
• API Reference for the full endpoint catalogue.