Dwellant API v1.0

Overview

The Dwellant v1.0 API delivers a simple application interface for your organisation.

The following functionality is provided:

Contractors: - Get: Work Order IDs (with new filter for polling) - Get: Work Order - Post: Acknowledge Work Order Received - Post: Complete Work Order - Post: Create New Informal Request

Managing Agents: - Get: Invoice files

In version 1.0 the API only accepts and sends data in JSON format. Dates and times should be in UTC ISO 8601 format, i.e. 2012-05-23T22:18:01Z.

URLs

• Training: https://api.dwellant.net/training
• Beta: https://api.dwellant.net/beta
• Live: https://api.dwellant.com/

Please note each environment has separate credentials and keys.

Actions

GET: Work Order IDs

Work Orders are synonymous with Purchase Orders, a instruction for work, services or supplies, with a maximum price, and all details of the site, agreement and invoicing.

Returns a list of all work order ids for work orders that are open. For v1.0 we will support a single filter of status=new that shows work orders that have not yet been acknowledged by a contractor. Use these IDs against the other endpoint to retrieve the work order data.

The purpose of this end point is to allow polling of new work orders on a regular.

Example Request

GET https://api.dwellant.com/workorders?status=new

Example Response

{
            "workOrders" : [
                { "id": 1567, "url": "https://api.dwellant.com/workorders/1567", "status": "InProgress" },
                { "id": 1342, "url": "https://api.dwellant.com/workorders/1342", "status": "InProgress" },
                { "id": 16890, "url": "https://api.dwellant.com/workorders/16890", "status": "InProgress" }
            ]
        }

GET: Work Order

Retrieves a single work order. The work order must be open, once closed, they are no longer available over the API. A work order may contain one or more items. These are requested to be provided and contain the price that has been previously been synchronized to Dwellant.

Fields

File Reference

Files are used for attachments, Health and safety docs, etc and are an object with free text and a url;

    { "name": "H&S Report", "url" : "https://dwellant.com/doc/9934"}

Address

We provide a fully or partially decomposed address where available. Not all fields will have values, and the object itself may be null.

    {
                "address1": "6 Grafton House",
                "address2": "19 Farrow Street",
                "address3": "",
                "townName": "London",
                "postcode": "SW12 7YT",
                "country": "UK"
            },

Item

Items are requests for items to be supplied.

{
            "description": "Boxes x100 - 14x32x32",
            "partNumber": "b1007-g",
            "quantity": 7,
            "netPrice": 4.73
        }

Groups

Contractors may optionally specify groups. These allow Managing Agents to directly assign a task to a group within the contractor. When specifying a group the Internal Group Name must be set and this value is returned in assignedGroup. Optionally an External Public Name and Description may be set and are returned as assignedGroupPublicName and assignedGroupDescription respectively. If the Public name is set then this will appear in the dropdown when a Managing Agent selects the group - overwriting the Internal name.

Example Request

GET https://api.dwellant.com/workorders/1567

Example Response

{
            "id": 1567,
            "subject": "Fix lights",
            "description": "Replace GU10 fittings and",
            "maxValue": 250,
            "created": "2012-04-23T18:25:43Z",
            "targetDate": "2012-05-23T00:00:00Z",
            "status": "InProgress",
            "siteAddress": "6 Grafton House, London SW11 2PT",
            "siteAddressDetails":   {
                "address1": "6 Grafton House",
                "address2": "",
                "address3": "",
                "townName": "London",
                "postcode": "SW11 2PT",
                "country": "UK"
            },
            "unitAddress": "5 Nirvana Court, Low Road, London, SW1V 1DW",
            "unitAddressDetails":   {
                "address1": "5 Nirvana Court",
                "address2": "Low Road",
                "address3": "",
                "townName": "London",
                "postcode": "SW1V 1DW",
                "country": "UK"
            },
            "createdByPersonName": "John Gomez",
            "managementGroupName": "London SW Group",
            "createdByPersonId": 439857,
            "assignedGroup": "Maintenance [123]",
            "assignedGroupPublicName": "Maintenance",
            "assignedGroupDescription": "Group 123",
            "priority": "Low",
            "propertyId": "430-9534",
            "audience": "Concierge",
            "clientName": "Freeholder Ltd",
            "invoiceAddress": "C/O Managing Agent Ltd, London, SW1V 1DW",
            "buildingDetails": "Please contact porter on 07956 456 216 when on site.",
            "preInspection": 0,
            "ramsRequired": "WorkingAtHeight; HotWorks",
            "ramsDescription": "Very high heights - use scaffold",
            "hAndSDocs": [
                { "text": "H&S Report", "url": "https://dwellant.com/doc/9934"},
                { "text": "Asbestos Report", "url": "https://secure.dwellant.com/doc/3423470324"}
            ],
            "attachments": [
                { "text" : "Photos", "url": "https://secure.dwellant.com/doc/123004" },
                { "text": "", "url": "https://secure.dwellant.com/doc/34145624" }
            ],
            "permitToWork": "https//secure.dwellant.com/permit_to_work/610456",
            "completedDate": "2012-05-23T00:00:00Z",
            "items": [
                { "description": "Boxes x100 - 14x32x32", "partNumber": "1007gh", "quantity": 7, "netPrice": 4.73},
            ],
            "blockId": 52367,
            "blockDetails": "Grafton Square B"
         }

Sub Types

Priority

    Low
            Medium
            High
            Urgent

