Introduction

Welcome to the Roamler API documentation. This documentation is intended for anyone who would like to consume task data from the Roamler Platform. You can obtain API key’s in our Customer Portal.

There are uses for the API, but to get you started we have specified 3 different scenario’s for you to inspire and start programming away!

Scenario’s

Getting Roamler data to use in my application – Realtime

I have an application that needs to get the data from Roamler as soon as it is validated.

These steps need to be taken to get the data in in realtime:

Configure webhook

The webhook fires a request with the relevant URL strings in the body. The URL can directly be used to fetch all of the submission associated information.

Get a Submission

This request delivers all the text information from the submission. If pictures are taken, the URLs to retrieve the pictures will be included in the body.

Get a Photo (n photos)

This request will directly give the binary data of the photo.

Getting Roamler data to use in my application – Batched

When it is not possible to configure an endpoint for the webhook, or there are other reasons to not use the webhook as a trigger, data can also be fetched periodically. In this scenario we assume that data needs to be fetched every hour and that a full list of projects need to be collected first. (e.g. to make a total backup of the projects done at Roamler)

Get all jobs

This call will give you the projects that are accessible to the API key. For every project it is possible to fetch the detailed information like questions and answers. To do so, use the

Get a specific Job

This will list the detailed information of a specific job.

Finally, the completed submissions of a job can be retrieved by using

Get Submissions of a job

You should use FromDate as a parameter to ensure long loading times and fetching more data then necessary.

After this you can fetch the information per specific job

Get a Submission

This request delivers all the text information from the submission. If pictures are taken, the URLs to retrieve the pictures will be included in the body.

Get a Photo (n photos)

This request will directly give the binary data of the photo.

Getting Roamler data to use in 3rd party systems

This is the scenario where you want to transfer the data to systems like SalesForce, Navision, Dropbox or other 3rd party systems that already have an API for loading in data. First check if it is possible to use a system like Zapier. We are currently working on an official Zapier plugin that makes it even easier for you to make recipes.

If you want to write your own bridge between Roamler and a 3rd party system, that’s totally fine. Use the different calls and techniques as described above.

Authentication

Roamler uses API keys to allow access to the API. You can register a new API key at our customer portal. There are two ways to authenticate your API calls.

Authenticate via URL

To authorize a call via the url, use this code:

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/Jobs?apiKey=MY_API_KEY",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

You can add apiKey to the url parameters to authenticate API calls.

Example: https://api-customer.roamler.com/v1/Jobs?apiKey=MY_API_KEY

Authenticate via header

To authorize a call via a header, use this code:

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/Jobs",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "X-Roamler-Api-Key: MY_API_KEY",
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

You can add X-Roamler-Api-Key to your request headers to authenticate API calls.

Example: X-Roamler-Api-Key: MY_API_KEY

Webhook

The webhook returns JSON structured like this:

{
  "Id": "3354h3n436879257n2463",
  "Attempt": 1,
  "Properties": {},
  "Notifications": [
    ...
    {
      "Action": "submission-completed",
      "title": "string",
      "date": "datetime",
      "url": "url",
      "jobUrl": "url"
    }
    ...
  ]
}

Webhook description

Configure a webhook via our customer portal.

Jobs

Get all jobs

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/Jobs",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "X-Roamler-Api-Key: MY_API_KEY",
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

The above command returns JSON structured like this:

[
 ...
  {
    "hRef": "string",
    "id": 0,
    "title": "string",
    "description": "string",
    "liveDate": "datetime",
    "closeDate": "datettime",
    "isActive": true,
    "questions": [
      {
        "hRef": "string",
        "id": 0,
        "code": "string",
        "questionType": "None",
        "text": "string",
        "isOptional": true,
        "answerOptions": [
          {
            "id": 0,
            "text": "string",
            "code": "string"
          }
        ],
        "imageHash": "string"
      }
    ],
    "attributeDefinitions": [
      {
        "name": "string",
        "id": 0,
        "type": "Unknown",
        "options": [
          {
            "id": 0,
            "value": "string"
          }
        ]
      }
    ]
  }
 ...
]

