Developer Documentation

The FORMATION REST API enables FORMATION customers and partners to integrate relevant backend and IOT/tracking systems with FORMATION.

The FORMATION API allows you to:

  • Update locations and meta data of objects in FORMATION. Add sensor measurements from your IOT. Integrate status updates from your ERP software.
  • Access tracking, usage, and access data for objects and break them down by area, time, type, and other criteria. Perfect for reporting, visualizations/dashboards, etc.
  • Poll for recent updates and propagate updates to your other systems.

Typical places to integrate our API would be backend systems that you control. For example: ERP systems or IOT systems (position updates, sensor readings, etc.) that are deployed in your workplace.

Getting started with the REST API or the FORMATION Agent

To use the API or the FORMATION agent, you need the following bits of information that will be provided by FORMATION:

  • A FORMATION workspace and the name and id of this workspace. Typically this is created by FORMATION.
  • A valid JWT token; you can request one by contacting us.

Note, this API is intended for our partners and customers. Please coordinate with us before trying out our API.

Using the FORMATION Agent

For some IOT integrations you can use the FORMATION Agent in your company network (requires access to our cloud platform) or if your systems are cloud accessible inside our cloud hosted solution. We can already integrate several standardized solutions that are commonly used and we are constantly adding more. This includes Omlox support via our Deephub module.

FORMATION regularly publishes new versions of the FORMATION Agent on Docker Hub. Refer to the documentation there usage and configuration.

Contact our sales and partner teams to learn more about the features and possibilities that we have for integrating your IOT and backend systems into FORMATION.

Using the JWT token

To use the token, you must provide an Authorization header with a Bearer token and your JWT as the value. So Authorization: Bearer XXXXXXXXXX where XXXXXXXXXX is the apiAccessToken.token in the token api response from our login API or the token that we provide to you.

Required headers:

ContentType: application/json
Authorization: Bearer XXXXXXXXXX

Updating external objects

The most common reason to use our API is updating the status of external objects that you control in our system. This can be done withour external objects API: POST /groups/<groupID>/externalObjects. An external object is something with a globally unique id that exists either in your physical workplace (a machine, a product, supplies, etc.) or something that exists in one of your software systems. The updates may be triggered manually or via some IOT or other software integration.

When you update an object, the corresponding object on the map in the FORMATION app is updated.

curl -X 'POST' \
  'https://api.tryformation.com/groups/<groupID>/externalObjects' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXX'
  -d '[{
	  "externalId": "myobjectid",
	  "locationUpdate": {
		  "newPosition": {
			  "lat": 51.99893651296793,
			  "lon": 13.002826256576668
		  }
	  },
	  "fieldValues": [{
		 	"type": "String",
			"field": "myfield",
			"value": "123"
		}, {
			"type": "Category",
			"field": "color-code",
			"value": {
				"namespace": "color ",
				"categoryName": "red"
			}
		}
	]
}]'
  • externalId: Required. A globally unique identifier for your external object. There can be only one object with this id in our system. And if that object already exists in another workspace, you won’t have the right to update it. Make sure that you always use the same id to refer to your objects. UUIDs are good for this.
  • locationUpdate. Optional. A new location in WGS 84 decimal form with a lat, lon, and optionally an alt field for the altitude (meters above sea level)
  • fieldValues. Optional. Field values. While you can use free form fields, you should coordinate with FORMATION support to ensure the field definitions are created and properly setup. You may do this before or after you start sending field values. Typical fields would be related to sensor readings, things like battery strength, or business information such as product/item types and identifiers. FORMATION supports string fields, numeric fields, and category fields. These fields may be used in the app for reviewing information and may also be used for custom dashboards, heatmaps, and other features.
  • initialExternalObject. Optional. You can specify some values for things like the object title here. If the object does not exist yet, it will get created with these values. Note, you can always edit the object in the FORMATION app as well after you call this for the first time. The initialExternalObject settings are ignored for updates to existing objects.

You MUST specify either a locationUpdate and/or fieldValues. Empty updates are not allowed. The first update MUST contain a locationUpdate.

QR Code Tracking

The simplest level of tracking that FORMATION provides works via the FORMATION app. You simply scan a QR Code with a link to the update, the app opens, and then you can update the location of the object from inside the app.

The FORMATION app supports deep linking to objects. To trigger the asset tracking flow in FORMATION, all you need is a link that looks like this:

https://app.tryformation.com/#page=Map&id=1234567890

The link has a single parameters:

  • id. This is the id of an object you want to track. Ids should be unique. Once associated with an object in FORMATION, the ownership cannot be changed.

What happens when you scan the qr code or enter the link manually depends on whether we have seen the code before.

  • For new codes: we trigger the create a new tracked asset flow. You can give the object a name and create it for the first time.
  • For codes you have used before: it opens the object and offers you to update the location of the object
  • For codes that are associated with object actions (like opening a Poll, opening the map, etc.), it performs the action. You can control this behavior by editing the object and associating qr codes with content elements.

Swagger API documentation

Note. documenting our APIs is a work in process and not all APIs are relevant to use for most integrators. Always talk to us before planning a deep integration. We can help!

Rate limiting and usage

  • We provide freemium API access with a limited number of API calls per month upon request for all our customers.
  • Talk to our sales team for more options for API Rate limits, access scope, and quality of service, etc.

Support

If you have any issues with using this API or questions about the API, contact our support team.