Status

    InProgress (When work is in progress on a job)
            Completed (When the work on a job has been completed)
            AwaitingQuotations
            QuotationsComplete
            InvoiceUploadRequired
            InvoiceBeingProcessed
            InvoicePaid
            AwaitingRamsDocuments (Awaiting RAMS documents)
            AwaitingRamsApproval (Awaiting RAMS approval)

Audience

    Private
            Concierges
            Directors
            WholeBuilding

Rams Required

    DisturbAsbestos (Works involving or likely to disturb asbestos)
            HotWorks
            WorkAtHeight (Work at height (above 2m))
            ConfinedSpaces
            PressurisedPlant (Working on pressurised plant)
            Electrics (Working on high voltage or low voltage electrics)
            Excavations (Excavations deeper than 1.5m)
            FireAlarmSystem (Isolation of the fire alarm system)
            LargeMobilePlan (Any work involving large mobile plant (e.g. MEWPs))
            Other (Any other work that has a risk of serious injury or death)

Errors

• Requesting a work order that does not exist will return 404 Not Found

POST: Create Work Order

This allows you to create a workorder.

Fields

Post

Allocation

Example Request

POST https://api.dwellant.com/workorders

{
            "subject": "Drain Improvement",
            "managingAgentId": 1234,
            "buildingId": 8759,
            "description": "Increase the flows of drains in the lower court.",
            "category": "Maintenance",
            "blockId": 4444,
            "maxValue": 1000,
            "externalId": "CT-1678",
            "groupId":13287,
            "targetDate": "2012-04-23T18:25:43Z",
            "invoicePreApproved": false,
            "allocations": [
                {
                    "recoverability": 1,
                    "scheduleId": "88",
                    "expenseTypeId": "2706",
                    "allocation": "1/2",
                    "propertyReference": "45102"
                },
                {
                    "recoverability": 1,
                    "scheduleId": "48",
                    "expenseTypeId": "1710",
                    "allocation": "50%",
                    "propertyReference": "45102"
                }
            ]
        }

Example Response

{
          "id" : "1234"
        }

Errors

• Requesting a building you do not have permission for will return 403 You do not have permission to access this building
• Requesting a building that does not exist will return 400 Requested building does not exist
• If required fields are not sent then 400 Bad Request will be returned.

POST: Acknowledge Work Order Received

After retrieving a work order you must send an acknowledgement. Work orders that are not acknowledged will continue to appear in ./api/workorders?status=new. Acknowledgements should only be sent after you have recorded the work order. Acknowledging a work order lets the Managing Agent know that your system has received the work order.

The External ID and Status are your systems values that Dwellant will record. This must be the unique ID of the ticket in your system. Status can be system generated or a comment from your users to indicate its stage in the process.

Fields

Example Request

POST https://api.dwellant.com/workorders/acknowledgements

{
            "id": "1567",
            "externalId": "EX-156-02",
            "externalStatus": "With Engineer"
        }

Example Response

200 OK

Errors

• Acknowledging a work order that has already been acknowledged will return 409 CONFLICT.
• If required fields are not sent then 400 Bad Request will be returned.
• Acknowledging a work order that does not exist will yield a 404 Not Found

POST: Complete Work Order

When a work order is complete you should notify Dwellant. Other information can now be supplied.

The External ID and Status are your systems values that Dwellant will record.

Fields

Example Request

POST https://api.dwellant.com/workorders/completions

{
            "id": "1567",
            "externalId": "EX-156-02",
            "comment": "All done and checked",
            "completionTime": "2012-05-23T00:00:00Z",
            "attachments": [
                { "text": "Photo of finished work", "url": "https://www.yoursystem.com/whatever/934850934.pdf" }
            ],
            "externalStatus": "Complete"
        }

Example Response

200 OK

Notes

After Dwellant receives a completion message, Dwellant will attempt to download any hyper-links contained in the attachment field. This will happen shortly after posting. There is a retry/back off mechanism built in , however in v1.0 if the file can not be downloaded after a number of attempts it will not appear in the Dwellant system. The response will be returned BEFORE an attempt is made to download files.

Errors

• If you attempt to complete a work order that has not been acknowledged you will receive 409 CONFLICT.
• If you try to complete a work order that has already been completed the server will return 410 GONE.
• If required fields are not sent then 400 Bad Request will be returned.
• Completing a work order that does not exist will yield a 404 Not Found

POST: Create New Informal Request

Request Fields

Sub Types

File Reference

Attachments are optional documents and photos that needs to be attached to the new task in Dwellant. They are defined by a short description and a URL. Dwellant will attempt to donwload the file from the URL and attach it to the new task.

    { "text": "Report", "url" : "https://www.example.com/doc/93434.pdf"}

Priority

    Low
            Medium
            High
            Emergency

Response Fields

Example Request

POST https://api.dwellant.com/tasks/informalrequests

{
            "externalId": "F-4035892",
            "buildingId": 49504,
            "blockId": 8998505,
            "subject": "subject 66",
            "description": "Description of the work to do.",
            "category": "H&S ACtion",
            "targetDate": "2018-11-21T21:10:10",
            "priority": "Medium",
            "externalStatus": "Ready",
            "externalCreatedDate": "2018-10-09T21:10:10",
            "siteAddress": "96 Wilton Road, London, SW1V 1DW",
            "unitAddress": "Flat 34",
            "attachments": [
                { "text": "Report", "url": "https://www.example.com/doc/93434.pdf" }
            ]
        }

Example Response

200 OK
        {
            "externalId": "F-4035892",
            "id": 822311,
            "status": "InProgress"
        }