This endpoint retrieves all jobs.

HTTP Request

GET /v1/Jobs/

URL Parameters

Parameter	Default value	Required	Description	Parameter Type	Data Type
page	0	No	Page of the result	Query	Integer

Get a specific job

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/Jobs/{JobId}",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "X-Roamler-Api-Key: MY_API_KEY",
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

The above command returns JSON structured like this:

{
  "hRef": "string",
  "id": 0,
  "title": "string",
  "description": "string",
  "liveDate": "datetime",
  "closeDate": "datetime",
  "isActive": true,
  "questions": [
    {
      "hRef": "string",
      "id": 0,
      "code": "string",
      "questionType": "None",
      "text": "string",
      "isOptional": true,
      "answerOptions": [
        {
          "id": 0,
          "text": "string",
          "code": "string"
        }
      ],
      "imageHash": "string"
    }
  ],
  "attributeDefinitions": [
    {
      "name": "string",
      "id": 0,
      "type": "Unknown",
      "options": [
        {
          "id": 0,
          "value": "string"
        }
      ]
    }
  ]
}

This endpoint retrieves a specific job.

HTTP Request

GET /v1/Jobs/{JobId}

URL Parameters

Parameter	Default value	Required	Description	Parameter Type	Data Type
JobId	null	Yes	Id of the job	Path	Integer

Get locations of a job

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/Jobs/{JobId}/Locations",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "X-Roamler-Api-Key: MY_API_KEY",
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

The above command returns JSON structured like this:

[
 ...
  {
    "id": 0,
    "address": "string",
    "longitude": 0,
    "latitude": 0,
    "attributes": [
      {
        "name": "string",
        "attributeDefinitionId": 0,
        "type": "Unknown",
        "value": 0,
        "text": "string"
      }
    ]
  }
 ...
]

This endpoint retrieves locations for a specific job. You'll get all locations that are specified by Roamler for this job.

HTTP Request

GET /v1/Jobs/{JobId}/Locations

URL Parameters

Parameter	Default value	Required	Description	Parameter Type	Data Type
JobId	null	Yes	Id of the job	Path	Integer
showCustomerAvailableAttributes	false	No	Indicates if you want to see available location attributes	Query	Boolean

Add location id to a job

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/jobs/{jobId}/locations/{locationId}",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_HTTPHEADER => array(
        "X-Roamler-Api-Key: MY_API_KEY",
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

The above command returns JSON structured like this:

{
  "success": true,
  "error": "string"
}

This endpoint adds a location id to an existing job. This endpoint isn't publicly available for every job. Please contact Roamler if you want to use it.

HTTP Request

POST /v1/jobs/{jobId}/locations/{locationId}

URL Parameters

Parameter	Default value	Required	Description	Parameter Type	Data Type
JobId	null	Yes	Id of the job	Path	Integer
locationId	null	Yes	Id of the location	Path	Integer

Get submissions of a job

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/Jobs/{JobId}/Submissions?fromDate=2017-12-01&toDate=2017-12-31",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "X-Roamler-Api-Key: MY_API_KEY",
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

The above command returns JSON structured like this:

[
 ...
  {
    "hRef": "string",
    "submitDate": "2017-12-18T09:44:49.342Z"
  }
 ...
]

This endpoint retrieves submission urls for a specific job.

HTTP Request

GET /v1/Jobs/{JobId}/Submissions

URL Parameters

Parameter	Default value	Required	Description	Parameter Type	Data Type
JobId	null	Yes	Id of the job	Path	Integer
fromDate	null	Yes	The start datetime of the timeframe you want to query for submissions	Query	Datetime
fromDate	null	Yes	The end datetime of the timeframe you want to query for submissions	Query	Datetime
page	1	No	The page of results you need	Query	Integer
take	50	No	The amount of submissions per page (max 1000)	Query	Integer

