Guide: API

See also the API Reference.

This guide assumes you’re familiar with REST APIs, particular concepts like HTTP methods and JSON.

Some examples will use curl – this command line tool is usually pre-installed with most Linux distributions, and is also available for Windows. If this is new to you, don’t worry, it’s just a tool for issuing HTTP requests, you’ll still be able to follow the examples. Curl is convenient for experimenting with REST APIs and seeing immediate results.

Authentication

Example: list users

Getting your documents

Processing documents

Connections to the API are authenticated using HTTP Basic access authentication, and so you need a user name and a password.

• the user name is always “api” (lower-case)
• the password is the API key generated by tapping Generate key for Custom on the Security tab in the management app – tap on Copy to copy it to the clipboard

Note that every time you generate a new key, you replace (and so deactivate) the old one.

Your account name (that’s the user name you use to access the management app) is specified in the URL, which has the form:

https://account.mobilit.ee/api/v1/type/parameters

Accessing the API with curl then looks like:

curl -u api:your-api-key-goes-here …

Command:

curl -u api:api-key https://account.mobilit.ee/api/v1/users

Response:

[
  {
    "id": "otto"
  },
  {
    "id": "aarunya"
  },
  {
    "id": "keith"
  },
  {
    "id": "grete"
  }
]

Hint: use jq to layout the output in a more readable format.

To get your documents, you must subscribe to the template. Provide an HTTP/S URL, and each document will be POSTed to that URL as it arrives. (Note, use HTTPS, not HTTP, if you want your data to remain secure, otherwise it won’t be encrypted.)

Command:

curl -u api:api-key https://account.mobilit.ee/api/v1/subscriptions -X POST -d @request.json

request.json:

{
  "template_id": "jobsheet",
  "target_url": "https://my.server.com/data-catching-servlet"
}

The request document must contain the template ID (the name you gave it when you created it) – example here is “jobsheet”.

Response:

{
  "id": "1200958169"
}

The response contains the subscription ID. You need this if you want to delete the subscription later using the API.

You can see (and, if you choose, delete) the subscription from the Security tab by tapping Manage connections.

Documents will be POSTed to the URL configured for the subscription. Your code must reply with an appropriate HTTP status code, either:

• 2xx – you accept and assume responsibility for the document, and mobilit.ee will discard its copy
• anything else – mobilit.ee will try again later, up to 20 times at progressively longer intervals, for the following week

You can see a sample JSON document for any template by using the API. This will give you some idea of what the data you receive will look like.

Command:

curl -u api:api-key https://account.mobilit.ee/api/v1/templates/jobsheet/sample

The URL contains the template ID – again, the example here is “jobsheet”.

Response:

{
  "_id": "doc_user_sample",
  "_rev": "1-0123456789abcdef0123456789abcdef",
  "properties": {
    "started": "2017-08-23T12:36:53.017Z",
    "template_name": "jobsheet",
    "template_version": 1,
    "lastSave": "2017-11-09T15:15:35.801Z",
    "firstSave": "2017-08-23T12:37:02.281Z"
  },
  "content": {
    "customerName": {
      "value": "text"
    },
    "dateAttended": {
      "value": "2017-08-29"
    },
    "costPerHour": {
      "value": 0
    },
    "hours": {
      "value": 0
    },
    "customerSignature": {
      "value": "data:image/png;base64,iVBORw0K…RK5CYII=",
      "at": "2017-09-18T12:58:17.971Z"
    }
  },
  "revs": []
}

Things to notice:

• Every document has an “_id”, starting doc_, followed by the name of the uploading user, then a unique sequence of characters – for example, doc_otto_E8gOJVDyvsU
• There are “_rev” and “revs” properties – these are used internally to manage revisions of the document, and can be ignored
• The “properties” section contains standard information about each document, including:
• name and version of the template on which this document was based
• the date and time it was created (editing began)
• the date and time it was first saved
• the date and time of the last time it was saved
• The “content” section contains data for the fields you defined in your template design.

In the content, most fields have a “value” property, which is the main value captured. Some also provide additional information. These are described on the Component Directory, but note that the names given there are as they appear in Zapier, and differ slightly from their API variants.

For example, for capture-signature, two values are listed:

• id
• id_at

To make integration with other products simpler, data delivered to Zapier is “flattened”. Also, as a shortcut, the primary value has “value” omitted from its Zapier name. When accessing a document delivered via the API, these become:

• .content.id.value
• .content.id.at