Errors

• Sending a work order with the same externalId twice will return 400 Bad Request
• See Common Errors for other errors

POST: Attach file to Informal Request

Request Fields

Note that one, and only one, of the file and fileLink fields must be provided.

Accepted file extensions

"pdf", "doc", "docx", "png", "jpg", "jpeg", "gif", "xls", "xlsx", "txt", "mp3", "mp4", "msg", "zip"

Example Request

POST https://api.dwellant.com/tasks/informalrequests/files

{
            "informalRequestId" : 822311,
            "fileName": "attachment.txt",
            "file": "--encoded file--"
        }
        
        {
            "informalRequestId" : 822311,
            "fileName": "attachment.txt",
            "fileLink": "https://example.com/filestore/file.pdf"
        }

Example Response

200 OK

Errors

• The specified task does not exist 400 The specified task does not exist.
• File no provided 400 File is required.
• File name not provided 400 File name is required.
• File extension not valid 400 File extension is not valid.
• Request is empty 400 The request can't be empty.
• Not allowed access to task - 403 You do not have permission to attach files to the task.
• See Common Errors for other errors

POST: Complete Informal Request

When an informal request is complete you should notify Dwellant. The External ID and Status are your systems values that Dwellant will record.

Fields

Example Request

POST https://api.dwellant.com/informalrequests/completions

{
            "id": "1567",
            "externalId": "EX-156-02",
            "comment": "All done and checked",
            "completionTime": "2012-05-23T00:00:00Z",
            "attachments": [
                { "text": "Photo of finished work", "url": "https://www.yoursystem.com/whatever/934850934.pdf" }
            ],
            "externalStatus": "Complete"
        }

Example Response

200 OK

Notes

After Dwellant receives a completion message, Dwellant will attempt to download any hyper-links contained in the attachment field. This will happen shortly after posting. There is a retry/back off mechanism built in , however in v1.0 if the file can not be downloaded after a number of attempts it will not appear in the Dwellant system. The response will be returned BEFORE an attempt is made to download files.

Errors

• If required fields are not sent then 400 Bad Request will be returned.
• Completing an informal request that does not exist will yield a 404 Not Found

PUT: Edit Request

Use the Dwellant ID in the URL to update a request. The Dwellant ID is returned by Create requests.

It is important to note that this is a PUT operation, not a PATCH, so any null fields will be saved as null. The fields work identically to creating a contract via a POST. Please note that externalStatus is optional and stored in the changes list on the request as a comment.

Request Fields

Sub Types

Priority

    Low
            Medium
            High
            Emergency

Example Request

POST https://api.dwellant.com/tasks/789

{
            "subject": "subject 66",
            "description": "Description of the work to do.",
            "category": "H&S ACtion",
            "targetDate": "2018-11-21T21:10:10",
            "priority": "Medium",
            "externalStatus": "Ready",
        }

Example Response

200 OK

Errors

• Updating a request that no longer exists results in 404 Request not found
• See Common Errors for other errors

POST: Request Comment

Adds a comment to a Work Order or Informal Request. The request ID is the Dwellant ID returned when creating a Work Order or Informal Request. This endpoint returns the Dwellant ID of the created comment.

Request Fields

Example Request

POST https://api.dwellant.com/requests/comments

{
            "requestId": 2319789,
            "comment": "new"
        }

Example Response

200 OK

        8960571

Errors

• The specified task does not exist 400 The specified task does not exist.
• See Common Errors for other errors

POST: Request Comment Attachment

Adds a file to a previously created comment.

Request Fields

Accepted file extensions

"pdf", "doc", "docx", "png", "jpg", "jpeg", "gif", "xls", "xlsx", "txt", "mp3", "mp4", "msg", "zip"

Example Request

POST https://api.dwellant.com/requests/comments/files

{
            "requestCommentId": 8960571,
            "fileName": "exampleq.xyz",
            "file": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYm..."
        }

Example Response

200 OK

Errors

• The specified task does not exist 400 The specified task does not exist.

• The specified comment does not exist 400 Request comment not Found.

• File not specified 400 You did not provide a file.

• File extension invalid 400 Please only provide files of type: "pdf", "doc", "docx", "png", "jpg", "jpeg", "gif", "xls", "xlsx", "txt", "mp3", "mp4", "msg", "zip"

• See Common Errors for other errors

GET: Task Event Notifications

This endpoint gives access to changes (comments or completion) made on tasks you created via this API (i.e. by using POST: Create New Informal Request). You should poll this endpoint to receive event notifications. The endpoint will record the date and time an event was retrieved. It will return every event only once. Please note you may prefer to use a webhook to receive notifications rather then poll using this endpoint.

The rate you poll the endpoint will depend on your requirements, but it is recommended to not call it more than once a minute. If it returns events you should call it as soon as you have finished processing those events. If it returns no events than continue your standard polling process.

Response Fields

The endpoint returns an object with a single events field. This is an array that contains the events, starting with the oldest one. It will contain maximum 5 events. Each event has the fields listed below.

Example Request

GET https://api.dwellant.com/tasks/events

Example Response

