Home Planner
Back to Help centerHow-to guides

Home Planner CRM API Reference

Home Planner
Home PlannerApp Team · October 28, 2026

Endpoints, authentication, webhook delivery and the project record of the Home Planner CRM API used by Zapier, Make and your own server.

Home Planner app sends a room design project via Zapier to HubSpot, Salesforce, Google Sheets and Pipedrive

The Home Planner CRM API connects the Home Planner app to Zapier, Make and your own server. It has four endpoints, all authenticated with a connection key, and one webhook that delivers each project the user sends.

This page is for developers and integration platforms. To set up project sending in the app, see How to send projects from Home Planner to your CRM.

Overview

ItemValue
Base URLhttps://icandesignapp.com (use this host: a redirect from homeplannerapp.com can drop a POST body)
FormatJSON over HTTPS
AuthenticationConnection key in the X-Api-Key header
DeliveryWebhook (REST hook): one POST per sent project
Required planPRO++ (or its 14-day free trial)

There are two ways to connect:

  1. Key connection — for Zapier and Make. The user chooses a CRM in the app and copies the key; the platform subscribes its webhook with POST /crm/key/hooks. This page describes this way.
  2. URL connection — for your own server. The user chooses Other system (your URL) in the app and enters the URL there. No key and no endpoints are needed, and the app shows the signing secret.
MethodEndpointPurpose
GET/crm/key/meValidate the key and return the connection name
POST/crm/key/hooksSubscribe a webhook URL
DELETE/crm/key/hooks/{id}Unsubscribe the webhook
GET/crm/key/sampleGet a sample project record

Authentication

Every request carries the connection key in the X-Api-Key header. Each key belongs to a single CRM connection in a single Home Planner account. Never put the key in a URL.

yamlyaml
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>

The user gets the key in the Home Planner app:

  1. Open Settings and choose where to send projects.
  2. Select Add connection and choose HubSpot, Pipedrive, Bitrix24, Salesforce or Google Sheets.
  3. Select Copy key.

A key stops working when the user selects New key or deletes the connection. Any request with a missing, invalid or replaced key returns 401 with {"code": "crm_key_invalid"} (DELETE is the exception, see below).

GET /crm/key/me

Returns the connection that the key belongs to. Zapier calls it to test a new connection and to label it.

bashbash
curl https://icandesignapp.com/crm/key/me \
  -H 'X-Api-Key: hp_live_…'

Response 200:

jsonjson
{
  "connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
  "name": "HubSpot deals",
  "system": "hubspot"
}
FieldTypeDescription
connectionIdstringConnection ID
namestringConnection name from the app, up to 24 characters
systemstringhubspot, pipedrive, bitrix24, salesforce or sheets

Errors: 401 crm_key_invalid. Other errors: see Errors below.

POST /crm/key/hooks

Sets the webhook URL that receives every project sent through this connection. Zapier calls it when a Zap is turned on.

bashbash
curl -X POST https://icandesignapp.com/crm/key/hooks \
  -H 'X-Api-Key: hp_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://hooks.zapier.com/hooks/standard/123456/abcdef/"}'

Response 201:

jsonjson
{
  "id": "3f2b9c0d1e4a5b6c7d8e9f01"
}

Store the id: you need it to unsubscribe.

  • One subscription per connection: a new subscription replaces the previous URL.
  • The URL must start with https://, be at most 2048 characters long and contain no user name or password.
  • URLs that point to private or local networks, including host names that resolve to them, are rejected: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* and 169.254.*.
StatuscodeMeaning
401crm_key_invalidMissing, invalid or replaced key
422crm_url_invalidNot an https:// URL, or longer than 2048 characters
422crm_url_credentialsThe URL contains a user name or password
422crm_url_forbiddenThe URL points to a private or local network

Other errors: see Errors below.

DELETE /crm/key/hooks/{id}

Removes the subscription with this id. Zapier calls it when a Zap is turned off or deleted.

bashbash
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
  -H 'X-Api-Key: hp_live_…'

Response 204 with no body. The response is also 204 if the ID does not match the current subscription, the key has been replaced, or the connection has been deleted. In each case there is nothing left to remove.

Errors: 401 crm_key_invalid for a missing key or a key that was never valid. Other errors: see Errors below.

GET /crm/key/sample

Returns an array with one sample project record in the same format as a real delivery. Zapier shows its fields so the user can map them to CRM fields.

bashbash
curl https://icandesignapp.com/crm/key/sample \
  -H 'X-Api-Key: hp_live_…'

Response 200: an array with one project record (below).

Errors: 401 crm_key_invalid. Other errors: see Errors below.

Webhook delivery

When the user selects Share → Send to … in the app, Home Planner posts the project to the subscribed URL.