Submissions

Get a submission

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/submissions/{submissionId}",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "X-Roamler-Api-Key: MY_API_KEY",
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

The above command returns JSON structured like this:

{
  "hRef": "string",
  "jobHRef": "string",
  "id": 0,
  "jobTitle": "string",
  "photoGalleryHRef": "string",
  "location": {
    "id": 0,
    "address": "string",
    "longitude": 0,
    "latitude": 0,
    "attributes": [
      {
        "name": "string",
        "attributeDefinitionId": 0,
        "type": "Unknown",
        "value": 0,
        "text": "string"
      }
    ]
  },
  "submissionDate": "datetime",
  "questions": [
    {
      "hRef": "string",
      "id": 0,
      "code": "string",
      "questionType": "None",
      "text": "string",
      "isOptional": true,
      "answerOptions": [
        {
          "id": 0,
          "text": "string",
          "code": "string"
        }
      ],
      "imageHash": "string"
    }
  ],
  "answers": [
    {
      "questionId": 0,
      "value": 0,
      "answerOptions": [
        {
          "id": 0,
          "text": "string",
          "code": "string"
        }
      ],
      "text": "string",
      "latitude": 0,
      "longitude": 0,
      "accuracy": 0,
      "userAnswerId": 0,
      "photoUrl": "string",
      "answerDate": "datetime"
    }
  ],
  "data": {
    "location": {}
  }
}

This endpoint retrieves a single submission. Most of the times you don't have to generate this url yourself. The webhook and the /v1/Jobs/{JobId}/Submissions will return the preformatted url to you in the href field. However, you may want to add some url parameters to get specific information in the response.

HTTP Request

GET /v1/submissions/{submissionId}

URL Parameters

Parameter	Default value	Required	Description	Parameter Type	Data Type
submissionId	null	Yes	The id of the submission	Path	Integer
includeAnswers	true	No	Indicating if you want to get the answers	Query	Integer
showCustomerAvailableAttributes	true	No	Indicates if you want to get task attributes	Query	Integer
includeQuestions	false	No	Indicates if you want to get the questions of the job	Query	Integer

Get a photo

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/submissions/{submissionId}/image/{photoId}",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "X-Roamler-Api-Key: MY_API_KEY",
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

This endpoint retrieves a photo.

HTTP Request

GET /v1/submissions/{submissionId}/image/{photoId}

URL Parameters

Parameter	Default value	Required	Description	Parameter Type	Data Type
submissionId	null	Yes	The id of the submission	Path	Integer
photoId	null	Yes	The id of the photo	Path	Integer

Me

Get info about the customer

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-customer.roamler.com/v1/me",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "X-Roamler-Api-Key: MY_API_KEY",
        "content-type: application/json"
      )
    ));

    $response = curl_exec($curl);
    $error = curl_error($curl);

    curl_close($curl);
?>

The above command returns JSON structured like this:

{
  "name": "CustomerName",
  "logoHRef": "urlToLogo",
  "expirationDate": "2018-03-27T12:15:52.517Z"
}

This endpoint retrieves info about the customer.

HTTP Request

GET /v1/me

Disclaimer & use policy

The Roamler API is in beta and should only be used in a production environment after negotiating with your Roamler counterpart. Roamler is not responsible for any losses, direct or indirect resulting as a malfunctioning from the API. Using the API also means that you will be using our API fairly. Knowing that we are still in beta, we might ask you to slow down if we see that our systems are suffering from your requests. You will also let us know when you see that your requests have a significant impact on the speed of our systems.

By using the API you also agree on our Responsible Disclosure Agreement. Don’t sell any vulnerabilities to the NSA, FBI or Darkweb, but share them with responsibledisclosure@roamler.com.