Planimble for developers

How it fits together

Four parties take part. Your API key never leaves your server; the browser only ever holds a short-lived link for one inspection.

Quickstart

1. Get an API key

   API access requires an active B2B API plan. There is no separate test-key service: a live key operates on real account data. Open the playground’s key-creation steps: sign in as the owner in another tab, prepare the key request, then send it from the API console. The key is shown once; store it in your server’s secret store. You can also test the public health endpoint without a key.

   POST /api/v1/org/api-keys        (signed in as the owner)
   → { "apiKey": "pk_live_…", "note": "Store this now; it is not shown again." }

2. Register your website

   Only registered websites can show the sketcher. Use the address of the page that will hold the iframe: https, no path. http://localhost is accepted for testing. Up to 10.

   PUT /api/v1/org/embed-origins    (signed in as the owner)
   { "origins": ["https://inspections.example.com"] }

3. Ask for a link from your server

   One link per inspection visit. It is valid for two hours, works only on the website you name, and reaches only this one sketch.

   curl C# Node

   curl -X POST "https://app.planimble.com/api/v1/embed/sessions" \
     -H "X-Api-Key: $PLANIMBLE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "externalInspectionId": "INS-1042",
           "origin": "https://inspections.example.com",
           "userName": "Pat Field",
           "subject": "12 Elm St, policy 77-1042",
           "mode": "edit" }'

4. Mount the sketcher on your page

   Load the SDK from Planimble and give it the link. It saves on its own while the inspector works; onSaved fires after every save on the server.

   <div id="sketch" style="height: 720px"></div>
   <script src="https://app.planimble.com/sdk/planimble-embed-sdk.js"></script>
   <script>
     const { embedUrl } = await (await fetch('/inspections/INS-1042/sketch-link', { method: 'POST' })).json();
     const sketch = PlanimbleEmbed.mount('#sketch', {
       embedUrl,
       height: '100%',
       onReady: m => console.log('ready', m.mode),
       onSaved: m => showTotals(m.calculatedSummary),     // { totalGlaSqFt, totalNonGlaSqFt, … }
       onError: m => m.code === 'embed_expired' && reopen()
     });
   </script>

5. Read the result from your server

   Read by your own inspection ID. Treat this server copy as the record: it is recalculated by Planimble, not taken from the browser.

   curl C# Node

   curl "https://app.planimble.com/api/v1/sketches/INS-1042" \
     -H "X-Api-Key: $PLANIMBLE_API_KEY"

Keys and tokens

An API key works only while the account is on an active B2B API plan (or a payment is past due). Removing a website from the registered list stops its links at once, including ones already handed out.

Embedding the sketcher

Create a link

POST /api/v1/embed/sessions API key

{
  "token": "CfDJ8…",
  "embedUrl": "https://app.planimble.com/embed?token=CfDJ8…&subject=12%20Elm%20St",
  "expiresAtUtc": "2026-10-24T13:40:00+00:00",
  "origin": "https://inspections.example.com",
  "mode": "edit"
}

What the sketcher shows

Inside your page the sketcher shows only the sketch: no Planimble sign-in, account, billing or list of other sketches. It saves to the server automatically while the inspector works, and works on touch screens with the number pad, voice and photos. Grant microphone and camera to the iframe (the SDK does) if you want voice input and photos.

When a link expires

After two hours, or if the website is removed, the sketcher shows "This sketch session has ended" and sends PLANIMBLE_ERROR with code: "embed_expired". Anything saved so far is kept. Ask your server for a new link and mount it again.

JavaScript SDK

Load /sdk/planimble-embed-sdk.js from Planimble. It adds window.PlanimbleEmbed (version 2.0) and talks only to the Planimble origin in embedUrl, and only with the iframe it created.

PlanimbleEmbed.mount(container, options)

Instance methods

Messages

The SDK is a thin wrapper over postMessage. If you build your own, send to and accept from the exact Planimble origin, and check event.source is your iframe.

The last two are not passed to SDK callbacks yet; listen for them on window if you need them. The playground's message log shows every message.

API reference

All responses are JSON. Errors return { "code": "…", "message": "…" }; save validation errors return { "code": "…", "error": "…" }. Every /api response is sent with Cache-Control: no-store.

{id} is your externalInspectionId or Planimble's sketchId.

Sketch data

