# Network Requirements
To ensure reliable communication between your infrastructure and magicplan services, please review and configure the following network requirements.
### đ Outbound IP Whitelisting
If your system enforces outbound traffic restrictions (e.g. via firewalls or proxy rules), please make sure to allow traffic from our stable outbound IP address: `13.219.158.242`
This IP is used by magicplan for operations such as:
* Sending data to external systems (e.g. webhooks, integrations)
* Communicating with partner or customer endpoints
* Accessing API endpoints that require reverse connectivity
If this IP is not whitelisted, some features or integrations may not function properly.
### đ API Access
Ensure that your network can reach the following domain to interact with the magicplan API:
* `https://cloud.magicplan.app`
Outbound HTTPS (TCP port 443) must be allowed for this domain.
#### â Additional Notes
* We currently use a **static outbound IP**, but if there are changes in the future, we will notify you in advance.
* No inbound traffic is expected or required to use the magicplan API.
If you have any questions or need assistance configuring your environment, feel free to [contact us](/guide/contact-support).
# Introduction to the magicplan REST API
Integrate, Retrieve, and Automate with the magicplan API
magicplan offers several built-in integration options, but you can also use the **magicplan REST API** to seamlessly connect your platform with magicplan. The following sections will guide you through the various integration methods available.
### **What Can You Do with the API? **
* **Project & Plan Management:** Create, retrieve, update, and delete projects and their associated plans.
* **Workspaces & Teams:** Manage user access, permissions, and collaboration within a workspace.
* **Data Exports & Integrations:** Automatically export plans and project data to other systems or formats for further processing.
### Who Is It For?
The magicplan REST API is designed for developers, integrators, and technical leads who need to incorporate floor plan data, project organization, and workflow automation into their existing applicationsâsuch as real estate portals, construction management platforms, insurance claim systems, and interior design tools.
### Before You Begin
* **Basic Knowledge:** Familiarity with RESTful APIs, JSON data formats, and HTTP request/response handling is recommended.
* **Account & Credentials:** Make sure you have a magicplan account with the appropriate access, and have obtained your API Key and Customer ID. [Here](/guide/getting-started/generating-api-credentials) you will learn how to generate your API Credentials.
### Next Steps
* **Getting Started:** Head over to the [Getting Started](/guide/getting-started) section to learn how to obtain credentials, authenticate your requests, and make your first API call.
* **Explore Key Resources:** Review documentation for [Projects](/guide/basic-concepts/projects), [Plan Exchange XML Format](/guide/basic-concepts/plan-exchange-xml-format), and Workspace & Teams to understand the core operations.
* **Advanced Integrations:** Once youâre comfortable with the basics, explore advanced topics like the [Custom Export Button](/guide/advanced-integrations/custom-export-button-integration), [Webhook Documentation](/guide/advanced-integrations/custom-export-button-integration/webhook-documentation-project-updated), or [Deep Linking](/guide/advanced-integrations/deep-linking).
### **Reference Documentation **
For detailed endpoint specifications, parameters, request/response models, and error codes, refer to the [API Reference](/reference).
# Authentication and Headers
### Using API Credentials
To interact with the magicplan REST API, you must include both an `API Key` and a `Customer ID` in the request headers of every API call. These credentials ensure that requests are authorized and associated with the correct magicplan account.
Unlike many APIs that use a bearer token format, the magicplan API requires two dedicated headers:
* `customer`: Your `Customer ID`
* `key`: Your `API Key`
Example Request
```bash
curl --location "https://cloud.magicplan.app/api/v2/workspace" \
--header "customer: YOUR_CUSTOMER_ID" \
--header "key: YOUR_API_KEY"
```
Replace `YOUR_CUSTOMER_ID` and `YOUR_API_KEY` with the actual values you obtained during the [Generating API Credentials](/guide/getting-started/generating-api-credentials) step.
### Accept-Language Header
You can specify the language of the API response by including the `Accept-Language` header in your request.\
If the header is not provided, the API will return responses in the default language (English).
**Example:**
```markdown
GET /api/v2/projects
Accept-Language: fr-FR
```
In this example, the API will return the response in French.
**Supported languages (format: language-COUNTRY):**
* `en-US` (English)
* `de-DE` (German)
* `fr-FR` (French)
* `pt-PT` (Portuguese)
* `es-ES` (Spanish)
### Notes & Best Practices:
* **Use HTTPS:** Always send requests over HTTPS to protect your credentials during transmission.
* **Security of Credentials:**
* Never commit your `API Key` to public repositories or share it openly.
* If you suspect that your credentials have been compromised, rotate your `API Key `immediately from the [magicplan Cloud](https://cloud.magicplan.app/integrations) dashboard.
* **Testing Connectivity:**
The `/workspace` endpoint is a good starting point to confirm that your headers are correct. A `200 OK` response with workspace details indicates that your credentials and request format are correct.
* Next Steps:
After confirming successful authentication, proceed to:
* [Making Your First API Call](/guide/getting-started/making-your-first-api-call)
* The [API Reference](/reference) for detailed endpoint specifications.
# Making Your First API Call
This page will help you verify that your credentials are set up correctly and that you can successfully communicate with the magicplan REST API.
### **Before You Begin **
Havenât generated your API credentials yet? Follow the instructions in [Generating API Credentials](/guide/getting-started/generating-api-credentials) before starting this step.
**Ensure you have the following:**
* `Customer ID:` Obtained from your magicplan Cloud account.
* `API Key:` Also generated within your magicplan Cloud account.
* **HTTP Client:** Such as curl, Postman, or a similar tool that allows you to set custom request headers and send HTTPS requests.
### **Step 1: Prepare Your Headers **
Unlike some APIs that require a single combined, encoded authorization string, the magicplan REST API uses two separate headers to authenticate requests:
* `customer`: Your `Customer ID`
* `key`: Your `API K`ey
### Step 2: Make a Test GET Request
First, confirm your connectivity by calling an endpoint that doesn't require a resource ID, such as `/workspace`:
**Example:**
```bash
curl -X GET "https://cloud.magicplan.app/api/v2/workspace" \
-H "customer: YOUR_CUSTOMER_ID" \
-H "key: YOUR_API_KEY" \
-H "Content-Type: application/json"
```
If you have a plan ID, you can also try the `/plans/get/{plan-id}` endpoint. Always use `https://` to ensure secure transmission of your credentials.
### Step 3: Check the Response
A `200 OK` status indicates a successful call. If you see workspace details or plan data returned as JSON, your credentials are valid.
Congratulations! Youâre now ready to leverage magicplanâs capabilities đ.
**Troubleshooting Tips:**
If you receive an error response, consider the following:
* **401 Unauthorized**
* **Invalid Credentials:** Double-check that your `customer` and `key` headers are correct and that the API Key has not been revoked. If issues persist, consider regenerating your credentials.
* **Insufficient Permissions:** If you included an `acting_user` parameter in your request, ensure that this user has the necessary permissions to perform the requested action. If not, update the userâs role or omit the `acting_user` parameter if itâs not required for the operation.
* **400 Bad Request or 404 Not Found**: Verify the endpointâs URL and parameters.
* **500 or Other Server Errors**: Try again after a short delay. If the issue persists, contact support.
### Step 4: Next Steps
With a successful test call, you have confirmed that your credentials are valid and your environment is set up correctly. You can now:
* Retrieve and manage projects with the `/projects` endpoints.
* Work with floor plans using the `/plans` endpoints.
* Manage teams and workspaces with the `/workspace` and `/teams` endpoints.
* Export or retrieve additional data, including images and forms.
Refer to the full [API Documentation](/reference) for in-depth details on parameters, request bodies, and available endpoints. With a working API call in place, you can start integrating magicplanâs capabilities into your existing systems and workflows.
# Generating API Credentials
To use our API, you must first generate API credentials. These credentials (your `API Key `and `Customer ID`) are required for authentication and must be included in the headers of every API request to ensure security.
### Generate API Credentials
1. **Log In**\
Access your account on the [**magicplan Cloud**](https://cloud.magicplan.app). Ensure you have the necessary permissions to manage API credentials[\*](/guide/faq#who-can-generate-api-credentials-in-magicplan).
2. **Navigate to the API & Integrations Page**
* Once logged in, locate the menu on the left-hand side.
* Click on ****[**API & Integrations Page**](https://cloud.magicplan.app/integrations)
3. **Generate API Credentials**
* Follow the instructions on the page to generate your `API Key` and `Customer ID`.
* **â ď¸ Important:** Safeguard these credentials; they will be required for all API interactions.
* Never commit your `API Key` and `Customer ID` to a public repository.
* Store them in environment variables or a secure secret management service.
### Rotate API Key
Rotating your API keys helps maintain security hygiene, ensuring that in case a key is ever compromised, it wonât pose a long-term risk. If you need to rotate your API keys:
1. Return to the [**API & Integrations Page**](https://cloud.magicplan.app/integrations) on the magicplan Cloud.
2. Follow the prompts to generate a new key.
3. Update all your systems and integrations with the new key immediately to avoid disruptions.
# File Upload Guide
File uploads use **presigned URLs**, which allow you to securely upload files directly to storage without passing them through our servers. The process consists of two steps:
1. **Request a presigned URL**
Before uploading a file, you must request a **temporary presigned URL** from the API. This URL allows direct file uploads to the storage service.
2. **Upload the File Using the Presigned URL**
Once you have the presigned URL, upload the file using a **PUT** request.
â ď¸ **Note:** The presigned URL is **time-limited** and will expire if not used promptly.
3. **Register the File in magicplan**
After the file has been uploaded, you must **register it with the project** to complete the process.
### **Supported File Types**
The API supports the following file types:
* đ **Documents**: `pdf`, `doc`, `docx`, `xls`, `xlsx`, `ppt`, `pptx`, `csv`
* đźď¸ **Images**: `jpeg`, `jpg`, `png`, `gif`, `bmp`, `svg`, `webp`
* đ ď¸ **3D Models**: `usdz`
### Common Issues & Troubleshooting
**Why is my presigned URL request failing?**
* Ensure the **project ID** is valid and you have the right permissions.
* Verify that `acting_user` is a valid email associated with your workspace.
**Why is my file upload failing?**
* Ensure youâre using the **correct HTTP method (**`PUT`**)**.
* Use the exact **headers** returned in the presigned URL response.
* Upload the file **before the presigned URL expires**.
**Why is my file not appearing in magicplan?**
* You must **register** the file using `/projects/{id}/files` after uploading.
# Getting Started
This section will guide you through the initial steps to integrate with our API and start building powerful applications.
Check the [API Reference](https://apidocs.magicplan.app/reference)
Hereâs what youâll learn:
* [**How to generate API credentials**](/guide/getting-started/generating-api-credentials): Securely generate the API key and secret needed to access the magicplan API.
* [**How to authenticate requests**](/guide/getting-started/authentication-and-headers): Understand how to use your credentials to securely interact with the API.
* [**How to make your first API call**](/guide/getting-started/making-your-first-api-call): Test your integration by making a sample request to the magicplan API.
By the end of this section, youâll have everything set up to explore the full range of features offered by the magicplan API. Letâs get started!
# Example 2: Retrieving and Displaying Project Information
This scenario covers how to fetch and present comprehensive project data. Itâs useful for dashboards, reporting interfaces, and any environment where users or systems need at-a-glance updates on project status, associated files, and plan details.
**Process:**
1. [**Get All Projects**:](/reference#tag/projects/GET/projects)
* **Endpoint:** `GET /projects`
* **Action:** Retrieve a list of all available projects for high-level overviews or dashboards.
2. [**Get a Specific Project**:](/reference#tag/projects/GET/projects/{id})
* **Endpoint:** `GET /projects/{id}`
* **Action:** Drill down into a particular projectâs details, including metadata and IDs of related files and plans.
3. **Retrieve **[**Plans**](/reference#tag/projects/GET/projects/{id}/plan)** and **[**Files**](/reference#tag/projects/GET/projects/{id}/files):
* **Endpoints:**
* `GET /projects/{id}/plan` to access the projectâs plan data.
* `GET /projects/{id}/files` to see all associated files.
* **Action:** Provide users or other systems with visual references, floor plans, and relevant documentation.
---
**Example Use Case:**\
An internal dashboard that allows managers to view a projectâs current phase, review its floor plan, and confirm all required documents are on file before scheduling site visits.
# Plan
### Example
```xml
âŚ
```
A ``-element represents a floor plan you see in magicplan as part of a magicplan Project. It is the root element of the XML.
| Attribute | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | A unique identifier of the floor plan as assigned by magicplan. |
| `name` | The human-readable name of the floor plan. It is in sync with the magicplan project name. |
| `type` | The type of project: `0` for residential, `1` for commercial |
| `interiorWallWidth` | The width of interior walls in meters as specified by the user. The actual wall width in the file may vary slightly from wall to wall due to incompatible measurements entered by the user. \[Default 0.12] |
| `exteriorWallWidth` | The width of exterior walls. \[Default 0.25] |
| `country` | The country the building is located in ([ISO 3166](https://en.wikipedia.org/wiki/ISO_3166-1)). |
### XML Schema
```xml
```
# Wall
```xml
exterior
```
The ``-element represents a wall on the current floor.
The coordinates of one vertex (corner) of a broken line representing a wall in its exploded representation. Points are positioned on an imaginary line located at the center of the wall. To compute the length of the wall surface you need to offset these points from the center of the wall to the wallâs surface.
| Attribute | Description |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x` | The corrected horizontal position of the corner relatively to the center of the project, in meters, as a floating point number. This value should be used when drawing an assembled project. |
| `y` | The corrected vertical position of the corner relatively to the center of the project, in meters, as a floating point number. This value should be used when drawing an assembled project. |
| `height` | The height of the wall in meters, as a floating point number. |
#### Type
The type can be either `exterior` or `interior`. See below more about the difference between these two types.
#### Interior vs. exterior wall
If there is a room attached to the other side of the wall, the part that is connected is an interior wall (1).
If there is no adjacent room the wall is an exterior wall (2).
#### Wall thickness
The thickness of the wall can be obtained from the ``-element (see [Plan](/guide/basic-concepts/plan-exchange-xml-format/plan)) and its respective attributes `interiorWallWidth` (1) and `exteriorWallWidth` (2).
On some occasion those values are overwritten. In this case please look at the parent ``-element's symbol instance and its properties. For more information, see [SymbolInstance, Floor](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance/floor).
### XML Schema
```xml
```
# Window
```xml
```
The ``-element represents a window on the current floor. Each window is only represented once.
| Attribute | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `symbolInstance` | The unique identifier of the `` [element](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance) containing data attached to this window. The symbol instance contains the symbol ID. |
| `x1` | The horizontal position of the first extremity of the window relatively to the center of the project, in meters, as a floating point number. |
| `y1` | The vertical position of the first extremity of the window relatively to the center of the project, in meters, as a floating point number. |
| `x2` | The horizontal position of the second extremity of the window relatively to the center of the project, in meters, as a floating point number. |
| `y2` | The vertical position of the second extremity of the window relatively to the center of the project, in meters, as a floating point number. |
| `width` | The width of the window in meters represented by a floating point number. This value should be used when drawing an assembled project. |
| `depth` | The depth of the window in meters, as a floating point number. |
| `height` | The height of the window in meters, as a floating point number. |
| `orientation` | The orientation of the window. The orientation is a number between 0 and 3 specifying which way the window is facing and if it opens to the left or the right. This value should be used when drawing an assembled project. |
### XML Schema
```xml
```
# Exploded Floor
```xml
⌠⌠⌠âŚ
```
The ``-element represents the whole floor with absolute coordinates. Walls and doors are only described once in this representation and are not grouped per room.
See also Rooms if you prefer a description per room.
### XML Schema
```xml
```
# Wide Opening
```xml
```
The ``-element represents a wall that has been removed in the current room.
| Attribute | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `symbolInstance` | The unique identifier of the `` [element](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance) containing data attached to this opening. The symbol instance contains the symbol ID. |
| `point` | The index 0-based of the `` element starting the opening. |
| `snappedPosition` | The corrected relative position of the opening represented by a floating point number between 0.0 and 1.0. This value should be used when drawing an assembled project. |
| `snappedWidth` | The corrected width of the opening in meters represented by a floating point number. This value should be used when drawing an assembled project. |
| `snappedDepth` | The corrected depth of the opening in meters represented by a floating point number. This value should be used when drawing an assembled project. |
| `snappedHeight` | The corrected height of the opening in meters represented by a floating point number. This value should be used when drawing an assembled project. |
### XML Schema
```xml
```
# Room
```xml
⌠âŚ
```
Each ``-element can contain multiple rooms (``).
The ``-element describes each room individually. See also [Exploded Floor](/guide/basic-concepts/plan-exchange-xml-format/exploded-floor) if you prefer a description of all the rooms on the whole floor.
| Attribute | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid` | Unique id of a room as assigned by magicplan in order to track a room. |
| `type` | The type of room. The text description may be part of the [predefined list of rooms](/guide/basic-concepts/plan-exchange-xml-format/standardized-plan-elements/predefined-list-of-rooms) in English or an ad hoc description entered by the user in any language. |
| `x` | The horizontal position of the center of the room on the project in meters as a floating point number. |
| `y` | The vertical position of the center of the room on the project in meters as a floating point number. |
| `rotation` | The angle of the floor in radians. |
#### Optional attributes
| Attribute | Description |
| ----------- | --------------------------------------- |
| `perimeter` | The perimeter of the floor in meters. |
| `area` | The area of the floor in square meters. |
#### XML Schema
```xml
```
# Window
```xml
```
The ``-element represents a window located on a wall in the current room. If the window is connecting two rooms, it is represented once on each wall of each room.
| Attribute | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `symbolInstance` | The unique identifier of the `` [element](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance) containing data attached to this window. The symbol instance contains the symbol ID. |
| `point` | The index 0-based of the `` element starting the wall containing the window. |
| `snappedPosition` | The corrected relative position of the center of the window on the wall represented by a floating point number between 0.0 and 1.0. This value should be used when drawing an assembled project. |
| `snappedWidth` | The corrected width of the window in meters represented by a floating point number. This value should be used when drawing an assembled project. |
| `snappedOrientation` | The corrected orientation of the window after the rooms are assembled. Inconsistent window orientations are unified across rooms and may differ from the original orientation. This value should be used when drawing an assembled project. The orientation is a number between 0 and 3 specifying which way the window is facing and if it opens to the left or the right. |
| `insetY` | Floating point number in meters to determine how far the object is into the wall. Positive values show that the object goes away from the middle of the wall and into the room. Negative values show that the object goes further inside the wall. |
### XML Schema
```xml
```
# Polygons
```xml
⌠âŚ
```
Polygon coordinates are stored in a ``-element under the polygon ``. The ``-element contains one `` for each point of the polygon, specifying its x and y coordinates.
For more information on polygons, see also [SymbolInstance](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance/polygon).
| Attribute | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------ |
| `x` | The horizontal position of the point relatively to the center of the floor, in meters, as a floating point number. |
| `y` | The vertical position of the corner relatively to the center of the floor, in meters, as a floating point number. |
### XML Schema
```xml
```
# Values
```xml
Example note
```
The ``-element contains a list of predefined or custom attributes attached to a symbol instance (``), a point inside a room (``), a room (``), a floor or ``.
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------- |
| `key` | The unique identifier of the attributes, as defined by magicplan or the symbol xml. |
### XML Schema
```xml
```
# Furniture
```xml
2.0000001img0.pngThese are notesm3
```
# Available types of floor
| Code | Description |
| ------ | -------------------------------------------------- |
| `-52` | Higher Ground (between Ground Floor and 1st Floor) |
| `-51` | Semi Basement (between basement and ground floor) |
| `-3` | Basement - Level 3 |
| `-2` | Basement - Level 2 |
| `-1` | Basement - Level 1 |
| `0` | Ground Floor |
| `1` | 1st Floor |
| `2` | 2nd Floor |
| `3` | 3rd Floor |
| ... | |
| `50` | 50th Floor |
| `1000` | Roof |
| `2000` | Land survey |
# Plan
Information pertaining to a plan, a room or a specific point inside a room are currently not stored in a symbol instance but on the element itself.
```xml
2018-05-04
```
# Wall
Information pertaining to a plan, a room or a specific point inside a room are currently not stored in a symbol instance but on the element itself.
The information are stored in the starting point of the corresponding wall.
```xml
3img1.pngNotes
```
# Plan Exchange XML Format
The following section describes the format of a magicplan Exchange XML file that can be exported for example using a [Custom Export](/guide/advanced-integrations/custom-export-button-integration) button.
The ExportConfigs format denominator is `mp`.
# Polygon
```plaintext
10.20000003311000000FF0.1 âŚ
```
# Rotation
The following discussion is made under the assumption that the Z-axis points upwards in the 3D modeling software. In case is the Y-axis the one pointing upwards, swap the letter Z with the letter Y (and vice versa) in the subsequent sections.
### Floor items
For floor items it is worth making a distinction between axis of rotation.
**Around Z-axis**: An angle of rotation around this axis can be assigned within the app while editing the project in 2D and it's trivially the only rotation visible in the 2D. Regarding the initial orientation around the Z-axis two different cases exist:
* **the item does not exist inside magicplan yet:** the initial rotation around the Z-axis is then arbitrary.
* **the item exists already as a magiplan symbol:** it is important to make sure that the initial rotation of the 3D item corresponds to that of the 2D symbol. Consider the following picture, representing a bed item in magicplan:
Taking into account the coordinate system used inside magicplan (top right in the next picture), it is easy to see that the headboard of the bed points towards the negative Y-axis (or, on the contrary, the foot points towards the positive Y-axis): the 3D model of the bed, must have the same orientation.
**Around X/Y-axis**: The model should be built in such a way as to guarantee that the surface of the item that touches the ground (where the pivot is placed) lies on the XY projecte.
### Wall items
To define wall-mounted item rotation, it is important to first define the normal of such an item:
The **normal** of a wall-mounted item corresponds to the normal of the back plane of the item pointing away from the wall where the item is placed.
The back plane of the item is the one used to define the position of the pivot.
The default orientation of an item should be such that its normal points toward the negative Y-axis (with respect to magicplan coordinate system).
# OAuth 2.0
**magicplan supports OAuth 2.0 with the Authorization Code grant type.** If your application also supports OAuth, you can contact the magicplan Integrations team to request the configuration of OAuth for your main workspace.
To see how OAuth works within magicplan, you can enable the **Floorplanner** integration under the [**API & Integrations**](https://cloud.magicplan.app/integrations) section on the magicplan Cloud. This allows you to evaluate whether OAuth is a suitable option for your integration as well.
đ **Coming soon:** We will soon publish documentation on how you can set up OAuth yourself. Stay tuned!
# Estimator API Endpoints
**The Estimator API is officially released! **These endpoints allow you to retrieve and manage estimator data associated with your magicplan projects. This enables seamless integration with external systems such as CRMs, ERPs, or invoicing tools.
## đ Overview
With the Estimator API, you can:
* Access detailed estimate data for any project
* Sync estimates into third-party systems
* Reconstruct the nested estimate layout shown in the magicplan Cloud interface
To explore full schemas and request/response examples, please check the [API Reference](/reference#tag/estimates)[.](/reference#tag/estimates)
---
## Integration Example: Syncing an Estimate into an ERP System
In this example, we walk through how a backend service might use the Estimator API to pull the latest estimate from a magicplan project and push that data into an ERP system for invoicing.
**Use Case**
When a new estimate is created or finalized in magicplan, sync it to our ERP as a draft invoice_._
### Step 1: Authenticate Your Request
Every request to the Estimator API requires two headers. These credentials authenticate your workspace access. Ensure you have obtained your API credentials as described on the page below:
[Authentication and Headers](/guide/getting-started/authentication-and-headers)
### Step 2: Retrieve the Estimate for a Project
Make a request to list estimates (optional filtering, if needed), and then fetch the detailed estimate.
```bash
GET /api/v2/projects/{project_id}/estimates/{estimate_id} HTTP/1.1
Host: cloud.magicplan.app
customer: YOUR_CUSTOMER_ID
key: YOUR_API_KEY
```
This returns a JSON response containing:
* Customer information (name, contact, address)
* Estimate metadata (status, currency, issue date)
* Structured list of estimate items (each with cost breakdowns)
* Totals including labor, materials, tax, discounts
### Step 3: Rebuild Nested Estimate Items
In the response, `estimate.items` is a flat list of all positions and groups. Each item contains:
* A `type` field: either `"group"` or `"position"`
* A `parent_id`: referencing another item's `id` (or `null` if it's a top-level item)
To reconstruct the **hierarchical structure** seen in the magicplan UI:
1. Parse the flat list into a dictionary keyed by `id`
2. Group items by their `parent_id`
3. Recursively nest children into their parents
This will allow you to render groups and positions exactly as users see them in the web interface, preserving sections, sub-sections, and line-item relationships.
### Step 4: Transform and Sync to ERP
Once retrieved, the estimate can be transformed into your ERP systemâs required format. Then send this to your ERP or accounting backend.
---
### đ Tips for Developers
* Use the `estimate_unique_id` as a stable external reference
* Use the `modified` timestamp to detect changes and avoid unnecessary syncs
* The nested structure enables flexible rendering in web, mobile, or PDF outputs
* Item types like `group` can be used to show section headers or collapsible UIs
# Export
The 3D model should be exported as such:
* geometry export format .OBJ
* material export format .MTL
* exported file size < 1MB (on average)
* set the Y-axis as the upwards axis in the export settings
### Geometry and material
In case an item consists of multiple parts, all its parts must be exported into a single .OBJ file.
It is important to export, together with vertices and faces (`v` and `f`), the vertices normals `vn` and texture coordinates `vt`.
The materials used in the example (e.g. `usemtl fabric` ) are defined in the .MTL file associated with the object. There should be a single .mtl file per item. Inside the file different material definitions can exist.
The correct assignment of all the values to the appropriate parameters will be taken care of by the software performing the export. In case a texture is to be applied to the item, it is important only to note (and make sure) that the parameters concerning textures are present inside the file.
For example, in the example there have been defined:
a diffuse texture for the fabric material
`map_Kd BlakeGreyWashRattan_bumf_Map.png`
a diffuse texture for the fabric material
`map_Bump -s 3.000000 4.000000 1.000000 BlakeGreyWashTeak_bum_Map.png`
`map_Kd -s 2.999999 3.999998 0.000000 BlakeGreyWashTeak_dif_Map.png`
### Example:
Blake Grey Wash 68" Media Console
```plaintext
...
o Door
v -359.413513 285.842468 226.055450 v -162.681000 285.842468 226.055450 ...
vt -0.000000 1.000000
vt -0.000000 0.000000
vt 1.000000 0.000000
...
vn 0.000000 0.000000 -1.000000
vn 0.000000 0.000000 1.000000
...
usemtl fabric
f 34/33/2 36/34/2 33/35/2
f 33/36/3 38/37/3 37/38/3
...
o Chestofdrawers
v -825.644714 199.242035 -232.641174 v -825.644714 199.241974 199.700531 ...
vt 0.103900
vt 0.068700
...
vn 0.000000
vn 1.000000
...
usemtl wood
f 34/33/2 36/34/2 33/35/2
f 33/36/3 38/37/3 37/38/3
...
```
Material Blake Grey Wash 68" Media Console
```plaintext
newmtl fabric
Ns 96.078431
Ka 1.000000 1.000000 1.000000
Kd 0.640000 0.640000 0.640000
Ks 0.500000 0.500000 0.500000
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 0
map_Kd BlakeGreyWashRattan_bumf_Map.png
newmtl wood
Ns 96.078431
Ka 1.000000 1.000000 1.000000
Kd 0.640000 0.640000 0.640000
Ks 0.500000 0.500000 0.500000
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 0
map_Bump -s 3.000000 4.000000 1.000000 BlakeGreyWashTeak_bum_Map.png
map_Kd -s 2.999999 3.999998 0.000000 BlakeGreyWashTeak_dif_Map.png
```
# Deep Linking
Deep linking allows users to navigate directly from other apps to the magicplan app.
## Open a Project
```plaintext
magicplanstd://project/{projectId}
```
This URL will automatically open the magicplan app and open the project identified by the given `projectId` .
If the project has not been downloaded yet to the app and an internet connection is available, it will download and open the project automatically.
#### **Example Usage**
If your application uses the [Create a new project REST API](/reference#tag/projects/POST/projects)[ ](/reference/tag/projects/POST/projects)to create a magicplan project directly for your user, you can send your user a notification email with the deep link to automatically download and open the project.
---
### Create a Project
```plaintext
magicplanstd://create-project?name=My New Project&external_reference_id=ERP12345
```
In addition to the [Create a new project REST API](/reference#tag/projects/POST/projects) that is used to create a magicplan project from server to server, you can also create a project locally from app-to-app.
| Parameter | Description | Mandatory | Data Type |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------- |
| name | The Project Name | Yes | String |
| target\_workgroup\_id | Specify the workspace or team where the project will be defined. | No | String |
| external\_reference\_id | The identifier of your local project that has been assigned to the magicplan project.This is used to link customer project and magicplan projects. | No | String |
| address\_1 | Address: Street | No | String |
| city | Address: City | No | String |
| zip | Address: ZIP Code | No | String |
| country | Country | No | String |
| longitude | GPS Coordinate | No | Float |
| latitude | GPS Coordinate | No | Float |
# Link Project
The Link Project webhook enables dynamic project selection during export from magicplan, offering a smoother integration when a project hasnât been linked in advance.
While not mandatory, configuring this webhook allows your users to associate magicplan data with an existing project in your system â or even create a new one â directly within the export flow.
### đš How the Project Listing Webhook Works
If you configure a `listing_url` for your workspace, magicplan will:
1. **Call your endpoint** to retrieve a list of your available projects.
2. **Display this list** to the user during the publishing process.
3. **Send back the selected project** in the subsequent API calls to your system.
This allows users to select the correct project context at the moment of export.
Only the **first 20 projects** returned by your service are shown in the magicplan interface. For best results, filter the list to show the **most relevant projects**, such as:
* Recently accessed or modified projects
* Projects located closest to the property (geo-location relevance)
magicplan provides the following fields to help with filtering: latitude, longitude, address.
To **warn users when an existing project may be overwritten**, include the following element in your XML response:
```xml
1
```
---
##### đ Creating a New Project
If no suitable project exists yet, you can use this service to allow users to create a new project in your application during the publishing process.
To support this:
* Add a **"New Project"** placeholder to the beginning or end of the project list.
* Assign it a recognizable dummy ID, such as `0`, that does not match any real project.
* When selected, your backend should:
1. Trigger the creation of a new project.
2. Return the newly created project so it appears in the list on subsequent exports.
This enables your users to link new or existing projects seamlessly, all within the magicplan publishing interface.
---
#### đ§ How to Set Up Your Listing URL
To configure your webhook, make a `PUT`** request to the **[Workspace API ](/reference#tag/workspace/PUT/workspace)and set the `listing_url` field with the URL of your endpoint.
---
### đ Sequence of Events
Link Project is part of the workflow that allows users to select or create a project within your system before exporting from magicplan.
1. **User Initiates Export**\
The user taps the export button in magicplan.
2. **magicplan Calls Your Listing URL**\
The `listing_url` is triggered to retrieve a list of projects from your system.\
This list is shown to the user in the app.
3. **User Selects a Project**\
The user chooses an existing project from the list or creates a new one (if supported).
4. **magicplan Calls Your **[**Authorize URL**](/guide/advanced-integrations/custom-export-button-integration/authorize-export-from-magicplan) _(Optional)_\
The selected `project_id` is sent to your `authorize_url`.\
If this call is successful, the export proceeds.
5. **magicplan Triggers **[**Webhook URL**](/guide/advanced-integrations/custom-export-button-integration/webhook-documentation-project-updated)\
The final export payload is sent to your `webhook_url` (if configured),\
including the selected project ID and associated files.
---
##### **HTTP Request**
* **Method**: `GET`
* **Endpoint**: `https://yourserverurl/getlistings`
---
##### **Request Parameter**
| Parameter | Required | Description |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| key | Yes | The magicplan API key provided by magicplan |
| email | Yes | The user's email address. |
| ref | No | The unique reference string that you supplied when creating the user. Absent if no reference was supplied. |
| latitude | Yes | The latitude of the property. |
| longitude | Yes | The longitude of the property. |
| street | Yes | The street number and name of the property. |
| city | Yes | The city of the property. |
| province | Yes | The province of the property. |
| country | Yes | The country of the acting user. |
| countryname | Yes | The country code of the property. |
| postalcode | Yes | The postal/zip code of the property. |
---
##### **Response Format**
| XML tag | Value | |
| ----------- | ----- | ------------------------------------------------- |
| `` | 0 | The request was a success. |
| | 1 | The API key is invalid. |
| | 2 | A parameter is missing or invalid. |
| | 14 | The given user reference or email does not exist. |
| `` | | see below |
Each `` element encapsulates a project.
| Attribute | Description |
| --------------- | ----------------------------------------------------------------------- |
| `id` | The unique identifier of a project. |
| `title` | The title of a project. magicplan will present this string to the user. |
| `warnOnReplace` | Warns the user that the operation will overwrite an existing project. |
---
#### Example Request
```plaintext
GET /getlistings?key=3b2abe7cd80d&
email=john.doe%40example.com&
latitude=40.7143528&
longitude=-74.0059731&
street=1617++Toy+Avenue&
city=Ajax+Pickering&
province=Ontario&
country=Canada&
postalcode=L1W+3N9 HTTP/1.1
Host: yourserverurl
```
---
#### Xml Response Schema
```xml
```
# Example 1: Automate File Processing with Webhooks
This workflow automates file handling when a project is completed in magicplan, ensuring immediate processing of files while adhering to webhook requirements.
**Steps**:
1. **Create Project**:\
Use the `external_reference_id` parameter in the [**Create Project API**](/reference#tag/projects/POST/projects) to link the magicplan project to your local system.
2. **Export Trigger:**
* Once the project appears in the user's app, they can open the magicplan app.
* Upon completing the project, the user presses the _Custom Export_ button, signaling that the project is ready for export.
3. **Webhook Notification**:\
magicplan sends a `POST` request to your `webhook_url`, including:
* The `listing` parameter, which identifies the local project linked to the magicplan project.
* File URLs (**valid for 60 minutes**).
* Additional project metadata.
4. **File Queuing and Downloading**:\
Your system queues the file URLs and downloads them as soon as possible.
5. **Webhook Response**:
* If your webhook responds with status `0`, magicplan displays success to the user.
* If the webhook fails or does not respond with status `0`, the app shows an error to the user, allowing them to retry.
6. **Fallback via Project Files API** _(Optional)_:\
If the webhook fails entirely, files can still be fetched using the [**Project Files API**](/reference#tag/projects/GET/projects/{id}/files) as a backup solution.
---
#### Use Case Example
A construction company automatically imports site reports and floor plans into their project management system after export.
# Example 3: Multi-Step Workflow with Notifications
This workflow enhances collaboration by combining file export with notifications to stakeholders.
**Steps**:
1. **Create Project**:\
Use the `external_reference_id` parameter in the [**Create Project API**](/reference#tag/projects/POST/projects) to link the magicplan project to your local system.
2. **Export Trigger:**
* Once the project appears in the user's app, they can open the magicplan app.
* Upon completing the project, the user presses the _Custom Export_ button, signaling that the project is ready for export.
3. **Webhook Notification**:\
magicplan sends a `POST` request to your `webhook_url`, including:
* The `listing` parameter, which identifies the local project linked to the magicplan project.
* File URLs (**valid for 60 minutes**).
* Additional project metadata.
4. **File Queuing and Downloading**:\
Your system queues the file URLs and downloads them as soon as possible.
5. **Notifications**:\
Notify stakeholders (e.g., project managers, clients) via email, Slack, or push notifications.
6. **Webhook Response**:
* Status `0`: Indicates success and displays a confirmation message in the app.
* Other statuses: The user sees an error and can retry.
---
#### Use Case Example
A project manager is notified automatically when floor plans are exported, streamlining review processes.
# Advanced Integrations
This section provides detailed guides and best practices for implementing complex workflows with the magicplan API. These integrations allow you to extend the capabilities of magicplan and tailor it to your specific business needs.
Hereâs what youâll learn:
* [**OAuth 2.0 Authentication**](/guide/advanced-integrations/oauth-20): How to implement OAuth 2.0 for secure and scalable access to the magicplan API.
* [**Single Sign-On (SSO)**](/guide/advanced-integrations/sso): Steps to set up SSO for seamless user authentication across your systems.
* [**Custom Export Button Integration**](/guide/advanced-integrations/custom-export-button-integration):
* Learn how to configure a custom export button to trigger workflows and receive project data directly into your system.
* Explore real-world example workflows to understand how the custom export button can automate notifications, synchronize data, and enhance your existing processes.
* [**Deep Linking**](/guide/advanced-integrations/deep-linking): Enable direct navigation to specific features or projects within the magicplan app, streamlining your user workflows.
By the end of this section, youâll have a comprehensive understanding of how to leverage these advanced integrations to enhance your workflows and connect magicplan seamlessly with your existing tools and platforms.
# Example 7: Custom Forms Integration
This integration allows you to create **custom forms (questionnaires)** directly within the **magicplan Cloud**. These forms can be accessed by all magicplan users in your workspace, enabling you to collect structured project-specific data tailored to your workflows.
**Steps**:
1. **Define Your Form Requirements**:
* Decide on the purpose of the custom form and the information you need to collect.
* Identify the input fields required for your form, such as text inputs, dropdowns, checkboxes, or date pickers.
2. **Create the Custom Form in magicplan Cloud**:
* Log in to the **magicplan Cloud**.
* Navigate to the **Forms** section.
* Use the interface to create your custom form:
* Add the required fields and configure their labels and formats.
* Organize the form layout to ensure it is user-friendly.
* Save the form once it is complete.
3. **Publish the Form to Your Workspace**:
* Publish the custom form to your workspace to make it accessible to all users.
* Once published, all workspace members can access and use the form when working on their projects.
4. **Retrieve Form Data via APIs**:
* [**Plan Forms API**](/reference#tag/plans/GET/plans/forms/{id}): Use this API to retrieve all the forms applied to a specific plan. This allows you to see which custom forms are associated with the plan and their structure.
* [**Project Plan API**](/reference#tag/projects/GET/projects/{id}/plan): This API returns the plan, including all the questions answered from the forms that were published. It provides an efficient way to collect user-submitted data for further processing in your system.
---
#### Use case
A heating company creates a custom form to inspect heating systems during site visits. The form includes questions about the condition of the heating unit, the type of system installed, and any maintenance or repairs required. Technicians use the form in the magicplan app during inspections to ensure all relevant data is collected.
After the site visit, the heating company retrieves the answered form data using the **Project Plan API** and automatically updates their internal CRM with the collected information for follow-up and scheduling future maintenance tasks.
---
**Note:**
The workflow for creating **custom object lists** is quite similar. Instead of navigating to the **Forms** section, you would go to the **Objects** section in the magicplan Cloud and define the attributes for each object. Once published, the object list will also be available to all users in your workspace.
# Example 5: Export and Visualize
This workflow uses exported files to generate dashboards and actionable insights.
**Steps**:
1. **Create Project**:\
Use the `external_reference_id` parameter in the [**Create Project API**](/reference#tag/projects/POST/projects) to link the magicplan project to your local system.
2. **Export Trigger:**
* Once the project appears in the user's app, they can open the magicplan app.
* Upon completing the project, the user presses the _Custom Export_ button, signaling that the project is ready for export.
3. **Webhook Notification**:\
magicplan sends a `POST` request to your `webhook_url`, including:
* The `listing` parameter, which identifies the local project linked to the magicplan project.
* File URLs (**valid for 60 minutes**).
* Additional project metadata.
4. **Data Extraction**:\
Extract key details (e.g., room dimensions, materials, costs) from the downloaded files.
5. **Dashboard Creation**:\
Visualize the extracted data in dashboards, highlighting:
* Resource usage.
* Completion rates.
* Project progress.
6. **Webhook Response**:
* Status `0`: Success, with a confirmation displayed to the user.
* Other statuses: The user is shown an error and can retry the export.
---
#### Use Case Example
A business analytics team tracks project performance and visualizes insights for management.
# magicplan MCP
**MCP Server**
The **magicplan MCP server** lets AI assistants like Claude and ChatGPT read your magicplan workspace and reason over it in a conversation. It implements the [Model Context Protocol](https://modelcontextprotocol.io), the open standard for connecting AI clients to external data. Where the REST API is for your own software, the MCP server is for AI assistants.
## **What Can You Do with It?**
Ask an assistant about your workspace in plain language and let it pull the data it needs:
* **Projects and floor plans**Â â a project's details, the field data on its plan, measured areas by floor and room, and the forms captured on site.
* **Restoration documentation**Â â the drying history from moisture instruments and the photos attached to each part of the building, localized to their room.
* **Files and estimates**Â â attached files, and estimates down to individual line items and cost totals.
It is especially suited to property restoration, where claim details, moisture readings, photo evidence, and an estimate all need to be read together.
## **Before You Begin**
Make sure you have:
* AÂ **magicplan account**Â with access to the workspace you want to connect.
* Your workspace's **Customer ID** and **API key**, found under **API & Integrations** in your workspace settings (the same credentials used for the REST API).
* An **MCP-capable client**, such as Claude or ChatGPT.
## **How to Connect**
The server connects at:
```plaintext
https://cloud.magicplan.app/mcp
```
The steps depend on your client, but the flow is the same everywhere:
1. **Add the connector.** In your assistant's settings, add a custom connector (in Claude, under **Settings â Connectors**) and paste the URL above.
2. **Authorize the workspace.** Your assistant opens a magicplan sign-in page asking for your **Customer ID** and **API key**. Enter both and confirm. Your API key is never shared with the assistant.
3. **Start working.**Â Ask the assistant about a project by name and it takes it from there.
A connection acts as one workspace. To connect another, authorize again with that workspace's credentials.
## **Good to Know**
* The server is **read-only** â it never changes anything in your workspace.
* Responses are shaped for AI, not for parity with the REST API. Large payloads like a full floor plan are compacted so they stay usable in a conversation.
* Your assistant shows the current list of tools it can call â that list is the definitive reference for what is available.
## **Next Steps**
Connect your workspace and ask your assistant to summarize one of your projects. For programmatic integrations, see the [REST API reference](https://apidocs.magicplan.app/reference).
# Contact & Support
If you need help integrating the magicplan REST API, have feature requests, or want to report bugs, we offer multiple support channels:
* **Email Support:**\
For technical issues, troubleshooting, or general questions, email our integration team at .
**Tip: **Include details like request samples, error codes, or workspace/project IDs to help us assist you more efficiently.
* **Community Feedback & Requests (Canny):**\
Visit our [Canny board](https://magicplan.canny.io/) to:
* Submit feature requests
* Report bugs
* Vote on and discuss ideas from other users\
This platform helps us prioritize improvements based on community interest.
* **Documentation & Reference:**\
Before reaching out, review our [API Reference](https://magicplan.apidocumentation.com/reference) , [Integration guides](/guide/advanced-integrations) or the [FAQ](/guide/faq) section in this documentation. Many common questions are addressed in the examples and explanations provided.
# Projects
The Projects API provides a suite of endpoints for managing the full lifecycle of your projects within the magicplan system. From creating new projects and retrieving existing ones, to updating project details, archiving them for safekeeping, and ultimately deleting them if needed, this API enables streamlined, programmatic control over your project data. Additionally, you can handle related filesâ such as floor plans, images, or other attachmentsâvia pre-signed upload URLs and direct file registration.
### Key Capabilities
* **Lifecycle Management**: Easily create new projects, fetch details of existing ones, update their information as scope changes, and archive or delete them when theyâre no longer needed.
* **Plan Retrieval**: Access detailed project plans, including floor plans and spatial data, to support visualization, analysis, and reporting tasks.
* **File Management**: Securely upload and link files to projects using pre-signed URLs for authenticated, reliable file handling.
* **Workflow Automation**: Combine multiple endpoints to automate tasks. For example, automatically create a project when a property is listed, upload floor plan PDFs and related documents, gather user inputs, and later archive completed projects for a clean, organized workspace.
### **Who Should Use This API? **
Developers and integrators who need to programmatically manage project data within their applications or services will find value in the Projects API. This includes:
* Real estate platforms integrating floor plan data into listings.
* Construction or remodeling services that track changes over the projectâs lifecycle.
* Systems syncing project data with CRMs, ERPs, or analytics tools.
For detailed, step-by-step scenarios and best practices, see the examples on the following pages.
# Example 1: Creating and Preparing a Project
This workflow outlines how to set up a new project from scratch, populate it with metadata, and attach relevant files. This is a typical starting point for new projects that require consistent data inputs, such as floor plans, images, and supporting documents.
**Process:**
1. [**Create a Project**:](/reference#tag/projects/POST/projects)
* **Endpoint:** `POST /projects`
* **Action:** Provide initial metadata, such as project name and description.
* **Result:** Returns a new project ID for subsequent actions.
2. [**Update Project Details**:](/reference#tag/projects/PUT/projects/{id})
* **Endpoint:** `PUT /projects/{id}`
* **Action:** Add or modify attributes like project owner, location details, or custom fields.
* **Result:** Ensures the project has all necessary context before proceeding.
3. [**Add Files to the Project**:](/reference#tag/projects/POST/projects/{id}/files/temporary-presigned-url)
* **Endpoints:**
* `POST /projects/{id}/files/temporary-presigned-url` (Request a URL)
* Upload the file directly to the returned URL.
* `POST /projects/{id}/files` ([Register the file](/reference#tag/projects/POST/projects/{id}/files))
* **Action:** Securely upload documents (e.g., PDFs, images) and associate them with the project.
* **Result:** The project is now enriched with essential files accessible via API or UI.
---
**Example Use Case:**\
A construction management app that needs to store floor plan PDFs and material lists immediately after creating a project.
# Door
```xml
```
The ``-element represents a door on the current floor. Each door is only represented once.
**Wall items:** Internally magicplan differentiates between wall items and pieces of furniture. Pieces of furniture (chairs, tables, kitchen sink, etc.) are placed freely inside a room while wall items (doors, windows, radiators, etc.) are always placed in relation to a wall.\
In the project (``) as well as in individual rooms (``) all wall items, except for windows, are expressed as a ``-element.
| Attribute | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `symbolInstance` | The unique identifier of the `` [element](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance) containing data attached to this door. The symbol instance contains the symbol ID. |
| `x1` | The horizontal position of the first extremity of the door relatively to the center of the project, in meters, as a floating point number. |
| `y1` | The vertical position of the first extremity of the door relatively to the center of the project, in meters, as a floating point number. |
| `x2` | The horizontal position of the second extremity of the door relatively to the center of the project, in meters, as a floating point number. |
| `y2` | The vertical position of the second extremity of the door relatively to the center of the project, in meters, as a floating point number. |
| `width` | The width of the door in meters represented by a floating point number. This value should be used when drawing an assembled project. |
| `depth` | The depth of the door in meters, as a floating point number. |
| `height` | The height of the door in meters, as a floating point number. |
| `orientation` | The orientation of the door. Inconsistent door orientations are unified across rooms and may differ from the original orientation. This value should be used when drawing an assembled project. The orientation is a number between 0 and 3 obtained by combining two bit values: bit 0, set if door opens towards the outside; bit 1, set if the door opens to the right. |
### XML Schema
```xml
```
# Point
```xml
```
The ``-element represents corner in the current room (the intersection of two walls). Points are positioned on an imaginary line located at the center of the wall. To compute the length of the wall surface you need to offset these points from the center of the wall to the wallâs surface.
The list of points are ordered clockwise.
| Attribute | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `snappedX` | The corrected horizontal position of the corner relatively to the center of the room, in meters, as a floating point number. This value should be used when drawing an assembled project. |
| `snappedY` | The corrected vertical position of the corner relatively to the center of the room, in meters, as a floating point number. This value should be used when drawing an assembled project. |
### XML Schema
```xml
```
# Furniture
```xml
```
The ``-element represents a piece of furniture in the current room.
| Attribute | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `symbolInstance` | The unique identifier of the `` [element](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance) containing data attached to this pience of furniture. The symbol instance contains the symbol ID. |
| `snappedX` | The horizontal position of the piece of furniture corrected relatively to the center of the project, in meters, as a floating point number. This value should be used when drawing an assembled project. |
| `snappedY` | The vertical position of the piece of furniture corrected relatively to the center of the room, in meters, as a floating point number. This value should be used when drawing an assembled project. |
| `snappedWidth` | The width of the piece of furniture in meters corrected relatively to the center of the room, represented by a floating point number. This value should be used when drawing an assembled project. |
| `snappedDepth` | The depth of the piece of furniture in meters corrected relatively to the center of the room, represented by a floating point number. This value should be used when drawing an assembled project. |
| `angle` | The angle of the piece of furniture in radians, as a floating point number. |
### XML Schema
```xml
```
# References
Symbol instances are referenced by ``, `` and `` elements. A single ``-element can be referred to by multiple elements when all these elements represent the same object in the project.
For instance, a door can be represented by up to three ``-elements:
* one in the first room,
* one in the adjacent room,
* and one in the exploded section describing the location of the door on the whole floor.
In this case, all three `` elements will refer to the same ``-element, indicating that they are in fact one and the same.
### Door in first room
```xml
```
### Same door in adjacent room
```xml
```
### Same door in exploded project
```xml
```
# Floor
Information pertaining to a specific floor are stored in a `symbolInstance` with the id `floor`.
```xml
These are notes
```
# Wire
Information pertaining to a wire are currently not stored in a symbol instance on the `floor`-element but on a symbol instance in the element itself.
```xml
8151229d000ff210.030000 ⌠âŚ
```
# Predefined list of rooms
| Residential | Commercial |
| --------------------- | ------------------ |
| `Kitchen` | `Private Office` |
| `Dining Room` | `Shared Office` |
| `Living Room` | `Open Space` |
| `Hall` | `Meeting Room` |
| `Bedroom` | `Conference Room` |
| `Primary Bedroom` | `Reception` |
| `Children Bedroom` | `Kitchenette` |
| `Bathroom` | `Cafeteria` |
| `Half Bathroom` | `Hall` |
| `Closet` | `Closet` |
| `Study` | `Balcony` |
| `Music Room` | `Garage` |
| `Balcony` | `Hallway` |
| `Garage` | `Lounge` |
| `Hallway` | `Waiting Room` |
| `Laundry Room` | `Workshop` |
| `Playroom` | `Training Room` |
| `Cellar` | `Stairway` |
| `Den` | `Maintenance Room` |
| `Workshop` | `Storage` |
| `Stairway` | `Archives` |
| `Storage` | `Photocopy Room` |
| `Furnace Room` | `Lab` |
| `Toilet` | `Server Room` |
| `Vestibule` | `Elevators` |
| `Deck` | `Furnace Room` |
| `Patio` | `Restrooms` |
| `Porch` | `Vestibule` |
| `Outbuilding` | `Outbuilding` |
| `Unfinished Basement` | `Other` |
| `Primary Bathroom` | |
| `Attic / Loft` | |
| `Other` | |
# Size
One unit in the 3D modeling environment corresponds to `1mm`.
# Webhook Documentation: Project Updated
The **Project Updated** webhook is triggered when a user generates new files or updates an existing project via the [**Custom Export Button**](/guide/advanced-integrations/custom-export-button-integration) in magicplan. While implementing this webhook is not mandatory, it is highly recommended for seamless integration and immediate file processing.
If no webhook URL is specified by the client:
* magicplan assigns a default URL that performs no action.
* The files generated during export can only be accessed through the [**Project Files API**,](/reference#tag/projects/GET/projects/{id}/files) instead of being included in the webhook request.
By providing a valid webhook URL, you can receive the exported files and project details directly, simplifying the process.
#### đ§ How to Set Up Your Webhook
To configure your webhook, make a `PUT`** request to the **[Workspace API ](/reference#tag/workspace/PUT/workspace)and set the `webhook_url` field.
---
##### **Webhook Encoding**
To ensure worldwide interoperability, the strings and file URLs in the request are encoded as follows:
1. The character string is converted into a sequence of bytes using UTF-8 encoding.
2. Each byte that is not an ASCII letter or digit is converted to `%HH`, where `HH` is the hexadecimal value of the byte (e.g., `ĂŠlectrique` becomes `%C3%A9lectrique`).
---
#### đ **Sequence of Events**
This webhook is part of a sequence used to notify your application about updates to floor plans:
1. [**Create and Link Project**](/reference#tag/projects/POST/projects):\
The project is created and linked in one step by specifying the `external_reference_id`. This field represents the identifier of your local project that is assigned to the magicplan project.
2. [**Authorize Export**](/guide/advanced-integrations/custom-export-button-integration/authorize-export-from-magicplan) _(Optional)_:\
If configured, the project is authorized for export.
3. **Floor Plan Updated** _(Webhook Trigger)_:\
When updates are made to the floor plan, magicplan sends the webhook request to your endpoint with updated files and metadata. If no webhook URL is specified, the files must be accessed through the [**Project Files API**](/reference#tag/projects/GET/projects/{id}/files).
---
### HTTP Request
* **Method**: `POST`
* **Endpoint**: `https://yourserverurl/update`
* The webhook includes file URLs (valid for 60 minutes) and relevant metadata about the project.
---
### **Request Schema**
| **Parameter** | **Required** | **Description** |
| -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `key` | Yes | The magicplan API key provided by magicplan. |
| `email` | Yes | The user's email address. |
| `title` | Yes | A human-readable title of the project being updated. |
| `planid` | Yes | The unique identifier of the plan being updated. |
| `project_id` | Yes | The unique identifier of the project being updated. |
| `listing` | No | The ID of your local project linked to the magicplan project. This is referenced as `external_reference_id `in the Workspace API |
| `pdf` | No | The URL of the updated PDF file. |
| `jpg0`, `jpg1` | No | URLs of JPG files, one per floor (e.g., `jpg0` for floor 0). |
| `dxf0`, `dxf1` | No | URLs of DXF files, one per floor. |
| `png0`, `png1` | No | URLs of PNG files, one per floor. |
| `svg0`, `svg1` | No | URLs of SVG files, one per floor. |
| `xml` | No | The URL of the updated magicplan file in XML format. |
| `html` | No | The URL of the updated web file. |
| `ifc` | No | The URL of the IFC file for the entire project. |
| `usdz` | No | The URL of the USDZ file for the entire project. |
| `obj` | No | The URL of the OBJ file for the entire project. |
---
### **Response Schema**
| **XML Tag** | **Value** | **Description** |
| ----------- | ---------- | -------------------------------------------------------------------------------------- |
| `` | `0` | The request was a success. |
| | `1` | The API key is invalid. |
| | `14` | The given user reference or email does not exist. |
| | `18` | The given listing does not exist. |
| `` | _Optional_ | A message that will be displayed in the magicplan app, providing feedback to the user. |
---
### XML Schema
```xml
An optional message that will be displayed to the user in the magicplan app.
```
---
### Example Webhook Request
```bash
POST /update HTTP/1.1
Host: yourserverurl
Content-Type: application/x-www-form-urlencoded
key=3b2abe7cd80d&
email=john.doe%40example.com&
project_id=73377c22-0366-4f1c-9308-8d1c2fbb05d0&
planid=c32ea8d1-fee3-4c81-b402-eb3f85772cf8&
title=Plan+3&
pdf=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.pdf&
jpg0=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.jpg&
dxf0=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.dxf&
png0=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.png&
svg0=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.svg&
xml=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.xml&
html=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.html&
embedded=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.embedded.html
```
# Example 2: Notify and Fetch Additional Files
This workflow retrieves both the files included in the webhook and additional data required for processing.
**Steps**:
1. **Create Project**:\
Use the `external_reference_id` parameter in the [**Create Project API**](/reference#tag/projects/POST/projects) to link the magicplan project to your local system.
2. **Export Trigger:**
* Once the project appears in the user's app, they can open the magicplan app.
* Upon completing the project, the user presses the _Custom Export_ button, signaling that the project is ready for export.
3. **Webhook Notification**:\
magicplan sends a `POST` request to your `webhook_url`, including:
* The `listing` parameter, which identifies the local project linked to the magicplan project.
* File URLs (**valid for 60 minutes**).
* Additional project metadata.
4. **File Queuing and Downloading**:\
Your system queues the file URLs and downloads them as soon as possible.
5. **Additional Data Retrieval**:\
If additional files or data are required, your system calls the [**Project Files API**](/reference#tag/projects/GET/projects/{id}/files) using the project ID or maybe the [**Project Details API**](/reference#tag/projects/GET/projects/{id}) for additional data.
6. **Webhook Response**:
* Status `0`: Indicates success and informs the user of successful processing.
* Other statuses: An error message is displayed in the app, prompting the user to retry.
---
#### **Use Case Example**:
An interior design firm retrieves both exported files and additional metadata, like room dimensions, for client presentations.
# Form API Endpoints
The **Form API** empowers teams to programmatically create, update, and delete custom forms within the magicplan ecosystemâwithout having to log in to the magicplan Cloud UI.
This API is ideal for organizations that already manage form content (like checklists, surveys, or structured field questions) in their internal tools and want to:
* Dynamically create or update forms in magicplan,
* Automate changes to form content as requirements evolve,
* Delete forms that are no longer relevantâ**with caution**.
These capabilities allow tighter integration into existing business workflows, giving developers full control over the form lifecycle in an automated, centralized manner.
đ§ All forms follow a validated schema to ensure compatibility with magicplanâs internal **floorplan** and **object modeling** engines. The schema supports nested elements, context targeting, and custom extension capabilities.
---
## Example Scenario: Custom Form Management from an Internal System
Imagine a property management company that already stores predefined inspection checklists in their internal software. Instead of manually recreating or maintaining these in magicplan Cloud, they can use the Form API to:
1. **Create Forms Automatically**\
As new property types are added in their internal system, corresponding forms (e.g., âLuxury Apartment Pre-Rental Checklistâ) are programmatically created in magicplan via the `POST /forms` endpoint.
2. **Keep Form Content in Sync**\
When a checklist is updated internally (e.g., new compliance questions are added), the `PUT /forms/{id}` endpoint allows syncing those changes instantly across all relevant forms in magicplan - without needing to manually edit anything.
3. **Delete Outdated Forms Carefully**\
If a form is no longer needed, the company can remove it using the `DELETE /forms/{id}` endpoint. **However, form deletion is permanent**:
* Any users who had the form attached to projects will receive a notification in the magicplan app indicating that workspace settings have changed.
* Once they click "Update" in the app, all questions from the deleted form are removed from their projects irreversibly.
This control-centric approach allows teams to manage their form definitions centrally, scale changes across projects and teams, and ensure consistency without manual intervention.
---
## Example Use Case: Heating System Inspection Workflow
Imagine a heating services company aiming to enhance its field inspection process by digitizing data collection and integrating it with their internal systems. They could utilize magicplan's Form API to achieve this goal:
1. **Designing Custom Inspection Forms**: The company creates tailored forms within magicplan Cloud, including fields for system type, condition assessments, maintenance requirements, and photo documentation.
2. **Deploying Forms to Field Technicians**: These forms are published to the company's workspace, making them accessible to technicians via the magicplan app during on-site inspections.
3. **Collecting Structured Data On-Site**: Technicians complete the forms during inspections, ensuring consistent and comprehensive data collection, including capturing photos and notes directly within the app.
4. **Integrating with Internal CRM Systems**: Post-inspection, the company uses the Project Plan API to retrieve the completed form data. This information is then automatically imported into their CRM, facilitating follow-up actions and maintenance scheduling.
This integration streamlines the inspection workflow, reduces manual data entry errors, and improves the efficiency of maintenance scheduling.
---
### Key Benefits
* **Automation**: Keep form content aligned with internal standards and changes.
* **Consistency**: Ensure field teams always use the most up-to-date forms.
* **Integration**: Connect form workflows to internal CRMs, ERPs, or compliance tools.
---
### đ đ§ Planned Endpoints
The following endpoints are part of our extended roadmap and will be introduced in upcoming updates:
#### - Form Context Options
Retrieve the list of available context options â including custom room types and object categories â for dynamic form assignment.
#### - Publish a Form
Make a form active and available for use across projects in the workspace.
#### - Unpublish a Form
Temporarily deactivate a form without deleting it. Ideal for archiving or testing workflows.
# Example 6: Project Versioning Workflow
This workflow maintains and compares multiple versions of a project, supporting detailed change tracking.
**Steps**:
1. **Create Project**:\
Use the `external_reference_id` parameter in the [**Create Project API**](/reference#tag/projects/POST/projects) to link the magicplan project to your local system.
2. **Export Trigger:**
* Once the project appears in the user's app, they can open the magicplan app.
* Upon completing the project, the user presses the _Custom Export_ button, signaling that the project is ready for export.
3. **Webhook Notification**:\
magicplan sends a `POST` request to your `webhook_url`, including:
* The `listing` parameter, which identifies the local project linked to the magicplan project.
* File URLs (**valid for 60 minutes**).
* Additional project metadata.
4. **Version Comparison**:\
Compare the newly downloaded files with previously stored versions to track changes.
5. **Version Management**:\
Save the updated files with versioning metadata (e.g., version number, timestamp).
6. **Webhook Response**:
* Status `0`: Indicates success to magicplan.
* Other statuses: Prompts an error in the app, allowing users to retry.
---
#### Use Case Example
An architecture firm tracks iterative updates to floor plans and maintains a comprehensive version history.
# FAQ
## _General API Usage_
### What is this API used for?
The API enables integrations with **magicplan**, allowing users to manage projects, exchange data, and automate workflows. Learn more: [API Overview](/guide/introduction-to-the-magicplan-rest-api).
### Who can use this API?
This API is available to **authorized workspaces** with valid **API Credentials**. Access is granted at the **workspace level**, meaning individual user authentication is not requiredâonly a valid `API key` and a `Customer ID` is needed to make requests.
### **What data format does the API use?**
All requests and responses use **JSON** format.
### Is there a sandbox or test environment?
Currently, there is no dedicated sandbox environment. However, we can set up a **test workspace** within the production environment for your account, which you can use for testing purposes. [Contact us](/guide/contact-support) for more details.
### How do I get started with the API?
To begin using the API:
1. **Generate an API Key** â A workspace admin must generate an API key in the magicplan dashboard.
2. **Make your first request** â Use your API key to authenticate and retrieve workspace data.
3. **Explore endpoints** â Refer to the API documentation to understand available functionalities.
---
## _Authentication & Security_
### What authentication method does the API use?
The API uses an `API key`** and **`customer ID` for authentication. Every request must include these credentials in the headers to be authorized. See [Authentication Guide.](/guide/getting-started/authentication-and-headers)
### How do I get API credentials?
API credentials can be generated from the magicplan dashboard. Follow the steps in the [API Credentials Guide](/guide/getting-started/generating-api-credentials).
### Who can generate API credentials in magicplan?
Only a **workspace admin** can generate the API Key for a workspace. This ensures that only authorized users have control over API access. Additionally, once the API Key is generated, only the workspace admin has access to it. Other members of the workspace cannot view or retrieve the API Key.
### How should I protect my API key?
Your API key grants access to your account's data and should be handled securely. Best practices include:
* Never expose your API key in public repositories or client-side applications.
* Store API keys in environment variables or secure vaults.
* [Rotate](/guide/getting-started/generating-api-credentials#rotate-api-key) keys periodically and revoke any compromised credentials immediately.
### Do API keys expire?
API keys do not expire by default, but they can be **revoked or regenerated** by an admin at any time. If your API key stops working, check your API settings to verify its status or generate a new one. Learn more in the [API Keys](/guide/getting-started/generating-api-credentials)[ ](#)section.
### How Do API Keys Work in Workspaces?
When an API Key is generated, it is **specific to a single workspace**.
* If a user is an **admin of multiple workspaces**, they must **generate a separate API Key for each workspace** to manage them via the API.
* The API will **only return data within the specific workspace** that the API Key belongs to.
* If a user has a project in **Workspace A**, but they use an API Key from **Workspace B**, that project **will not be listed** in the API response.
##### **Example Scenario**
**⡠User Admin of Two Workspaces**
* **Workspace A** (API Key: `key_A`) â Contains **Project X**
* **Workspace B** (API Key: `key_B`) â Contains **Project Y**
**⡠API Calls:**
* If the user makes a request using `key_A`, only **Project X** will be returned.
* If they make a request using `key_B`, only **Project Y** will be returned.
To manage multiple workspaces via API, the user must **authenticate separately** with the correct API Key for each workspace.
---
## _Requests & Responses_
### How should I structure API requests?
Requests must be made using **JSON payloads** and include the required headers.
### What HTTP methods does the API support?
The API supports standard HTTP methods:
* **GET** â Retrieve data
* **POST** â Create a new resource
* **PUT** â Update a resource
* **DELETE** â Remove a resource
### **What status codes should I expect?**
The API returns standard HTTP status codes, including:
* `200 OK` â Successful request
* `400 Bad Request` â Invalid input
* `401 Unauthorized` â Invalid API credentials
* `404 Not Found` â Resource does not exist
* `500 Internal Server Error` â Unexpected issue
### **Does the API support pagination?**
Yes, large datasets are **paginated**. Use the following query parameters to control pagination in your requests:
* `page`** (integer, default: **`1`**)** â Specifies the page number to retrieve. Defaults to `1` if not provided.
* **Example:** `?page=1`
* `page_size`** (integer, default: **`10`**, max: **`50`**)** â Specifies the number of items per page. Defaults to `10`, with a maximum of `50`.
* **Example:** `?page_size=10`
### **How do I filter or sort results?**
You can use query parameters to filter and sort results. Refer to the API documentation for supported filters.
### How do I handle errors?
Error responses contain a status code, an error message, and details (depending on the issue).
---
## _Endpoints & Functionality_
### How do I create a new project?
You can create a project via the API by sending a **POST** request with the required data. See [Create Project](/guide/basic-concepts/projects/example-1-creating-and-preparing-a-project).
### How do I upload files?
File uploads use **presigned URLs**. First, request a URL, then upload the file directly. See [File Upload Guide](/guide/basic-concepts/projects/file-upload-guide).
### How do I link an external project to magicplan?
To link an external project to **magicplan**, use the `external_reference_id` when creating a project. This ensures that your local project and the corresponding **magicplan** project remain synchronized.
---
## _API Performance & Rate Limits_
### **How can I optimize API performance?**
To improve performance:
* Use **pagination** when retrieving lists
* Cache responses where applicable
* Reduce unnecessary API calls
### What are the rate limits for API requests?
To ensure system stability and prevent excessive usage, the API enforces rate limits.
##### **Rate Limits:**
* **Standard API Endpoints:** **500 requests per 5 minutes**
* **High-Throughput Endpoints:** **2000 requests per 5 minutes**
If you exceed these limits, the API will return a `429 Too Many Requests` response.
### What should I do if I exceed my rate limit?
If your API requests exceed the allowed threshold:
* **Implement Exponential Backoff** â Introduce a delay before retrying requests, increasing the wait time after each failure.
* **Optimize API Calls** â Avoid unnecessary requests by caching results where applicable and fetching only the required data.
* **Use Bulk Operations** â If possible, retrieve larger sets of data in fewer requests instead of making frequent small requests.
---
## _Webhook_
### How do I set up the webhook?
Webhooks allow your system to receive real-time notifications when specific events occur in **magicplan**. To set up a webhook:
1. **Define the webhook endpoint** â This is the URL in your system that will receive webhook payloads.
2. **Register the webhook** â Send a request to the API to register your endpoint, specifying the event types you want to receive.
3. **Validate the setup** â Ensure your system is correctly receiving and processing webhook payloads.
Once registered, **magicplan** will send an HTTP **POST** request to your endpoint whenever the specified event occurs. Your server must be able to handle these incoming requests and respond appropriately. See [Webhook Documentation](/guide/advanced-integrations/custom-export-button-integration/webhook-documentation-project-updated).
### What events trigger the webhook?
Currently, **magicplan** provides a single webhook event, which is triggered when the user **presses the Custom Export button** in the application.
When this happens:
* A webhook request is sent to the configured endpoint with relevant data about the export.
* The payload includes details such as the `project ID`, `email` and such.
* This allows your system to process the exported data in real time.
Since this is the only webhook event available, ensure your system is set up to handle it properly, including validating the incoming request and processing the export data efficiently.
### What happens if my server is down when a webhook is sent?
If your server is unavailable or fails to respond when the webhook is triggered, **magicplan will not retry the request** automatically.
Instead:
* An **error message** will be displayed to the user in the app, informing them that the export failed.
* The user will need to **manually retry** the export process later.
To prevent missed exports, ensure that your webhook endpoint is always accessible, responds quickly, and handles incoming requests efficiently. If needed, implement logging on your end to track failed webhook requests for further troubleshooting.
---
## _Troubleshooting_
### Why am I getting a 401 Unauthorized error?
A `401 Unauthorized` error indicates that the request is **not authenticated properly**. Common causes include:
* **Invalid API Key or Customer ID** â Ensure that you are using the correct credentials.
* **Missing Authentication Headers** â The request must include the required authentication headers.
* **Revoked API Key** â If your key has been revoked, generate a new one.
* **Workspace Restrictions** â API keys are **workspace-specific**, so ensure you are using the correct key for the workspace you are trying to access.Why is my project not appearing in magicplan?
### Why is my project not appearing in magicplan?
If a project does not appear in **magicplan**, consider the following possibilities:
* **Project creation failed** â If the API request did not return a `201 Created` response, the project was not successfully created.
* **Wrong workspace** â If the project was created under a different workspace, it **will not appear in another workspaceâs project list**.
* **Sync Delay** â While changes usually appear instantly, there may be a short delay before projects become visible in the UI.
* **Device is not connected to the internet** â If the userâs device is offline, the project created via the API has not yet been downloaded onto the device. The user must reconnect to the internet and sync their magicplan app to retrieve the project.
**To troubleshoot:**
1. Use the **GET **`/projects` endpoint with the `external_reference_id` to confirm if the project exists.
2. Check the **API response logs** for errors during creation.
3. Ensure you are using the **correct API Key** associated with the workspace where the project was created.
### **Why am I getting a 500 Internal Server Error?**
A `500 Internal Server Error` indicates an unexpected issue on the server. Possible reasons include:
* **Temporary API outage** â The service may be experiencing downtime.
* **Malformed request payload** â Incorrect JSON structure, missing required fields, or invalid data types.
* **Database or backend issues** â The API may be facing internal processing errors.
To resolve:
1. **Check the API status page** (if available) for any known issues or outages.
2. **Review your request payload** to ensure all required fields are correctly formatted.
3. **Retry the request** after a short delay in case it was a temporary issue.
4. If the issue persists, [**contact us**](/guide/contact-support)** with the request details** and response logs.
### How can I debug failed requests?
If your API request fails, follow these steps to identify and fix the issue:
1. **Inspect the API response** â Check the status code and error message for clues.
2. **Review request headers** â Ensure authentication headers, content type, and required fields are present.
3. **Validate the request payload** â Confirm the JSON format and required parameters.
4. **Check API rate limits** â If you exceed the allowed requests, you may receive a `429 Too Many Requests` error.
5. **Monitor webhook logs** â If using webhooks, verify that the receiving server is properly handling requests.
6. **Use logging** â Keep logs of request attempts and responses for easier debugging.
# Example 3: Archiving and Deleting Projects
When a project is completed or no longer needed, you may want to lock its state (prevent further changes) and then remove it from the active roster. This workflow ensures a controlled, reversible step (archiving) before the permanent action of deletion.
**Process:**
1. [**Archive the Project**:](/reference#tag/projects/PUT/projects/{id}/archive)
* **Endpoint:** `PUT /projects/{id}/archive`
* **Action:** Temporarily freeze the project to prevent modifications.
* **Result:** Ensures the project remains intact but read-only, providing a safety net against accidental loss of data.
2. [**Delete the Project**:](/reference#tag/projects/DELETE/projects/{id})
* **Endpoint:** `DELETE /projects/{id}`
* **Action:** Permanently remove the archived project.
* **Result:** Frees up storage and declutters your project list once youâre sure the data isnât needed.
---
**Example Use Case:**\
A long-term construction project that has reached completion and no longer needs active tracking. After archiving for record-keeping, the project can eventually be deleted to maintain a clean working environment.
# Wires
```xml
âŚ
```
Each ``-element can contain a list of ``-elements. A `` is not limited to a single room. For more information on wires, see also [SymbolInstance](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance/wire).
##### Point
Each ``-element has one ``-element for each point that makes up the wire.
| Attribute | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------ |
| `x` | The horizontal position of the point relatively to the center of the floor, in meters, as a floating point number. |
| `y` | The vertical position of the corner relatively to the center of the floor, in meters, as a floating point number. |
##### First, Last
The elements `` and/or `` are only present if the first/last points of the wire are attached to an anchor.
Each ``-element has one ``-element for each point that makes up the wire.
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | The type of anchor the wire point is attached to. `point-room`: the wire is attached to a corner of the room `point-wallitem`: the wire is attached to a point on a wall item `point-furniture`: the wire is attached to a point on a piece of furniture `segment-room`: the wire is attached to a wall of the room `segment-wallitem`: the wire is attached to a segment on a wall item `segment-furniture`: the wire is attached to a segment on a piece of furniture |
| `tag` | The tag of the anchor the wire point is attached to. Tags are custom values that can be defined to restrict which anchors. Predefined values include: `electrical`: the wire conducts electricity `plumbing`: the pipe carries water |
### XML Schema
### Wires
```xml
```
#### Wire
```xml
```
# Furniture
```xml
```
The ``-element represents a piece of furniture on the current floor.
| Attribute | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `symbolInstance` | The unique identifier of the `` [element](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance) containing data attached to this piece of furniture. The symbol instance contains the symbol ID. |
| `x` | The horizontal position of the piece of furniture relatively to the center of the project, in meters, as a floating point number. |
| `y` | The vertical position of the piece of furniture relatively to the center of the project, in meters, as a floating point number. |
| `width` | The width of the piece of furniture in meters, as a floating point number. |
| `depth` | The depth of the piece of furniture in meters, as a floating point number. |
| `height` | The height of the piece of furniture in meters, as a floating point number. |
| `angle` | The angle of the piece of furniture in radians, as a floating point number. |
### XML Schema
```xml
```
# Room
Information pertaining to a plan, a room or a specific point inside a room are currently not stored in a symbol instance but on the element itself.
```xml
Notes here
```
# Pivot
### Floor items
The pivot for these items should be positioned as in the following picture:
### Wall items
The pivot for these models should be positioned as in the following picture:
# SSO
**Single sign-on (SSO)** simplifies the login process by allowing team members to use one set of credentials across all business systems. With magicplan's SSO feature, your team members can securely and conveniently access magicplan using the same credentials they use for other systems, eliminating the need to manage multiple logins and streamlining authentication.
**SSO is a paid add-on service with magicplan.** Please contact our [Sales Team](https://www.magicplan.app/contact) for more details.
**Note:** The setup process for SSO should be performed by an **IT administrator** experienced in configuring applications within your identity provider account. Only admins can enable SSO for your magicplan account.
### Supported Identity Providers
magicplan supports identity providers that use **SAML 2.0**, such as:
* [**Google**](/guide/advanced-integrations/sso#instructions-for-specific-identity-providers__google)
* [**Salesforce**](/guide/advanced-integrations/sso#instructions-for-specific-identity-providers__salesforce)
* [**Microsoft Azure**](/guide/advanced-integrations/sso#instructions-for-specific-identity-providers__microsoft-azure)
If youâre unsure whether your identity provider is compatible, feel free to contact us for assistance.
### General Setup Instructions
To set up SSO for your organization, follow these steps:
1. **Log in to your identity provider account.**
2. **Navigate to your applications** and create a new application for magicplan.
3. Enter the required values in your identity provider account where prompted:
1. **ACS (Assertion Consumer Service) URL**
2. **Audience URISign-on URL or Redirect URL**
4. **Set the username format/Name ID to Email** if prompted.
5. After completing the configuration, contact us at [**integration@magicplan.app**](mailto:integration@magicplan.app) to enable SAML SSO for your workspace.
**Note:** Navigation instructions and field names may vary across identity providers. You can find provider-specific setup instructions below.
---
## **Instructions for Specific Identity Providers**
### Google
1. **Follow** [_these steps_](https://support.google.com/a/answer/6087519?hl=en) provided by Google support.
2. **Set up the magicplan app** with the following information:
1. **Application Name: **`magicplan`
2. **Upload logo:Â **`https://go.magicplan.app/hubfs/NEW%20BRANDING/Logos/mp_magicplan_logo_icon.png`
3. **ACS URL:**
4. **Entity Id**:
5. **Name ID:**
1. Basic Information
2. Primary Email
6. **Name ID Format:** `EMAIL`
3. **Add attribute mappings** for magicplan-required fields:
1. **Email**:
1. Basic Information: `Primary email`
2. App Attribute: `emailaddress`
2. **First Name**:
* Basic Information: `First name`
* App Attribute: `firstname`
3. **Last Name**:
* Basic Information: `Last name`
* App Attribute: `lastname`
4. **Enable magicplan**: Click the three dots in the top-right corner and select **ON for everyone**.
5. **Contact magicplan**: After completing the setup, contact magicplan at [**integration@magicplan.app**](mailto:integration@magicplan.app) to enable SAML SSO for your workspace. Include the following details:
1. The magicplan account that owns your workspace.
2. Workspace name (if you have multiple workspaces).
3. Your organization's email domain (e.g., `@magicplan.app`).
4. SAML Information from Google:
* IdP Certificate
* SAML Entity ID (Issuer)
* SSO URL (Login URL)
* Logout URL
* SAML XML Metadata
---
### Salesforce
1. **Follow** [_this_](https://help.salesforce.com/articleView?id=sf.identity_provider_enable.htm\&type=5) documentation provided by Salesforce.
2. **Log in to Salesforce** and create a Connected App:
1. **Connected App Name**: `magicplan`
2. **Contact Email**: `integration@magicplan.app`
3. **Logo Image URL**: `https://go.magicplan.app/hubfs/NEW%20BRANDING/Logos/mp_magicplan_logo_icon.png`
4. Under **Web App Settings**, check the box for **Enable SAML** and fill in these fields:
1. **Entity ID**: `https://cloud.magicplan.app/`
2. **Subject Type**: Username
3. **ACS URL**: `https://cloud.magicplan.app/auth-sso-success`
4. **Name ID Format**: `emailAddress`
5. **IdP Certificate**: Default IdP Certificate
3. Navigate under _Platform Tools > Apps > App Manager_ and find magicplan. Tap on **View** and scroll down to **Custom Attributes. **Tap on **New **to add custom attributes required by magicplan:
1. **Email**:
* Key: `emailaddress`
* Field: `$User->Email`
2. **First Name**:
* Key: `firstname`
* Field: `$User->First name`
3. **Last Name**:
* Key: `lastname`
* Field: `$User->Last name`
4. **Grant privileges**:
1. Navigate to **Administration > Users > Profiles**, and update the profiles you want to enable access for.
2. Under **Connected App Access**, check the box for the magicplan app and click **Save**.
5. **Contact magicplan**: After completing the setup, contact magicplan at [**integration@magicplan.app**](mailto:integration@magicplan.app) and provide:
1. The magicplan account that owns your workspace.
2. Workspace name (if applicable).
3. Your organization's email domain (e.g., `@magicplan.app`).
4. SAML Information from Salesforce:
* IdP Certificate
* SAML Entity ID (IdP-Initiated Login URL)
* SP-Initiated Redirect Endpoint
* Single Logout Endpoint
* SAML XML Metadata or Metadata Discovery Endpoint
---
### Microsoft Azure
1. Follow [_this documentation_](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal) to add magicplan as an app. You can directly jump to step 7 where it explains about "Create your own application".
2. Continue to configure properties for magicplan, following the steps [_here_](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-configure). The values you need from magicplan are listed below:
1. **Application Name**: `magicplan`
2. **Logo:**` https://go.magicplan.app/hubfs/NEW%20BRANDING/Logos/mp_magicplan_logo_icon.png`
3. **Reply URL:** `https://cloud.magicplan.app/auth-sso-success`
3. After configuring magicplan, assign your users to the app you just created by following the steps [_here_](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-assign-users).
4. Next, set up SAML-based SSO for magicplan. Please follow [_this documentation_](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso#enable-single-sign-on-for-an-app) for more info. To complete those steps, you need the following data from magicplan:
1. **Identifier (Entity ID)**: `https://cloud.magicplan.app`
2. **Reply URL (ACS URL)**: `https://cloud.magicplan.app/auth-sso-success`
3. **Sign-on URL**: `https://cloud.magicplan.app/login`
5. Go into section "User Attributes & Claimsâ and add a new claim for:
1. **Email**:
* Name: `emailaddress`
* Source: Attribute
* Source Attribute: `user.mail`
2. **First Name**:
* Name: `firstname`
* Source: Attribute
* Source Attribute: `user.givenname`
3. **Last Name**:
* Name: `lastname`
* Source: Attribute
* Source Attribute: `user.surname`
6. **Contact magicplan**: After completing the setup, contact magicplan at **integration\@magicplan.app** and provide:
* The magicplan account that owns your workspace.
* Workspace name (if applicable).
* Your organization's email domain (e.g., `@magicplan.app`).
* SAML Information from Azure:
* SAML Single Sign-On Service URL (Login URL)
* SAML Azure AD Identifier
* Logout URL
* SAML Signing Certificate (Base64)
* SAML XML Metadata or App Federation Metadata URL
# Example 4: Export and Sync with External Systems
This workflow ensures project data and files are seamlessly synchronized with external systems like ERPs or CMSs.
**Steps**:
1. **Create Project**:\
Use the `external_reference_id` parameter in the [**Create Project API**](/reference#tag/projects/POST/projects) to link the magicplan project to your local system.
2. **Export Trigger:**
* Once the project appears in the user's app, they can open the magicplan app.
* Upon completing the project, the user presses the _Custom Export_ button, signaling that the project is ready for export.
3. **Webhook Notification**:\
magicplan sends a `POST` request to your `webhook_url`, including:
* The `listing` parameter, which identifies the local project linked to the magicplan project.
* File URLs (**valid for 60 minutes**).
* Additional project metadata.
4. **File Synchronization**:\
Files are downloaded and synced with external systems like:
* ERPs for billing or inventory.
* CMSs for client-facing content.
5. **Webhook Response**:
* Status `0`: Confirms success to magicplan.
* Other statuses: Prompts an error in the app, allowing retries.
6. **Activity Logging**:\
Log the export and synchronization activity for auditing purposes.
---
#### Use Case Example
A retail company syncs floor plans with their ERP for inventory and uploads visualizations to a CMS for clients.
# Changelog & Release Notes
**Update â 25.08.2026**
**Added SVG rendering options to project plans**
`GET /projects/{project_id}/plan` now supports these query parameters:
* `floor_svg_dimensions`
* `room_svg_dimensions`
* `floor_svg_show_annotations`
* `room_svg_show_annotations`
These options control dimensions and annotations in generated floor and room SVGs. Requests without them remain backward compatible.
**Update â 18.08.2026**
**Improved file type consistency**
Updated file types returned by the public API to provide more consistent values following reports from users.
#### Update â 12.05.2026
**Changes in the Project Plan API:**
* Added **Load-Bearing Wall **values under the Room > Walls.
### Update â 16.03.2026
**Changes in the Project Plan API:**
* Introduced `statistics` under the Plan, Floor and Room objects, exposing numeric measurements such as area, perimeter, volume, and surface values.
* Introduced `statistics_formatted` under the Plan, Floor and Room objects, exposing formatted, human-readable measurement values.
* Introduced `image_map` under the Floor and Room objects.
* Introduced `door_count` and `windows_count` at Plan level.
* Introduced the `notes` field on Floor with a values array.
* Introduced the `notes` field on Room with a values array.
* Introduced structured values under Floor, including `ceilingHeight` and `notes`.
* Introduced structured values under Room, including `ceilingHeight`, `roomType`, `ground.color`, and `notes`.
* Introduced structured values under Walls, allowing wall-level attributes to be exposed through the values array.
* Introduced `width`, `height` and `depth` under the values array for doors and windows objects.
### Update â 03.03.2026
**Changes in the Project API:**
* Added a new endpoint to restore an archived project: `PUT /projects/{id}/restore.`
* Added a new endpoint to permanently delete a project file: `DELETE /projects/{id}/files/{fileId}`.
### Update â 20.05.2025
đ **Form API Released**
Weâve released a new **Form API** that allows you to programmatically manage forms within your magicplan workspace.
With this API, you can now:
* **Create** forms remotely via API to reflect your business-specific workflows.
* **Update** form content (questions, structure, etc.) without logging into magicplan Cloud.
* **Delete** obsolete formsââ ď¸ Note: deletion is **irreversible** and may remove form data from user projects after sync.
* **Fetch** forms to review or manage their structure externally.
This is especially valuable if you already manage inspection or checklist templates in your own system and want to automate syncing with magicplan.
For implementation guidance and examples, refer to the documentation page below:
[Form API Endpoints](/guide/basic-concepts/form-api-endpoints)
---
### Update â 19.05.2025
đ **Estimator API Released**
The Estimator API is now officially available, enabling programmatic access to detailed estimate data within magicplan projects.
**Key Features:**
* **Retrieve Detailed Estimates:** Access comprehensive estimate information, including customer details, project metadata, and financial breakdowns.
* **Structured Estimate Items:** Utilize the `parent_id` and `type` fields to reconstruct the nested structure of estimate items, mirroring the hierarchy displayed in the magicplan Cloud interface.
* **Integration-Ready Data:** Seamlessly integrate estimate data into external systems such as CRMs, ERPs, or invoicing tools.
For implementation guidance and examples, refer to the documentation page below:
[Estimator API Endpoints](/guide/basic-concepts/estimator-api-endpoints)
---
### Update â 29.04.2025
##### Changes in the Documentation:
**Published a âComing Soonâ preview page for the Form API Endpoints**, providing an early look at the upcoming capabilities for managing custom forms within a workspace.
These endpoints are still under development and not yet available in production.\
This page is intended to support planning and early discussions with partners.
[Form API Endpoints - Coming Soon đ](/guide/basic-concepts/form-api-endpoints)
---
### Update â 14.04.2025
**Changes in the Documentation:**
**Published a âComing Soonâ preview page** for the **Estimator API Endpoints**, providing an early look at two upcoming endpoints:
* `GET /projects/{id}/estimates` â Lists all estimates associated with a project.
* `GET /projects/{id}/estimates/{estimateId}` â Returns detailed data for a specific estimate.
This preview includes:
* Example JSON payloads
* Description of supported data (estimate metadata, items, cost breakdowns, customer/project info)
* Key integration considerations for external systems
These endpoints are still under development and not yet available in production.\
This page is intended to support planning and early discussions with partners.
[Estimator API Endpoints â Coming Soon đ](/guide/basic-concepts/estimator-api-endpoints)
---
### Update â 10.04.2025
**Changes in the Documentation:**
* A**dded a â**[**Network Requirements**](/guide/getting-started/network-requirements)**â page** under the **Getting Started** section.\
This new page outlines:
* The stable outbound IP address used by magicplan
* Required domain access for API communication
* Firewall and connectivity guidelines for secure integration setup
---
### **Update - 25.03.2025**
**Changes in the Project Plan API:**
* **Added an array of walls** under the Room object.
* **Affected Areas (Partial Areas)** are now exposed under Objects.
* **Added **`wall_uid` to the Room.Object, facilitating identification of wall items and affected wall areas.
* **Introduced **`values`** under Object**, providing dynamic values depending on the object type. For furniture, it includes height, width, and depth; for Affected Areas, it includes color and dimensions.
* **Added **`formatted_dimensions` to the Room object.
* **Renamed **`Objects.symbolId`** to **`Objects.symbol_id` for consistency.
---
### **Initial Release - 04.02.2025**
đ **Launch of the new magicplan API documentation!**
**Features:**
* **Comprehensive Getting Started guide.**
* **Advanced Integrations**: Guides for [SSO](/guide/advanced-integrations/sso), [Deep Linking](/guide/advanced-integrations/deep-linking), and [Custom Export Button](/guide/advanced-integrations/custom-export-button-integration), including real-world use cases
* **Full API documentation:** Includes detailed request/response examples for Projects, Plans, Webhooks, and more.
# Floor
```xml
⌠⌠⌠âŚ
```
Each `` element contains a list of `` elements, representing the floor levels in a floor plan.
| Attribute | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `floorType` | A number representing the type of floor. See [list](/guide/basic-concepts/plan-exchange-xml-format/standardized-plan-elements/available-types-of-floor) of available types of floor. |
| `areaWithoutWalls` | Pre-computed number representing the area without walls. |
| `areaWithWalls` | Pre-computed number representing the area with walls. |
| `areaWithInteriorWallsOnly` | Pre-computed number representing the area with only interior walls. |
##### Exploded Floor vs. Room
Each ``-element contains two equivalent descriptions of the same project:
1. The ``-element represents the **whole floor with absolute coordinates**. Walls and doors are only described once in this representation and are not grouped per room. This representation is convenient for drawing the floor when you only need a line drawing without the room nomenclature.
2. A list of ``-elements describe **each room individually**. Connecting walls and doors are described twice in this format, once for each room. This representation is semantically rich and allows determining in which room lies any `[x, y]` coordinate on the project.
In both representations, the coordinates of a wall are positioned on an imaginary line located at the center of the wall, see also [Point](/guide/basic-concepts/plan-exchange-xml-format/room/point). To compute the length of the wall surface you need to offset these points from the center of the wall to the wallâs surface.
### XML Schema
```xml
```
# 3D Symbols
When adding symbols to a room, magicplan distinguishes between two types of items:
1. **Floor items**: can be positioned anywhere in a room.
2. **Wall items**: a wall must be selected first.
The position of the pivot or the rotation of a 3D model depend on the type of item it represents.
As a general rule, in case an item is composed of multiple parts, the bounding boxes shown in the examples below refer to the entire item, i.e. comprising all of its parts.
# Wall Items
Internally magicplan differentiates between wall items and pieces of furniture. Pieces of furniture (chairs, tables, kitchen sink, etc.) are placed freely inside a room while wall items (doors, windows, radiators, etc.) are always placed in relation to a wall.
In the project (``) as well as in individual rooms (``) all wall items, except for windows, are expressed as a ``-element.
When dealing with wall items an important attribute is `wallItemDistanceToFloor`. This attribute defines the distance between the floor and the bottom of the wall item. It is therefore an essential piece of information when rendering the project in 3D or computing additional values for each room.
### Door
```xml
above2Kitchen DoorNotes on the door0.0500002.0000001.000000
```
---
### Window
```xml
above7Rear WindowNotes on the window1.0000001.2000001.000000
```
---
### Radiator
```xml
above4RadiatorNotes on the radiator0.2000000.6000000.800000
```
# Custom Export Button Integration
The custom export button in magicplan serves as both an export tool and a notification mechanism. When users press the button, it notifies your system that they have completed their work on a project. This allows your system to process the project further based on your requirements.
magicplan generates files specified in the `formats` field of the workspace configuration. However, if the generated files do not meet your needs, you can use other APIs to fetch additional files or data required for your workflow. This flexibility ensures your integration remains robust and adaptable to different use cases.
The export button can be configured either through the [magicplan Cloud settings](https://cloud.magicplan.app/workspaces/settings) or by using the [Workspace Update API](/reference#tag/workspace/PUT/workspace). This integration is designed to be user-friendly and can be set up without additional support.
---
### Configure the Custom Export Button in the Settings Page
Follow these steps to configure the custom export button:
1. Log in to [**magicplan Cloud**](https://cloud.magicplan.app) as a Workspace admin.
2. Navigate to the [**Settings**](https://cloud.magicplan.app/workspaces/settings) section of your Workspace.
* Enter a public **URL** for your logo (1) to customize the appearance of the export button.
* Provide a **description** for the export button (2) as it will appear in magicplan.
* Specify the **email address** (3) to receive exported projects.
3. Save your configuration to activate the custom export button.
##### Additional Option:
* **Apply export configuration for all members**: Use this setting to overwrite the export settings of all Workspace and Team members with the updated configuration.
---
### Configure the Custom Export Button Using the Workspace Update API
To enable the custom export button via the [**Workspace Update API**](/reference#tag/workspace/PUT/workspace), update the following fields in your workspace configuration:
* **Fields required for proper display**:
* `webhook_url`, `name`, `description`, `logo`.\
These fields ensure the button is displayed correctly in the magicplan app. For example, a button without a logo may appear incomplete or unprofessional.
* **Optional fields**:
* `formats, listing_url`, `authorize_url`, and `notify_user`.\
These fields enable additional functionality, such as project listing, transfer authorization, or user notifications upon export.
Although none of the fields are strictly mandatory, including them enhances the appearance and functionality of the export button.
To apply these settings, send a `PUT` request to the [Workspace Update API](/reference#tag/workspace/PUT/workspace) endpoint with the updated values.
For ideas on how to integrate the custom export button into your system, see **Workflow Examples **section.
# Door
```xml
```
The ``-element represents a door located on a wall in the current room. If the door is connecting two rooms, it is represented once on each wall of each room. See also [SymbolInstance](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance) for more information.
**Wall items:** Internally magicplan differentiates between wall items and pieces of furniture. Pieces of furniture (chairs, tables, kitchen sink, etc.) are placed freely inside a room while wall items (doors, windows, radiators, etc.) are always placed in relation to a wall.
In the project (``) as well as in individual rooms (``) all wall items, except for windows, are expressed as a ``-element.\
\
For more information, please see [_wall items_](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance/wall-items).
| Attribute | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `symbolInstance` | The unique identifier of the `` [element](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance) containing data attached to this door. The symbol instance contains the symbol ID. |
| `point` | The index 0-based of the `` element starting the wall containing the door. |
| `snappedPosition` | The corrected relative position of the center of the door on the wall represented by a floating point number between 0.0 and 1.0. This value should be used when drawing an assembled project. |
| `snappedWidth` | The corrected width of the door in meters represented by a floating point number. This value should be used when drawing an assembled project. |
| `snappedOrientation` | The corrected orientation of the door after the rooms are assembled. Inconsistent door orientations are unified across rooms and may differ from the original orientation. This value should be used when drawing an assembled project. The orientation is a number between 0 and 3 obtained by combining two bit values: bit 0, set if door opens towards the outside; bit 1, set if the door opens to the right. |
| `insetY` | Floating point number in meters to determine how far the object is into the wall. Positive values show that the object goes away from the middle of the wall and into the room. Negative values show that the object goes further inside the wall. |
### XML Schema
```xml
```
# Authorize export from magicplan
This service enables your application to confirm whether users are allowed to publish a project to your system. By default, **magicplan** authorizes all projects.
If this service is configured, **magicplan** calls it when a user requests to publish a project. Your application can then accept or decline the transfer based on your own criteria, such as payment status or account verification.
#### đ§ Setting up an authorization endpoint
If you want magicplan to call an authorization endpoint before making a request to your [webhook](/guide/advanced-integrations/custom-export-button-integration/webhook-documentation-project-updated), you must configure it by making a **PUT request to the **[**Workspace API**](/reference#tag/workspace/PUT/workspace) and setting the `authorize_url` field.
##### đ **Sequence of Events**
1. **Request from magicplan**:
* **magicplan** sends a `GET` request to your server.
* The request contains essential parameters such as `key`, `email`, `listing`, `project_id` and `planid`.
2. **Application Decision**:
* Based on the information provided, your application:
* **Accepts**: Returns a successful status.
* **Declines**: No successful status is returned, and the transfer is denied.
3. **Follow-Up Action**:
* If accepted, **magicplan** calls your [webhook](/guide/advanced-integrations/custom-export-button-integration/webhook-documentation-project-updated) to notify your application that the files are ready for download.
---
##### **HTTP Request**
* **Method**: `GET`
* **Endpoint**: `https://yourserverurl/cansend`
---
##### **Request Parameters**
| **Parameter** | **Required** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `key` | Yes | The API key provided by **magicplan**. |
| `email` | Yes | The user's email address. |
| `listing` | No | The ID of your local project linked to the **magicplan** project. This is referenced as `external_reference_id `in the Workspace API |
| `planid` | Yes | The unique identifier of the plan being updated. |
| `project_id` | Yes | The unique identifier of the project being updated. |
---
##### **Response Format**
| **XML Tag** | **Value** | **Description** |
| ----------- | ---------- | -------------------------------------------------------------------------------------- |
| `` | `0` | The request was a success. |
| | `1` | The API key is invalid. |
| | `2` | A parameter is missing or invalid. |
| | `14` | The user reference or email does not exist. |
| | `18` | The given listing does not exist. |
| `` | _optional_ | A message that will be displayed in the magicplan app, providing feedback to the user. |
---
#### Xml Response Schema
```xml
An optional message displayed to the user in the magicplan app, providing additional context or feedback.
```
---
#### Example Request
```plaintext
GET /cansend?key=32ab7ce088d6
&email=john.doe@example.com
&listing=12345678
&project_id=73377c22-0366-4f1c-9308-8d1c2fbb05d0
&planid=4d56f57a5435 HTTP/1.1
Host: yourserverurl
```
---
#### Example XML Response (Acceptance)
```xml
0
```
---
#### Example XML Response (Decline)
```xml
14Your custom message which will displayed to the users in the magicplan app
```
# SymbolInstance
```xml
âŚ
```
Symbol Instances are the primary source for information that the user may have entered in magicplan (e.g. piece of furniture or a door). It contains a list of predefined or custom attributes that holds each value entered by the user (see [Values](/guide/basic-concepts/plan-exchange-xml-format/symbolinstance/values)).
Information pertaining to a project, a room or a specific point inside a room are currently not stored in a symbol instance but on the element (``, `` or ``) itself.
Each `` contains a list of ``-elements. Each of those elements describe an instance of a symbol on the current floor along with its parameters.
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | An identifier uniquely identifying the current symbol instance so it can be referenced from other elements, namely ``, ``, and ``. |
| `uid` | Unique id of a symbol instance as assigned by magicplan in order to track a symbol instance. |
| `symbol` | The ID of the symbol represented by the symbol instance. This can also be custom symbol. |
### XML Schema
```xml
```