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

If you configure a listing_url for your workspace, magicplan will:

Call your endpoint to retrieve a list of your available projects.
Display this list to the user during the publishing process.
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:

<warnOnReplace>1</warnOnReplace>

🆕 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 and set the listing_url field with the URL of your endpoint.

🔁 Sequence of EventsCopied!

Link Project is part of the workflow that allows users to select or create a project within your system before exporting from magicplan.

User Initiates Export
The user taps the export button in magicplan.
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.
User Selects a Project
The user chooses an existing project from the list or creates a new one (if supported).
magicplan Calls Your Authorize URL (Optional)
The selected project_id is sent to your authorize_url.
If this call is successful, the export proceeds.
magicplan Triggers Webhook URL
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 property.
postalcode	Yes	The postal/zip code of the property.

Response Format

XML tag	Value
`<status>`	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.
`<listing>`		see below

Each <listing> 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

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

<xs:element name="MagicPlanService">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="status">
        <xs:simpleType>
          <xs:restriction base="xs:integer">
            <xs:enumeration value="0"/>
            <xs:enumeration value="1"/>
            <xs:enumeration value="2"/>
            <xs:enumeration value="14"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element name="listing" type="listing" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
</xs:element>

<xs:complexType name="listing">
  <xs:sequence>
    <xs:element name="id" type="xs:string"/>
    <xs:element name="title" type="xs:string"/>
    <xs:element name="warnOnReplace" minOccurs="0">
      <xs:simpleType>
        <xs:enumeration value="0"/>
        <xs:enumeration value="1"/>
      </xs:simpleType>
    </xs:element>
  </xs:sequence>
</xs:complexType>