200 OK
        {
          "events": [
            {
              "eventType": "TaskCommented",
              "eventDateTime": "2019-12-17T15:56:05.8756813Z",
              "id": 1007796,
              "externalId": "af99811969",
              "changeId": 4556056,
              "comment": "Comment 1",
              "attachments": null,
              "notificationId": 10,
              "updatedBy": "Joe Bloggs"
            },
            {
              "eventType": "TaskCommented",
              "eventDateTime": "2019-12-17T15:57:30.0998325Z",
              "id": 1007799,
              "externalId": "af99811904",
              "changeId": 4556057,
              "comment": "Comment 2",
              "attachments": [
                {
                  "name": "RAMS 5.pdf",
                  "url": "https://dwellant.com/Task/TaskChangeViewAttachment/dGpZA0NT2MDU3AXlbA0Y2UBdGFpZAFSQU1TIDUucGmAX6ckpnMTcxQWQy0ZQUzZtamxmaGNxME9hdz0="
                }
              ],
              "notificationId": 11,
              "updatedBy": "Joe Bloggs"
            },
            {
              "eventType": "TaskCompleted",
              "eventDateTime": "2019-12-17T16:08:34.4476907Z",
              "id": 1007796,
              "externalId": "af99811969",
              "changeId": 4556058,
              "comment": "Comment 3",
              "attachments": null,
              "notificationId": 12,
              "updatedBy": "Richard Roe"
            }
          ]
        }

POST: Task Event Notification Acknowledgement

Use this endpoint to acknowledge that your system has received a task event notification. Each event contains a notificationId field which should be used when making an acknowledgement.

Request Fields

Example Request

POST https://api.dwellant.com/tasks/events/acknowledgements

{
            "id": 10
        }

Example Response

200 OK

Errors

• If you attempt to acknowledge a notification that does not exist the service will return 404 Not Found.
• If you attempt to acknowledge a notification without first retrieving it the service will return 409 Conflict.
• If you attempt to acknowledge a notification that has already been acknowledged the service will return 409 Conflict.
• If required fields are not sent then 400 Bad Request will be returned.

GET: Building Details

Retrieves basic information about all buildings that you may offer Key Building Services to. This endpoint offers two modes:

• Property Mode ?isPropertyLevel=true
• Organisation Mode ?isPropertyLevel=false

Property mode breaks each building into its Dwellant Accounting Property. This may return multiple records per Organisation and will populate the Property fields. You will need to discuss with us which method makes more sense.

There is also an optional from=2016-01-02 parameter which allows you to request only buildings that have been updated since the provided dates. This allows you to poll us daily and only retrieve details that have been modified in the last day.

Example Request

• GET https://api.dwellant.com/buildings
• GET https://api.dwellant.com/buildings?isPropertyLevel=false
• GET https://api.dwellant.com/buildings?isPropertyLevel=true&from=2016-01-02

Example Response

Given isPropertyLevel=true:

{ 
            "buildings" : [
                {
                  "managingAgentId": 82734,
                  "dwellantBuildingId": 34672,
                  "buildingExternalId": "-2000951540",
                  "buildingReference": "205410",
                  "buildingName": "Building 34672",
                  "buildingOwner": "A building owner",
                  "buildingAddress": "328907 Long Street; New City; W8 7AB",
                  "dwellantPropertyId": 23190,
                  "propertyExternalId": "-2000951540",
                  "propertyReference": "205410",
                  "propertyName": "Accounting Property 23190",
                  "propertyAddress": "1234 Long Street; New City; W8 7AC",
                  "note": null,
                  "buildingDetailsLastUpdated": null,
                  "buildingAddressDetails": {
                        "address1": "328907 Long Street",
                        "address2": "",
                        "address3": "",
                        "townName": "New City",
                        "postcode": "W8 7AB",
                        "country": ""
                    },
                  "propertyAddressDetails": {
                        "address1": "1234 Long Street",
                        "address2": "",
                        "address3": "",
                        "townName": "New City",
                        "postcode": "W8 7AC",
                        "country": ""
                    }
                },
                ...
            ]
        }

Given isPropertyLevel=false:

{ 
            "buildings" : [
                {
                  "managingAgentId": 82734,
                  "dwellantBuildingId": 34672,
                  "buildingExternalId": "-2000951540",
                  "buildingReference": "205410",
                  "buildingName": "Building 34672",
                  "buildingOwner": null,
                  "buildingAddress": "328907 Long Street; New City; W8 7AB",
                  "dwellantPropertyId": 0,
                  "propertyExternalId": null,
                  "propertyReference": null,
                  "propertyName": null,
                  "propertyAddress": null,
                  "note": "Account number is 178862",
                  "buildingDetailsLastUpdated": null
                },
                ...
            ]
        }

Errors

This endpoint should return no errors.

GET: Specific Building Details

This allows you to retrieve specific information regarding a building. You can use either:

• The Dwellant Building ID (recomended)
• The Dwellant Property ID (recomended)
• The Dwellant Managing Agent ID and one of the following provided by the Managing Agent:
  • The Property External ID
  • The Property Reference
  • The Building External ID
  • The Building Reference

In any case the above IDs are provided in the response from a call to https://api.dwellant.com/buildings/

Example Request

• GET https://api.dwellant.com/buildings/34672
• GET https://api.dwellant.com/buildings/property/23190
• GET https://api.dwellant.com/buildings/property/ma/123/ext/-2000951540
• GET https://api.dwellant.com/buildings/property/ma/123/ref/205410
• GET https://api.dwellant.com/buildings/ma/123/ext/-2000951540
• GET https://api.dwellant.com/buildings/ma/123/ref/205410

Example Response

