This page describes each of the operations that the platform supports and the information that each one expects to receive and will send back. All information is sent and received in JSON format and you should set the Content-Type header accordingly. All of the operations below require your partner key, as described in Getting Started, and this is not repeated for each operation.

1. Ordering a survey

Surveys are ordered by sending a POST request to /api/v1/survey. The body of the request should contain the following fields. Fields marked as required must always be supplied and the order will be refused if any of them are missing, in which case the response will tell you which ones were the problem.

Field	Required?	Description
claim_ref	Yes	Your own reference for the claim this survey relates to. We do not check this value but we will include it in everything we send you about the survey so that you can match it up on your side. It can be any text you like, up to a reasonable length.
property_address	Yes	The full address of the property to be surveyed. Please include the street number, street name, suburb and district. Incomplete addresses may result in delays while our dispatch team confirms the location with you by telephone.
priority	No	How urgently the survey is required. One of normal, rush or emergency. If not supplied, normal is assumed. Rush surveys are completed within 12 business hours and attract a surcharge as set out in your service agreement. Emergency surveys are dispatched immediately, day or night, and must be pre-approved by your account manager.
notify_url	No	The web address we should send the results to once the survey is complete. See Webhooks below.

If the order is accepted you will receive a reply containing the survey number, which you should keep. The survey will initially be in the pending state.

2. Checking on a survey

To find out where a survey is up to, send a GET request to /api/v1/survey/{id}, where {id} is the survey number you received when you ordered it. The reply will contain the details you supplied when ordering, along with a status, which will be one of the following:

• pending - the survey is in our dispatch queue and is waiting for a pilot
• in_progress - the survey has been flown, or is being flown, and our analysts are working on it
• done - the survey is complete and the results are included in the reply

When a survey is done, the reply will also include the results of the assessment. The most important of these is the damage_score, which is a whole number from 1 to 10 where 1 means no visible damage and 10 means the structure is a total loss, together with a category (none, minor, moderate, severe or total) which is worked out from the score, and a flag indicating whether our analysts believe there is a risk to the structure of the building which should be assessed by an engineer before anyone enters it. The reply will also include links to the aerial photographs taken during the flight. Photographs are kept for 90 days and you should download any you need to keep within that time.

You may also retrieve all of the surveys ordered by your organisation by sending a GET request to /api/v1/surveys/list. This is intended for reconciliation and reporting purposes and should not be used to check on individual surveys.

3. Cancelling a survey

Surveys cannot be cancelled through the platform once they have been ordered. If you have ordered a survey in error, please contact our dispatch desk by telephone as soon as possible. Surveys which are cancelled before a pilot has been dispatched will not be charged.

4. Webhooks

If you supplied a notify_url when ordering a survey, then when the survey is complete our platform will send a POST request to that address containing the same information that you would receive by checking on the survey. Your system should reply with a success response promptly. Please make sure that the address you supply can be reached from the internet and that it is not protected by a login, as our platform has no way of logging in. We will tell you which kind of notification it is in an HTTP header so that you do not need to inspect the body to find out.

If your system does not respond, or responds with an error, we will try again several times over the following 24 hours.

5. Errors

If something goes wrong with your request the platform will reply with an error. The reply will include a status number and a short code describing the kind of problem. Most errors are caused by missing or incorrect information in the request, in which case please check the request against this page before contacting support.

Last updated: 09/08/2018