PLNAR REST API Specification (4.4.0)

INTRODUCTION

PLNAR Snap allows users to easily convert measurable 3D models of their interior spaces using smartphone photos captured using the PLNAR Snap App. The Snap project lifecycle begins in the portal where users create projects for reporters in the field who download the the Snap app and instructed to take photos using the Snap flow. Once uploaded from the Snap app, photos are analyzed using PLNAR's AI back-end system and assembled into an accurate digital twin (3D model) of the user's interior space. When finished, the extracted measurements and 3D model can be viewed and interacted with in the PLNAR portal.

PLNAR API

As an alternative to creating projects directly from the PLNAR portal, we provide a public API. The API allows provisioned users to create projects, receive callbacks for key project lifecycle events, and fetch project data directly from their own environments.

The base url for calling the api is https://api.plnar.ai/api/{version}/

AUTHENTICATION

Authentication credentials (client_id and client_secret) are supplied to provisioned company admininstrators in the PLNAR portal. These can be used to request Oauth bearer tokens via the /oauth/token (POST) route which can be used for the downstream API calls. Upon expiration, a new bearer token can be requested as needed.

CREATING PROJECTS

The project creation process is handled using the /project (POST) route. Authentication is performed via the request header while data for the request is provided in the request body. Key data elements include:

• reporter (required) information is required for the person in the field using the PLNAR Snap app/

• user (optional) information can be provided to assign the project to an existing user in the PLNAR portal. If user data is not provided, the project will be created in an unassigned state.

• referenceNumber (optional) can be provided to bind the project to a project ID within your home system.

• perilType (optional) can be provided for projects representing property claims and/or restoration work.

• referringSource (optional) can be used to store the referring URL for source referencing, market tracking, etc, .

• notifications (optional, default=true) which signals whether reporter entry into PLNAR SNAP process should be initiated directly via PLNAR-provided SMS (true) or whether engagement will be handled directly by you using the generated uploadUrl and the redirect method of your choice.

• communication (optional) Settings which can be used to customized the communications (SMS and emails) sent to the reporter. This provides control of personalization and organization (company) branding in the SMS and email along with the ability to use a custom organization name. This is useful for custom and sub branding under your official company name.

Additional required and optional data elements are further documented below.The response for a successful project creation request will contain all the data necessary to bind the project into your system and to allow downstream tracking of your using the project fetch API.

PROJECT_DATA

After a project is created, interior data (photos, metadata, etc) will be collected in the field by the reporter and uploaded to the PLNAR servers. The data will then be assembled into 3D models of each interior space (room) and reports for the project will be generated. As the data is made available, it will be accessable via both callbacks and the fetch API. Key data components accessible via API include:

• photos: Direct links to all photos uploaded by the reporter will be available immediately on submission to give you immediate insight to the project as the 3D model and measurement data is being assembled.

• rooms: A list of rooms and summaries of perimeter, area, and volume measurements for floors, walls, doors, openings, windows foreach room and aggregated for the room. Counts of objects will also be providedl in addition to measurement data for all objects in each room.

• data: Perimeter, area, and volume measurements for floors, walls, doors, openings, windows foreach room and aggregated for the entire project. Counts of objects will also be provided.

• shareUrl: (optional) A direct link to the project in the PLNAR portal giving you access to the 3D model, measurement data, reports, exports, etc in an embeddable URL. Your organization needs to be provisioned for share links, or you can enable projects individually, for share links to be available.

• attachments: Links to reports containing photos, measurements, take-offs raw photos, 2D plan underlays, etc that allow you to share data for your project and upload to your back end integrations as necessary.

The project data will be progressively made available in your project as it moves through its lifecycle. All of the data will be available once the project is in the completed state.

WEBHOOK AND CALLBACKS

PLNAR projects created via the API will fire (POST) callbacks containing project data to a webhook address for all key lifecycle events. These include:

• project.created Noting that a project has been created.

• project.inProgress Signaling that a reporter (policyholder, homeowner, etc) has begun documenting their interior using the PLNAR Snap app.

• project.submitted Alerting you that the project (room data, photos) has been successfully uploaded by the reporter and has begun processing.

• project.completed Letting you know that the project has completed processing.

In addition to project events, callbacks will be fired for both reporter and user events including:

• creation Sent when a user or reporter is created.

• updates Sent when a user or reporter is updated.

• deletion Sent when a user or reporter is deleted in the PLNAR portal.

You can set up the webhook address for your organization directly in the portal company tab. If left empty, no callbacks will be fired during the project lifecycle but you can still query projects using the fetch API. For security, each request provides a signature (SHA-256 HMAC) which is accessable via the x-plnar-signature key in the request header. The signature is encoded using the secret you provide when setting up the webhook for your organization.

UPDATING PROJECTS

At any point after a project has been created, you can update project data using the /project/{orderNumber} (PUT) route. Project parameters that can be updated include project name, notes, referring source (URL), reporter attributes, address, and communication settings among others. Authentication is handled in the request header and the orderNumber (provided in the project creation API response) just needs to be appended to the route. The response will contain all the data available for the project in its current state.

FETCHING PROJECTS

You can also fetch project data using the /project/{orderNumber} (GET) route. Authentication is handled in the request header and the orderNumber (provided in the project creation API response) just needs to be appended to the route. The response will contain all the data available for the project in its current state.

If you need any further assistance with the PLNAR API, please contact plnar-support@plnar.ai .