{
          "buildingId": 34619,
          "buildingName": "Fork building",
          "accountingReference": "-2000951602",
          "managingGroup": "Team 07",
          "propertyManagers": [
            {
              "name": "John Sampleson",
              "role": "Fund Manager",
              "phoneNumber": null,
              "mobileNumber": "07123456",
              "email": "john.sampleson@example.com",
              "userId": 490963,
              "outOfOfficeTill": null,
              "coveringForUserId": null
            },
            {
              "name": "Mary Example",
              "role": "Asset Manager",
              "phoneNumber": null,
              "mobileNumber": null,
              "email": "mary.example@example.com",
              "userId": 490958,
              "outOfOfficeTill": null,
              "coveringForUserId": null
            },
            {
              "name": "Polly Pepper - Out of Office until 2024-08-31",
              "role": "Asset Manager",
              "phoneNumber": null,
              "mobileNumber": null,
              "email": "mary.example@example.com",
              "userId": 490959,
              "outOfOfficeTill": null,
              "coveringForUserId": null
            },
            {
              "name": "Alt - Charles Ipsum - Covering: Polly Pepper",
              "role": "Asset Manager",
              "phoneNumber": null,
              "mobileNumber": null,
              "email": "mary.example@example.com",
              "userId": 490960,
              "outOfOfficeTill": "2024-08-31T01:00:00+01:00",
              "coveringForUserId": 490959
            }
          ],
          "contracts": [
            {
              "contractName": "Ongoing instalation of Fire Supresion Systems",
              "contractorName": "The Fire People",
              "contractId": 38401,
              "primaryEmail": "fire@example.com",
              "switchboardNumber": "07 555 1988"
            },
            {
              "contractName": "Rubish Collection",
              "contractorName": "The Garbage Men",
              "contractId": 36502,
              "primaryEmail": "gm@example.com",
              "switchboardNumber": "07 123 4567"
            }
          ],
          "managingAgentId": 34368,
          "buildingAddress": "7 Lane Road; SW11 2GH; London",
          "buildingInformation": {
            "lastUpdated": "2019-12-19T11:28:44",
            "notes": [
              {
                "name": "Emergency Phone Number",
                "text": "07 123 4567"
              },
              {
                "name": "",
                "text": "Only Call this number after 8:00pm"
              }
            ]
          },
          "serviceNotes": {
            "auditorNote": null,
            "healthAndSafetyCompanyNote": null,
            "insuranceCompanyNote": "Account number is 178862",
            "liftCompanyNote": null,
            "outOfHoursCompanyNote": null,
            "solicitorNote": null,
            "utilityBrokerNote": null
          },
          "blocks": [
            {
              "blockId": 155490,
              "blockName": "Main block",
              "blockOwner": "Big Corp Inc",
              "blockManagementCompany": "Three Oaks Management Company Ltd",
              "blockType": 5,
              "blockTypeName": "Main block",
              "blockHeight": "Low",
              "blockRelevance": false,
              "blockAddress": "7 Lane Road; SW11 2GH; London"
            },
            {
              "blockId": 155432,
              "blockName": "Three Oaks Lodge",
              "blockOwner": "Big Corp Inc",
              "blockManagementCompany": "Three Oaks Management Company Ltd",
              "blockType": 14,
              "blockTypeName": "Physical block",
              "blockHeight": "Low",
              "blockRelevance": null,
              "blockAddress": "7 Lane Road; SW11 2GH; London"
            }
          ]
        }

Please note that buildingInformation is not generally available and needs to be specifically enabled by our support team. Where it is not enabled the value will be returned as null. notes may be null or empty and any particular note, name or text may be null or white space.

Errors

• Requesting a building you do not have permission for will return 403 You do not have permission to access this building
• Requesting a building that does not exist will return 404 Requested building does not exist

POST: Create Contract

This allows you to create a contract.

Fields

Post

Allocation

Example Request

POST https://api.dwellant.com/contracts

{
            "subject": "subject test",
            "managingAgentId": 1234,
            "propertyReference": "1111",
            "description": "contract description",
            "category": "insurance",
            "referenceNumber": "2",
            "blockIds": [
                4444,
                5555
            ],
            "maxValue": 1000,
            "vatType": "E",
            "contractTolerance": "2",
            "maximumExpectedInvoices": 2,
            "contractRenewalPeriodInDays": 12,
            "startDate": "2021-03-09",
            "endDate": "2021-03-19",
            "assignedGroup": "Gas Safety",
            "allocations": [
                {
                    "recoverability": 1,
                    "scheduleId": "88",
                    "expenseTypeId": "2706",
                    "allocation": "1/2"
                },
                {
                    "recoverability": 1,
                    "scheduleId": "48",
                    "expenseTypeId": "1710",
                    "allocation": "1/2"
                }
            ]
        }

Example Response

{
          "id" : "c1234"
        }

Put: Edit Contract

This allows you to edit a contract. You need to use the Dwellant Contract Id in your urls to specify the contract.

It is important to note that this is a PUT operation not a PATCH so any null fields will be saved as null. The fields work identically to creating a contract via a POST. The single difference is that Allocation is optional and does not need to be provided. Providing an allocation will be marked as a change to the allocation in the contract log.

Fields

Post

Allocation

Example Request

POST https://api.dwellant.com/contracts/123456

