Integrating the Field Services API

Search…
KEY TERMS
A work order is a set of elementary tasks that must be performed by a field technician. These tasks are related to one or more photos that are requested from the technicians. End-users can also specify other parameters (a category, a number, etc.)
 A task in this context refers to a specific checkpoint that can be validated via the Deepomatic application. There may be several checkpoints to be validated on a single photo, or conversely there may be several photos needed to validate a single checkpoint. The most basic checkpoint is the presence of a certain type of photo requested from the field technician, but much more complex checkpoints can be implemented in your Deepomatic application.
A task group corresponds to a grouping of several tasks. This grouping is primarily for display purposes. All the tasks that are grouped together are generally about the same photo. We can then also consider that a task group corresponds to a type of photo requested from the field technician.
A state in this context corresponds to the current status of a given control point for your work order. It is built from the aggregation of the results of the workflow executions.
This is a REST API.
Since authentication parameters are transmitted through HTTP headers, and the transferred data may contain sensitive information, it is strongly recommended to use HTTPs with secure encryption.
All endpoints must end with a slash / unless specified explicitly.
Body parameters are JSON data. They must be sent with an application/json MIME type. The root element of the JSON that is sent must be an object.
Prerequisites
Once you have a site that is deployed, you can call an API that is part of your application. Contact your Customer Success Manager to deploy a site.
Global diagram of the API
This diagram is indicative. It includes most of the endpoints shown below, and suggests a way of interacting with the API. Some endpoints are marked as optional but are recommended, depending on what is hardcoded on the mobile application side. 
The goal is to have as few elements hardcoded as possible to make the integration as scalable as possible, and thus allow business users to make changes without having to touch the integration code. 
Endpoints
For some endpoints, the format described is generic, but you will need to consult the page of the application you are integrating on the Deepomatic platform to get the exact list of fields to send in your requests, or to know the exact format of the API return.
post
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/
Create a work order
get
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/
Retrieve a list of work orders
get
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/{id}/
Retrieve a work order
get
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/{id}/timeline/
Retrieve a work order (timeline)
delete
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/{id}/
Delete a work order
put
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/{id}/
Update a work order
patch
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/{id}/metadata/
Update metadata of a work order
put
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/{id}/metadata/
Update a metadata
get
https://api.{$SITE_ID}.customers.deepomatic.com
/V0.2/task-groups/{id}
Retrieve a task group
get
https://api.{$SITE_ID}.customers.deepomatic.com
/V0.2/task-groups/
Retrieve all task groups
post
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/{id}/analyze/
Analyze inputs
post
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/{id}/analyze/callback/
Analyze inputs with callback
Here is an example of inputs to send for an application requiring four inputs, two images, a text and a number.
1
"inputs": [
2
            {
3
                'name': 'windshield_image',
4
                'data':
5
                {
6
                    'type': 'image',
7
                    'value': 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRw...'
8
                },
9
                'metadata': {}
10
            },
11
            {
12
                'name': 'dog_image',
13
                'data':
14
                {
15
                    'type': 'image',
16
                    'value': 'https://link/to/my/image/dog.jpg'
17
                }
18
            },
19
            {
20
                'name': 'anything',
21
                'data':
22
                {
23
                    'type': 'text',
24
                    'value': 'something'
25
                }
26
            },
27
            {
28
                'name': 'pi',
29
                'data':
30
                {
31
                    'type': 'number',
32
                    'value': 3.14
33
                }
34
            }
35
    ]
Copied!
patch
https://api.{$SITE_ID}.customers.deepomatic.com
/v0.2/work-orders/{id}/tasks/{task_id}/correction/
Correct a task