PartValue
MethodPOST
Content-Typeapplication/json
BodyOne project record
X-HomePlanner-DeliveryDelivery ID. It stays the same across retries: use it to detect duplicates.
X-HomePlanner-Signaturet=<unix time in seconds>,v1=<lowercase hex>, where v1 = HMAC-SHA256(signing secret, t + "." + raw body)
Your responseWhat Home Planner does
Any 2xx within 15 secondsDelivered
No response within 15 seconds, 5xx, 408 or 429Retries after 1 minute, 10 minutes and 1 hour. If the project is still not delivered 2 hours after the first attempt, stops retrying and marks the connection as Error in the app.
410 GoneKey connection: removes the subscription; turn the Zap on again to resubscribe. URL connection: the same as any other 4xx
Any other 4xx, a redirect or a certificate errorNo retry; the app marks the connection as Error

Every delivery is signed. The app shows the signing secret only for a URL connection. For signature verification steps, see How to send projects from Home Planner to your CRM.

When the user's PRO++ subscription or free trial ends, the app stops sending projects. The endpoints keep responding, so the Zap stays on but receives no new projects until the user renews.

Project record

Every delivery and the sample endpoint use this format. Prices and totals match the project estimate in the app. In Zapier, the record also has an id field: a copy of client_reference_id, shown as Send ID.

project-record.jsonjson
{
  "client_reference_id": "sample_0d4f1c2b9e7a",
  "planNumber": "000000000000000000000000",
  "planName": "Sample project",
  "revisionUrl": "https://share.roomplannerapp.com/all/project/000000000000000000000000",
  "revisionNumber": "1",
  "updated": "2026-10-01T12:00:00.000Z",
  "created": "2026-09-28T09:30:00.000Z",
  "rooms": [
    {
      "roomNumber": "6f1d2c3b4a5e6f708192a3b4c5d6e7f8",
      "roomName": "Living room",
      "items": [
        {
          "itemNumber": "SOFA-1042",
          "quantity": 1,
          "imageURL": "https://files.icandesignapp.com/sample/sofa.jpg",
          "components": [
            {
              "itemNumber": "CUSH-17",
              "quantity": 2,
              "imageURL": "",
              "name": "Cushion",
              "price": 25,
              "currency": "USD",
              "total": 50,
              "price_source": "estimate",
              "source": "homeplanner"
            }
          ],
          "name": "Sofa Oslo",
          "price": 899,
          "currency": "USD",
          "total": 899,
          "price_source": "company",
          "source": "company",
          "note": null
        },
        {
          "itemNumber": "Floor_Oak_01",
          "quantity": 1,
          "imageURL": "",
          "name": "Oak flooring",
          "price": 540,
          "currency": "USD",
          "total": 540,
          "price_source": "estimate",
          "source": "homeplanner",
          "note": null,
          "area": 18
        }
      ],
      "roomType": "LivingRoom",
      "area": 18,
      "height": 2.7,
      "width": 4,
      "depth": 4.5
    }
  ],
  "integration": "custom",
  "totals": {
    "items": 2,
    "sum": 1489,
    "currency": "USD"
  },
  "warning": null,
  "pdfUrl": "https://files.icandesignapp.com/sample/plan.crm.pdf",
  "productsText": "Living room:\n- Sofa Oslo (SOFA-1042): 1 × 899.00 = 899.00 USD\n  - Cushion (CUSH-17): 2 × 25.00 = 50.00 USD\n- Oak flooring (Floor_Oak_01): 1 × 540.00 = 540.00 USD\n\nTotal: 1489.00 USD"
}
FieldTypeDescription
client_reference_idstringUnique ID of this send
planNumberstringProject ID
planNamestringProject name
revisionUrlstringPublic link to the project
revisionNumberstringProject revision
created, updatedstring, ISO 8601When the project was created and last saved
rooms[]arrayroomNumber, roomName, roomType, area (m²), height, width, depth (m), items
rooms[].items[]arrayitemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (the user's note on the item, or null), area (m², for materials), components[] (parts of the item: the same fields, where quantity is the count for all units of the item, plus quantityPerItem, the count per unit; the sample omits quantityPerItem)
price_sourcestringcompany (price from the company catalog) or estimate (Home Planner estimate)
sourcestringcompany (product from the company catalog) or homeplanner (Home Planner catalog)
totalsobjectitems: number of top-level line items (components not counted); sum: estimate total, components included; currency: currency code
pdfUrlstring or nullLink to the floor plan PDF; the file is available for 7 days
productsTextstringThe full estimate as plain text
warningstring or nullFor example: "2 item(s) without SKU were sent with a Home Planner code"
integrationstringAlways "custom"

Rate limits

ScopeLimit
One connection key30 requests per minute, 500 per day
Requests with an invalid key, per IP address300 per minute, 5000 per day

When a limit is exceeded, the API returns 429 with {"code": "crm_throttled"}.

Errors

Every error is JSON with a code field, for example {"code": "crm_key_invalid"}.

StatuscodeMeaning
401crm_key_invalidMissing, invalid or replaced key
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenThe webhook URL is refused
429crm_throttledRate limit reached
503crm_unavailableTemporary server problem; retry later

Support

Questions about the API: [email protected].

Trademark notice. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce and Google Sheets are trademarks of their owners. Home Planner is independent of these companies and is not endorsed by, sponsored by or affiliated with them.

Home Planner

Try it on your own project

Free room planner and interior design app