{
            "subject": "subject test",
            "managingAgentId": 1234,
            "propertyReference": "1111",
            "description": "contract description",
            "category": "insurance",
            "referenceNumber": "2",
            "blockIds": [
                4444,
                5555
            ],
            "maxValue": 1000,
            "vatType": "E",
            "contractTolerance": "2",
            "maximumExpectedInvoices": 2,
            "contractRenewalPeriodInDays": 12,
            "startDate": "2021-03-09",
            "endDate": "2021-03-19",
            "assignedGroup": "Gas Safety",
            "allocations": [
                {
                    "recoverability": 1,
                    "scheduleId": "88",
                    "expenseTypeId": "2706",
                    "allocation": "1/2"
                },
                {
                    "recoverability": 1,
                    "scheduleId": "48",
                    "expenseTypeId": "1710",
                    "allocation": "1/2"
                }
            ]
        }

Example Response

200 OK

Errors

• Updating a contract to use a different managing agent will return 400 Cannot move contract to a different Managing Agent
• Updating a contract you do not have access to will result in 404 Contract not Found
• Requesting a building you do not have permission for will return 403 You do not have permission to access this building
• Requesting a building that does not exist will return 400 Requested building does not exist
• If required fields are not sent then 400 Bad Request will be returned.

Post: Close Contract

This allows you to close a contract. You need to use the Dwellant Contract Id in your url to specify the contract.

Fields

Post

Example Request

POST https://api.dwellant.com/contracts/123456/close

{}

Example Response

200 OK

Errors

• If the contract cannot be found, then 404 Not Found will be returned.
• If the contract belongs to a different managing agent, then 400 Invalid organisation id will be returned.

GET: Building Contracts

Allows managing agents to retrieve a list of contracts for a building. You can use either:

• The Dwellant Building ID, or
• The Dwellant Managing Agent ID and the Property External ID

The above IDs are provided in the response from a call to GET: Building Details

Example Request

• By Dwellant Building ID 555:
  GET https://api.dwellant.com/buildings/555/contracts
• By Dwellant Managing Agent ID 82734 and Property External ID 12321:
  GET https://api.dwellant.com/buildings/ma/82734/ext/12321/contracts

Example Response

[
          {
            "id": "c34985",
            "contractName": "Communal Cleaning",
            "buildingId": 23984723,
            "managingAgentId": 82734,
            "propertyReference": "bld-889",
            "externalBuildingId": "123-cv",
            "description": "Annual Cleaning Contract",
            "category": "Cleaning",
            "utilitySupplyId": null,
            "referenceNumber": null,
            "blockIds": [
              203498
            ],
            "vatType": "5",
            "startDate": "2022-06-29T00:00:00",
            "endDate": "2023-06-28T00:00:00",
            "contractTolerance": "0.00000",
            "maximumExpectedInvoices": 12,
            "contractRenewalPeriodInDays": 0,
            "assignedGroupId": null,
            "contractTemplate": null,
            "renewalDiscussionPeriodDays": 30,
            "isAcceptanceRequired": false,
            "value": 1293.00000,
            "lock": 2,
            "contractorName": "Liftman Lifts Ltd",
            "contractorReference": "LLL-8602",
            "allocations": [
              {
                "recoverability": 16,
                "scheduleId": null,
                "expenseTypeId": 203498,
                "propertyId": 234798,
                "proportion": "1/1"
              }
            ]
          }
        ]

Errors

• If the building cannot be found, then 404 Building not found will be returned.
• If the building belongs to a different managing agent, then 403 No permission for this building will be returned.

POST: Attach file to Work Order

Request Fields

Accepted file extensions

"pdf", "doc", "docx", "png", "jpg", "jpeg", "gif", "xls", "xlsx", "txt", "mp3", "mp4", "msg", "zip"

Example Request

POST https://api.dwellant.com/workorders/files

{
            "workOrderId" : 822311,
            "fileName": "attachment.txt",
            "file": "--encoded file--"
        }

Example Response

200 OK

Errors

• The specified task does not exist 400 The specified task does not exist.
• File no provided 400 File is required.
• File name no provided 400 File name is required.
• File extension not valid 400 File extension is not valid.
• Request is empty 400 The request can't be empty.
• Not allowed access to task - 403 You do not have permission to attach files to the task.
• See Common Errors for other errors

POST: Create Building Document

This allows you to upload a building document. This can be sent as form-data or JSON. If using JSON, please send the File as encoded base64 string.

Fields

Post

Document Type

Example Request

Form-Data

POST https://api.dwellant.com/documents/create

curl --location --request POST 'api/documents/create' \
        --header 'Authorization: XXXX' \
        --form 'file=@"/C:/file path/file.pdf"' \
        --form 'buildingId="4807"' \
        --form 'startDate="19/03/2021"' \
        --form 'endDate="19/06/2021"' \
        --form 'documentType="13"' \
        --form 'documentTitle="Health & Safety Report 2021"' \
        --form 'metadata="{
                \"Inspection Date\": \"2021-05-23T00:00:00Z\",
                \"inspector\": \"John Stanley\",
            }"'

JSON

POST https://api.dwellant.com/documents/createAsJson

{
            "buildingId": 4807,
            "metadata": "{\"Inspection Date\": \"2021-03-19T09:00:00Z\", \"inspector\": \"John Stanley\"}",
            "startDate": "2021-03-19T09:00:00Z",
            "endDate": "2021-03-20T11:00:00Z",
            "documentTitle": "Health & Safety Report 2021",
            "documentType": 13,
            "fileExtension": "png",
            "fileName": "kc",
            "file": "base64EncodedFileAsString"
        }

Example Response

200 OK

{
          "1234"
        }

Errors

• Requesting a building you do not have permission for will return 403 You do not have permission to access this building
• Requesting a building that does not exist will return 400 Requested building does not exist
• If required fields are not sent then 400 Bad Request will be returned.

GET: Facility Calendar Events

