Home Planner CRM API Reference

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

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
| Item | Value |
|---|---|
| Base URL | https://icandesignapp.com (use this host: a redirect from homeplannerapp.com can drop a POST body) |
| Format | JSON over HTTPS |
| Authentication | Connection key in the X-Api-Key header |
| Delivery | Webhook (REST hook): one POST per sent project |
| Required plan | PRO++ (or its 14-day free trial) |
There are two ways to connect:
- 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.
- 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.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /crm/key/me | Validate the key and return the connection name |
| POST | /crm/key/hooks | Subscribe a webhook URL |
| DELETE | /crm/key/hooks/{id} | Unsubscribe the webhook |
| GET | /crm/key/sample | Get 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.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>The user gets the key in the Home Planner app:
- Open Settings and choose where to send projects.
- Select Add connection and choose HubSpot, Pipedrive, Bitrix24, Salesforce or Google Sheets.
- 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.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Response 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Field | Type | Description |
|---|---|---|
| connectionId | string | Connection ID |
| name | string | Connection name from the app, up to 24 characters |
| system | string | hubspot, 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.
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:
{
"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.*.
| Status | code | Meaning |
|---|---|---|
| 401 | crm_key_invalid | Missing, invalid or replaced key |
| 422 | crm_url_invalid | Not an https:// URL, or longer than 2048 characters |
| 422 | crm_url_credentials | The URL contains a user name or password |
| 422 | crm_url_forbidden | The 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.
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.
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.
| Part | Value |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Body | One project record |
| X-HomePlanner-Delivery | Delivery ID. It stays the same across retries: use it to detect duplicates. |
| X-HomePlanner-Signature | t=<unix time in seconds>,v1=<lowercase hex>, where v1 = HMAC-SHA256(signing secret, t + "." + raw body) |
| Your response | What Home Planner does |
|---|---|
| Any 2xx within 15 seconds | Delivered |
| No response within 15 seconds, 5xx, 408 or 429 | Retries 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 Gone | Key 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 error | No 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.
{
"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"
}| Field | Type | Description |
|---|---|---|
| client_reference_id | string | Unique ID of this send |
| planNumber | string | Project ID |
| planName | string | Project name |
| revisionUrl | string | Public link to the project |
| revisionNumber | string | Project revision |
| created, updated | string, ISO 8601 | When the project was created and last saved |
| rooms[] | array | roomNumber, roomName, roomType, area (m²), height, width, depth (m), items |
| rooms[].items[] | array | itemNumber (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_source | string | company (price from the company catalog) or estimate (Home Planner estimate) |
| source | string | company (product from the company catalog) or homeplanner (Home Planner catalog) |
| totals | object | items: number of top-level line items (components not counted); sum: estimate total, components included; currency: currency code |
| pdfUrl | string or null | Link to the floor plan PDF; the file is available for 7 days |
| productsText | string | The full estimate as plain text |
| warning | string or null | For example: "2 item(s) without SKU were sent with a Home Planner code" |
| integration | string | Always "custom" |
Rate limits
| Scope | Limit |
|---|---|
| One connection key | 30 requests per minute, 500 per day |
| Requests with an invalid key, per IP address | 300 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"}.
| Status | code | Meaning |
|---|---|---|
| 401 | crm_key_invalid | Missing, invalid or replaced key |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | The webhook URL is refused |
| 429 | crm_throttled | Rate limit reached |
| 503 | crm_unavailable | Temporary 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.
Try it on your own project
Free room planner and interior design app