The same shape is used to save (POST /sketches/sync), to load into the sketcher (PLANIMBLE_LOAD), and in vectorCanvas when you read a sketch (schema 1.7). Lengths are feet. x grows east and y grows south, so north is up on screen.

{
  "externalInspectionId": "INS-1042",
  "subject": "12 Elm St, policy 77-1042",
  "baseRevision": 0,
  "glaRate": 195, "auxRate": 88, "materialMultiplier": 1.0,
  "floors": [ { "id": "main", "name": "Main floor", "visible": true, "locked": false } ],
  "activeFloorId": "main",
  "areas": [
    { "id": "a1", "code": "GLA1", "label": "Main house", "isLivingAreaGla": true, "factor": 1,
      "floorId": "main",
      "verticesFt": [ {"x":0,"y":0}, {"x":48,"y":0}, {"x":48,"y":30}, {"x":0,"y":30} ] },
    { "id": "a2", "code": "GAR", "label": "Garage", "isLivingAreaGla": false, "factor": 1,
      "floorId": "main",
      "verticesFt": [ {"x":48,"y":6}, {"x":72,"y":6}, {"x":72,"y":30}, {"x":48,"y":30} ] }
  ],
  "stamps": []
}

Areas

Everything else

Leaving out underlay, annotations, photos, bulges or holes keeps what is saved, so an older integration never wipes them by accident. Send an empty list or null to clear them.

How the totals are worked out

Planimble ignores any areas or totals you send and measures every area itself (curved walls and openings included), rounded to a tenth of a square foot. Replacement cost is (living × glaRate + other × auxRate) × materialMultiplier, rounded to whole dollars, unless a custom rcFormula is set. Drawing problems are reported in validation.issues, never silently fixed:

SELF_INTERSECTION TOO_FEW_POINTS ZERO_AREA DUPLICATE_POINT SHORT_WALL FACTOR_RANGE BULGE_RANGE HOLE_OUTSIDE HOLE_OVERLAP

Saving and conflicts

Every accepted save adds one to revision. Send the revision you last read as baseRevision. If someone saved in between (the inspector in the field, or QA in the office), the save is refused with 409, and the response carries the current server copy so you can merge or ask:

{ "error": "revision_conflict",
  "message": "This sketch was changed on another device or by the office since your last sync.",
  "yourBaseRevision": 3,
  "server": { "revision": 4, … } }

A new externalInspectionId counts toward the month's new sketches (500 on the B2B API plan). Edits to an existing sketch never count. Over the limit, a new sketch is refused with 402 quota_exceeded and resetsAtUtc.

Webhooks

When your server saves with an API key, add "webhookCallbackUrl": "https://…" to the body. Planimble then posts the save result to that address, signed with the webhook signing secret Planimble gives you: X-Planimble-Signature is the HMAC-SHA256 of the raw body, in upper-case hex.

app.MapPost("/planimble/webhook", async (HttpRequest req, IConfiguration cfg) =>
{
    using var reader = new StreamReader(req.Body);
    var body = await reader.ReadToEndAsync();
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(cfg["Planimble:WebhookSecret"]!));
    var expected = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(body)));
    var given = req.Headers["X-Planimble-Signature"].ToString();
    if (!CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(given)))
        return Results.Unauthorized();
    var saved = JsonDocument.Parse(body).RootElement;   // eventType: PLANIMBLE_SKETCH_SAVED
    return Results.Ok();
});

import crypto from 'node:crypto';
app.post('/planimble/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', process.env.PLANIMBLE_WEBHOOK_SECRET)
    .update(req.body).digest('hex').toUpperCase();
  const given = req.get('X-Planimble-Signature') || '';
  if (given.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given))) return res.sendStatus(401);
  const saved = JSON.parse(req.body);   // eventType: PLANIMBLE_SKETCH_SAVED
  res.sendStatus(200);
});

Errors

Limits

Security checklist

• The API key is only on your server, in a secret store, never in page code or a mobile app.
• Your page gets embedUrl from your own server, after your own sign-in and permission checks.
• Create a new link for each visit; don't store embedUrl in your database or logs.
• Use view mode for people who should only look.
• Save the inspection's numbers from GET /api/v1/sketches/{id} on your server, not from browser messages.
• Verify the webhook signature with a constant-time comparison, and accept only HTTPS callbacks.
• Planimble refuses to be framed anywhere except your registered websites, sends no cookies inside the iframe, and never uses a Planimble sign-in from the same browser.