GuideReferencemagicplan Cloud

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.

📘 OverviewCopied!

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.

Integration Example: Syncing an Estimate into an ERP SystemCopied!

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 RequestCopied!

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

Step 2: Retrieve the Estimate for a ProjectCopied!

Make a request to list estimates (optional filtering, if needed), and then fetch the detailed estimate.

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 ItemsCopied!

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 ERPCopied!

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 DevelopersCopied!

  • 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