This allows you to retrieve booking information regarding a facility calendar for a specific date.

Example Request

• GET https://api.dwellant.com/facilitycalendar/1233/bookings?date=2021-08-04

Example Response

200 OK

{
            "bookingId": 1353,
            "startTime": "2021-08-04T10:00:00",
            "endTime": "2021-08-04T14:00:00",
            "reference": "E.........a"
        }

Errors

• Facility calendar id no provided 400 Facility calendar id is required.
• Date no provided 400 Event date is required.

GET: Managing Agent Invoice Files

Allows managing agents to download one file for a given invoice id. - If an invoice contains only one main file, the response will be a unique PDF file. - If the invoice has historic (invoice replacements) or additional files, the response is a ZIP file.

Example Request

• GET https://api.dwellant.com/invoices/files/1233

Key PDF file response headers

Key ZIP file response headers

Example Response

200 OK

Errors

• 401 Unauthorised if the requester is not a managing agent.
• 401 Invalid invoice id (api user may not have enough privileges to access a given invoice).
• 404 Invoice not found (invoice does not exist in the system).

POST: Notes

Request Fields

Example Request

POST https://api.dwellant.com/notes

{
            "externalId": "ABC",
            "buildingId": 5744,
            "tenantId": "NEEDL001",
            "contactId": "C-123",
            "unitId" : "0002",
            "propertyId": "19801",
            "managingAgentId": 1234,
            "noteCreatedDate": "2022-04-23T18:25:43Z",
            "author": "example@managing.agent.com",
            "subject": "Subject Matter",
            "text": "Text content",
            "category": "Accident",
            "priority": "High",
            "nextActionDate": "2022-04-23T18:25:43Z",
            "startTime": "09:10",
            "isClosed": "false"
        }

Example Response

{
            "noteId": 219079,
            "threadId": 163526
        }

Errors

• Requesting a Managing Agent you do not have permission for will return You do not have permission to this Managing Agent
• Requesting a building that does not exist will return Building not found
• Requesting a building that does not belong to the provided Managing Agent will return Building does not belong to Managing Agent
• Providing an Importance that is not recognized will return Importance not recognized
• Requesting a Managing AGent that does not exist will return Managing Agent not found
• If you provide a Unit Id and or Property Id you must provide both. If you don’t then the following will be returned If UnitId or PropertyId are provided then both must be provided

POST: Reports

This runs and fetches a custom report in real time.

Request Fields

These depend on the query being run

Example Request

POST https://api.dwellant.com/reports/1254

{
          "startDate": "2022-04-01",
          "finishDate": "2022-04-15",
        }

Example Response

[
          ["columnA", "columnB", "columnC"],
          ["valueA1", "valueB2", "valueC3"],
          ["valueA2", "valueB2", "valueC3"]
        ]

Errors

• Requesting a custom query that does not exist will return Query does not exist
• Requesting a custom query that is not configured to be used by the API will return Query not enabled for API

POST: Overnight Reports

This subscribes to a report (if a subscription does not exist) and returns a download URL (if the report has been run). The file referenced by the URL is in tab-separated text format

Request Fields

These depend on the query being run, but _frequencies is compulsory. Valid values for _frequencies are:

• Tomorrow
• Mondays
• Tuesdays
• Wednesdays
• Thursdays
• Fridays
• Saturdays
• MonthStarts
• MonthEnds

They may be combined using comma separators, for example: Mondays, Wednesdays, Fridays

Example Request

POST https://api.dwellant.com/overnight-reports/1254

{
          "_frequencies": "Mondays, Wednesdays, Fridays",
          "startDate": "2022-04-01",
          "finishDate": "2022-04-15",
        }

Example Response

For a new subscription, where the report has not yet been run.

{
           "subscriptionId": 983181,
           "nextRunDate": "2024-06-05",
           "lastRunTime": null,
           "downloadUrl": null
        }

For an existing subscription, where the report has been run.

{
           "subscriptionId": 983181,
           "nextRunDate": "2024-06-07",
           "lastRunTime": "2024-06-05T10:15:20",
           "downloadUrl": "https://............"
        }

The downloadUrl is valid for 20 minutes from the time the response is returned.

Errors

• Requesting a custom query without the "_frequencies" parameter _frequencies not specified
• Requesting a custom query that does not exist will return Query does not exist
• Requesting a custom query that is not configured to be used by the API will return Query not enabled for API

Webhooks

Update Requests

When this webhook is configured we send updates to Requests to the configured webhook. We only send updates to Requests that have been created by the API.

Updates stream in real-time from Dwellant with a single user action often generating multiple updates.

For example when a user completes a request we send:

• TaskChanged - Resolution time
• TaskStatusChanged - Status before and after
• TaskChanged - Resolver
• TaskCommented - Includes comment and any attachment
• TaskCompleted - We delay sending this by one minute so in ordinary circumstances it will be the last message you receive

All messages are recorded to our database before sending them - if we are unable to connect to your endpoint we will retry sending the message five times. After this we can manually kick of a resend after your endpoint has come back online.

The JSON object we send has an identical schema in all cases - however the fields content will vary by EventType

Example request change webhook payload

{
          "id": 2319057,
          "parentId": 2319051,
          "parentExternalId": "45101",
          "externalId": "45102",
          "changeId": 8955279,
          "eventType": "TaskCommented",
          "eventDateTime": "2022-02-18T10:24:30.3206025Z",
          "comment": "This is a sample comment",
          "description": "Comment added [Jane Doe of Example Contractor]: \"This is a sample comment\"",
          "attachments": [
            {
              "name": "sample.pdf",
              "url": "https://_beta-secure.dwellant.net/Task/TaskChangeViewAttachment/ABCDE...ZZZZ=="
            }
          ],
          "updatedBy": "Jane Doe",
          "updatedByEmail": "Jane.Doe@dwellant.com",
          "taskSatusBefore": "InProgress",
          "taskSatusAfter": "Completed"
        }

EventType is a task event type, defined as one of:

• AttachmentAdded
• AttachmentRemoved
• EmailSent
• QuotationAccepted
• QuotationPriceAdjustment
• ReplyToEmail
• RfqsSent
• TaskChanged
• TaskCommented
• TaskCompleted
• TaskStatusChanged
• WorkOrderPdfReissued

TaskStatusBefore and TaskStatusAfter will be empty strings if the status has not changed. If they are present they will be a request status defined as one of:

• AwaitingQuotations
• AwaitingRamsApproval
• AwaitingRamsDocuments
• Closed
• Completed
• ContractAssigned
• InProgress
• InvoiceBeingProcessed
• InvoiceDeleted
• InvoicePaid
• InvoiceUploadRequired
• QuotationsComplete
• QuotationsPrecursor
• Transferred
• UnderConstruction
• WorkOrderPrecursor

Note Change

This web hook should be configured at managing agent level. When a note changes, a notification is sent.

Fields

Tenant Fields

Example Notification

{
            "threadId": 129687,
            "noteId": 174922,
            "externalId": "n456",
            "subject": "Test subject",
            "text": "Test description",
            "category": null,
            "priority": "Medium",
            "updateTime": "2022-11-03T14:01:25",
            "nextActionDate": null,
            "startTime": null,
            "isClosed": false,
            "isDeleted": false,
            "author": "user@test.com",
            "attachmentCount": 0,
            "managingAgentId": 789456,
            "externalManagingAgentId": "123",
            "externalBuildingIds": [
                "40052"
            ],
            "externalUnitId": null,
            "externalTenants": [
                {
                    "tenantId": "T-53",
                    "contactId": "2541234"
                }
            ]
        }

Security

Overview

You will be given a Dwellant ID (unique organisation id) and the ability to generate an Authorization Key. You will need to pass this in the headers of all your requests using Basic Authentication. Failing to do so will result in all responses being 403 Forbidden.

Key Setup

In the Dwellant site you will generate a key. This is available under Core Data => Authentication Keys.

Here you can generate your keys for each available environment. Clicking create presents you with this screen:

Two keys are listed.

• Key 1: Used in the Authorization Header
• Key 2: Used in the x-api-key Header

These keys are not saved in our system. You can not view them again after you close the page. If you loose them you can use the Reset button. This generates new keys which replace the old keys.

Requests

Each organisation has a unique Dwellant ID (this is how we know which organisation to return data for). You concatenate the two together in the form ID:Key. This is then base 64 encoded and prefixed with “Basic” (quotes omitted). So for example:

A contractor with Dwellant id: 1756

A key is generated: mafaDmb28t5EgqK2jGV+ftNRbWVUqcdz317PAygIhcY36oEVGJmS+w==

Concatenate ID and Key: 1756:mafaDmb28t5EgqK2jGV+ftNRbWVUqcdz317PAygIhcY36oEVGJmS+w==

Base 64 Encode them: MTc1NjptYWZhRG1iMjh0NUVncUsyakdWK2Z0TlJiV1ZVcWNkejMxN1BBeWdJaGNZMzZvRVZHSm1TK3c9PQ==

Prefix with Basic: Basic MTc1NjptYWZhRG1iMjh0NUVncUsyakdWK2Z0TlJiV1ZVcWNkejMxN1BBeWdJaGNZMzZvRVZHSm1TK3c9PQ==

Pass this in a header called Authorization

This header is then sent for all calls made for this organisation.

In addition an x-api-key header must also be sent for all requests for this organisation. The value is generated using the same method as generating the Authorization Key but using key 2.

Thus for one organisation you will need to send two headers which will remain the same for each request.

All requests must be sent over HTTPS.

curl -i -H 'Accept:application/json' -H 'Authorization:Basic base64encodeduserpass' -H 'x-api-key:generatedApiKey' https://api.dwellant.com/workorders/12345

Common Errors

• 401 Unauthorised
  • Probably due to wrong Organisation ID
• 403 Forbidden
  • Probably due to wrong API key,
  • or x-api-key not set,
  • or possibly the wrong URL
• 429 Rate limit exceed
  • Rate limiting is configured in the AWS API Gateway, please consider if you are calling to frequently, otherwise contact us.
• 400/404/409/410
  • The response likely has information regarding why this failed
• Authorization header requires ‘Credential’ parameter. Authorization header requires ‘Signature’ parameter. Authorization header requires ‘SignedHeaders’ parameter. Authorization header requires existence of either a ‘X-Amz-Date’ or a ‘Date’ header.
  • Almost certainly due to the wrong url being used.

Webhook Setup

On the Dwellant site you can set up webhooks. Currently this supports updates on requests only. All webhook Requests are sent as an HTTP POST.

There are six fields:

• Type (Authentication Type - Currently Basic Auth only.)
• URL (The base url of your webhook)
• Request Slug (The specific endpoint for receiving request updates. This is appended to the URL)
• Note Slug (The specific endpoint for receiving note updates. This is appended to the URL)
• Username
• Password (After setting this you will no longer be able to view it)