Integrating the Augmented Technician API

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 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 your application has been deployed, you can call an API that has been deployed as part of your application. To do so, however, the two following conditions must be met:
your workflow must be compatible - it must define outcomes that are the result sent within the API
Add a native API on top of a workflow
/deepomatic-drive/configuring-visual-automation-applications/assembling-workflows/add-a-native-api-on-top-of-a-workflow
you must have added the customer-api service to your application
Use Deepomatic CLI
/deepomatic-drive/configuring-visual-automation-applications/publishing-visual-automation-apps/use-deepomatic-cli
post
Create a work order
https://api.{$SITE_ID}.customers.deepomatic.com/v0.2/work-orders/
Create a new work order.
Request
Response
Request
Headers
Authentication
required
string
Deepomatic API Key.
Body Parameters
name
required
string
Name of the work order
You can set the value of your choice as a name. It is recommended that you set a unique name per work order. If your system keeps track of work orders you should probably use you internal work order id as a name.
metadata
required
object
Dictionary to set metadata to a work order
Metadata let you store custom data on a per work order basis. Since you can change them later this is a nice way to store your custom work order data without needed a database.
tags
optional
array
List of tags attached to your work order
These tags make it possible to categorise work orders according to your own logic.
parameters
optional
object
Dictionary of entries used in the app logic
If your application logic, on the deepomatic side, requires per work order parameters, this is where you set them. WARNING: unless told so by our teams this shouldn't be specified. If you need to store data that only you will use you should use the metadata parameter.
Response
201: Created
Returns the newly created work order id.
{
  "id": "30c99d1c-2468-4155-8322-2beda677b464",
  "name": "work order 123",
  "site_id": "3a749f74-182e-4154-9cfe-03f352a0ff74",
  "create_date": "2021-03-10T10:05:44.689343+01:00",
  "update_date": "2021-03-10T10:05:44.689374+01:00",
  "review_date": None,
  "tags": [
    "tag1",
    "custom-tag-2",
    "hello"
  ],
  "assigned_user_id": None,
  "parameters": {
    "text-to-validate": "abcdef"
  },
  "metadata": {
    "source": "foo",
    "location": "bar"
  },
  "tasks": [
      {
        "id": "785e7f54-b10b-4fa6-96fc-cbb89e32c369",
        "name": "very-important-checkpoint",
        "label": "The cable is connected.",
        "type": "Boolean",
        "state": None
      }
  ]
}
get
Retrieve a list of work orders
https://api.{$SITE_ID}.customers.deepomatic.com/v0.2/work-orders/
Get all work orders attached to your Deepomatic  API Key.

Request
Response
Request
Headers
Authorization
required
string
Deepomatic API Key
Response
200: OK
The response contains a list of work orders. Note that the output is minimal and that other endpoints will give you more details about the individual work orders.
{
  "count": 1,
  "next": 'https://api-staging.deepomatic.com/v0.7/work-orders/?limit=4&offset=24',
  "previous": 'https://api-staging.deepomatic.com/v0.7/work-orders/?limit=4&offset=16',
  "results": [  
        {
          "id": "30c99d1c-2468-4155-8322-2beda677b464",
          "name": "work order 123",
          "create_date": "2021-03-10T10:05:44.689343+01:00",
          "update_date": "2021-03-10T10:05:44.689374+01:00",
          "review_date": "2021-03-10T10:05:44.689374+01:00",
          "tags": [
            "tag1",
            "custom-tag-2",
            "hello"
          ],
          "parameters": {
            "text-to-validate": "abcdef"
          },
          "metadata": {
            "source": "foo",
            "location": "bar"
          }
        ]
      },
      {
        "id": "21b72ddd-4518-4d44-98af-67dfedf6ae04",
        "name": "work order 456",
        "create_date": "2021-02-25T18:21:06.814571+01:00",
        "update_date": "2021-02-25T18:21:06.814571+01:00",
        "review_date": "2021-02-25T18:21:06.814571+01:00",
        "tags": [
          "tag1",
          "custom-tag-3"
        ],
        "parameters": {
          "measure-to-validate": 36.5
        },
        "metadata": {
          "source": "foo",
          "location": "bar"
        }
      ]
    }
  ]
} 
get
Retrieve a work order
https://api.{$SITE_ID}.customers.deepomatic.com/v0.2/work-orders/{id}/
Get the details about a specific work order. 
Request
Response
Request
Path Parameters
id
required
string
Id of the work order to retrieve
This id corresponds to the id transmitted in the response to the request to create a work order.
Headers
Authorization
required
string
Deepomatic API Key
Query Parameters
include_inputs
optional
boolean
Include analyzed inputs in the response
Default to true. Setting this parameter to false will give you a less verbose output. If it fits your needs you should pass false as it will be faster.
Response
200: OK
The status of a work order corresponds to a set of tasks. For each task, the current analyzed value from one or more analyses is provided (aggregation is an internal Deepomatic process). In case of correction via the correction endpoint (see below), the corrected value is also given. Finally, to explain the result of the analysis, regions attached to an image can be provided to give a maximum of information to the end user.
By setting the include_inputs to false, the response time is reduced. 
include_inputs=true
include_inputs=true
{
  "id": "30c99d1c-2468-4155-8322-2beda677b464",
  "name": "work order 123",
  "site_id": "3a749f74-182e-4154-9cfe-03f352a0ff74",
  "create_date": "2021-03-10T10:05:44.689343+01:00",
  "update_date": "2021-03-10T10:05:44.689374+01:00",
  "review_date": "2021-02-25T18:21:06.814571+01:00",
  "tags": [
    "tag1",
    "custom-tag-2",
    "hello"
  ],
  "assigned_user_id": None,
  "parameters": {
    "text-to-validate": "abcdef"
  },
  "metadata": {
    "source": "foo",
    "location": "bar"
  },
  "tasks": [
      {
        "id": "785e7f54-b10b-4fa6-96fc-cbb89e32c369",
        "name": "very-important-checkpoint",
        "label": "The cable is connected.",
        "type": "Boolean",
        "state": {
          "id": "42d926f8-8c2f-4e35-9611-8a2f058a36ef",
          "analyzed_value": true,
          "analyzed_date": "2021-02-24T18:21:06.814571+01:00",
          "corrected_value": None,
          "corrected_date": "2021-02-24T18:21:06.814571+01:00",
          "message": "Everything is alright.",
          "analyzed_inputs": [{
                "input_id": "e265e644-6a7c-432d-8a6b-7588dd501e01",
                "regions": [
                    {
                      "bbox": {
                        "xmax": 0.5531774759292603,
                        "xmin": 0.26091110706329346,
                        "ymax": 0.6088465452194214,
                        "ymin": 0.26795440912246704
                      },
                      "score": 0.9999864101409912,
                      "concept": "Cable label",
                    }
                }]
          ],
      },
      {
        "id": "a750dc02-ff55-47a3-9e92-df3b123f9d07",
        "name": "another-important-checkpoint",
        "label": "The plugs are installed.",
        "type": "Text",
        "state": {
          "id": "36dbae13-ad7c-463f-ad6a-f24bfba1e1cd",
          "analyzed_value": "1 missing plug",
          "analyzed_date": "2021-02-24T18:21:06.814571+01:00",
          "corrected_value": None,
          "corrected_date": "2021-02-24T18:21:06.814571+01:00",
          "message": "Quality problem detected.",
          "analyzed_inputs": [{
                "input_id": "4de9b9e1-b97c-4044-a1cc-c1ca606c8dfe",
                "regions": [
                    {
                      "bbox": {
                        "xmax": 0.5531774759292603,
                        "xmin": 0.26091110706329346,
                        "ymax": 0.6088465452194214,
                        "ymin": 0.26795440912246704
                      },
                      "score": 0.9999864101409912,
                      "concept": "Missing plug",
                    }
                }]
            ],
        }
    ],
    "inputs": [
     {
          "id": "e265e644-6a7c-432d-8a6b-7588dd501e01",
          "name": "image_input_1",
          "data": {
              "type": "image",
              "value": "https://storage.googleapis.com/dp-resources-prod/inputs/e265e644-6a7c-432d-8a6b-7588dd501e01.jpeg?GoogleAccessId=vulcan-prod%40deepomatic-160015.iam.gserviceaccount.com&Expires=1614275929&Signature=XxrUs3rbJdHgAQ4FgccwjIv9%2B9eYWHj1dtozDjL%2BYrgEdfsEsV3wY4onxboly3Mnx35bp%2BPfkOQ7GO3jNnoL6t%2BtG0QJzY41VuTUQbAMmOp2rw%2FkicXPU2DEi125eZKzmBqpiot2yCteqTK4c6VNC4g2g75%2F2HHTDYfbRuUtHfvXUXKXxhasSL5Uk%2BPbC0o34i4EA1WgiRAGrnugj8I2Ri4%2FJa26NtQcYxDpe895HZs7vTAl35hArxqumc4c7c8%2BH9nbNdeb0ycOg3y7rURQ%3D%3D"
          },
          "metadata": {}
      },
     {
          "id": "4de9b9e1-b97c-4044-a1cc-c1ca606c8dfe",
          "name": "image_input_2",
          "data": {
              "type": "image",
              "value": "https://storage.googleapis.com/dp-resources-prod/inputs/e265e644-6a7c-432d-8a6b-7588dd501e01.jpeg?GoogleAccessId=vulcan-prod%40deepomatic-160015.iam.gserviceaccount.com&Expires=1614275929&Signature=XxrUs3rbJdHgAQ4FgccwjIv9%2B9eYWHj1dtozDjL%2BYrgEdfsEsV3wY4onxboly3Mnx35bp%2BPfkOQ7GO3jNnoL6t%2BtG0QJzY41VuTUQbAMmOp2rw%2FkicXPU2DEi125eZKzmBqpiot2yCteqTK4c6VNC4g2g75%2F2HHTDYfbRuUtHfvXUXKXxhasSL5Uk%2BPbC0o34i4EA1WgiRAGrnugj8I2Ri4%2FJa26NtQcYxDpe895HZs7vTAl35hArxqumc4c7c8%2BH9nbNdeb0ycOg3y7rURQ%3D%3D"
          },
          "metadata": {}
      }
    ]
  ]
}
404: Not Found
Work order not found
{"error": "Not found.", "detail": ""}
get
Retrieve a work order (timeline)
https://api.{$SITE_ID}.customers.deepomatic.com/v0.2/work-orders/{id}/timeline/
Get a chronological list of analyses for a given work order. Newest to oldest.
Request
Response
Request
Path Parameters
id
required
string
Id of the work order to retrieve
This id corresponds to the id transmitted in the response to the request to create a work order.
Headers
Authorization
required
string
Deepomatic API Key
Response
200: OK
The response contains a list of analyses. Each analysis corresponds to a set of inputs sent to the analyze endpoint (see below), and the corresponding result for each impacted task.
{
  "id": "30c99d1c-2468-4155-8322-2beda677b464",
  "site_id": "3a749f74-182e-4154-9cfe-03f352a0ff74",
  "create_date": "2021-03-10T10:05:44.689343+01:00",
  "update_date": "2021-03-10T10:05:44.689374+01:00",
  "review_date": "2021-02-25T18:21:06.814571+01:00",
  "name": "work order 123",
  "analyses": [
      {
        "id": "03b31cbc-ef89-4aec-bf2f-8427ac234168",
        "inputs": [
           {
                "id": "e265e644-6a7c-432d-8a6b-7588dd501e01",
                "name": "image_input",
                "data": {
                    "type": "image",
                    "value": "https://storage.googleapis.com/dp-resources-prod/inputs/e265e644-6a7c-432d-8a6b-7588dd501e01.jpeg?GoogleAccessId=vulcan-prod%40deepomatic-160015.iam.gserviceaccount.com&Expires=1614275929&Signature=XxrUs3rbJdHgAQ4FgccwjIv9%2B9eYWHj1dtozDjL%2BYrgEdfsEsV3wY4onxboly3MnxuR6x%2FT3AwEL0gJnXVFT0wlTtdpcm%2FVzsD6cF0fOonZ55rZ2r9vep8WcgbtwpTmOq9D35bp%2BPfkOQ7GO3jNnoL6t%2BtG0QJzY41VuTUQbAMmOp2rw%2FkicXPU2DEi125eZKzmBqpiot2yCteqTK4c6VNC4g2g75%2F2HHTDYfbRuUtHfvXUXKXxhasSL5Uk%2BPbC0o34i4EA1WgiRAGrnugj8I2Ri4%2FJa26NtQcYxDpe895HZs7vTAl35hArxqumc4c7c8%2BH9nbNdeb0ycOg3y7rURQ%3D%3D"
                },
                "metadata": {}
            }
          ],
        "tasks":[
          {
            "id": "785e7f54-b10b-4fa6-96fc-cbb89e32c369",
            "name": "life-question",
            "label": "what is the answer to life ?",
            "type": "Text",
            "state": {
              "id": "42d926f8-8c2f-4e35-9611-8a2f058a36ef",
              "analyzed_value": "OK",
              "analyzed_date": "2021-02-24T18:21:06.814571+01:00",
              "corrected_value": None,
              "corrected_date": "2021-02-24T18:21:06.814571+01:00",
              "message": "Everything went alright: OK",
              "analyzed_inputs": [{
                    "input_id": "e265e644-6a7c-432d-8a6b-7588dd501e01",
                    "regions": [
                        {
                          "bbox": {
                            "xmax": 0.5531774759292603,
                            "xmin": 0.26091110706329346,
                            "ymax": 0.6088465452194214,
                            "ymin": 0.26795440912246704
                          },
                          "score": 0.9999864101409912,
                          "concept": "Etiquette Cable",
                        }
                    }]
                ]
              }
            ]
        }
    ]
}
delete
Delete a work order
https://api.{$SITE_ID}.customers.deepomatic.com/v0.2/work-orders/{id}/
Request
Response
Request
Path Parameters
id
required
string
Id of the work order to delete
This id corresponds to the id transmitted in the response to the request to create a work order.
Headers
Authorization
required
string
Deepomatic API Key
Response
204: No Content
​
patch
Update a work order
https://{$SITE_ID}.api.customers.deepomatic.com/v0.2/work-orders/{id}/
Update a work order. Parameters have the same meaning as for work order creation.
Request
Response
Request
Path Parameters
id
required
string
Id of the work order to update
This id corresponds to the id transmitted in the response to the request to create a work order.
Headers
Authorization
required
string
Deepomatic API Key
Body Parameters
name
optional
string
Override work order name
metadata
optional
object
Override work order metadata
tags
optional
array
Override work order tags
Response
200: OK
{
  "id": "30c99d1c-2468-4155-8322-2beda677b464",
  "name": "work order 123",
  "site_id": "3a749f74-182e-4154-9cfe-03f352a0ff74",
  "create_date": "2021-03-10T10:05:44.689343+01:00",
  "update_date": "2021-03-10T10:05:44.689374+01:00",
  "tags": [
    "tag1",
    "custom-tag-2",
    "hello"
  ],
  "assigned_user_id": None,
  "parameters": {
    "text-to-validate": "abcdef"
  },
  "metadata": {
    "source": "foo",
    "location": "bar"
  },
  "tasks": [
      {
        "id": "785e7f54-b10b-4fa6-96fc-cbb89e32c369",
        "name": "very-important-checkpoint",
        "label": "The cable is connected.",
        "type": "Boolean",
        "state": None
      }
  ]
}
patch
Update metadata of a work order
https://{$SITE_ID}.api.customers.deepomatic.com/v0.2/work-orders/{id}/metadata/
Update the metadata of a work order. The entire body, as a JSON object, will be added as metadata to the existing work order metadata. Where a metadata field already exists, the specified value will replace the current value.
Request
Response
Request
Path Parameters
id
required
string
Id of the work order to update
This id corresponds to the id transmitted in the response to the request to create a work order.
Headers
Authorization
required
string
Deepomatic API Key
Body Parameters
*
optional
object
Existing or new metadata
Any metadata you want to update or add to the work order.
Response
200: OK
Complete metadata object after the update
{
  "source": "foo",
  "location": "bar"
}
​
put
Update a metadata
https://{$SITE_ID}.api.customers.deepomatic.com/v0.2/work-orders/{id}/metadata/
Update the metadata of the work order. The entire body, as a JSON object, will be added as metadata to the existing work order and replace the existing metadata. Any metadata field not specified in body will then be deleted.
Request
Response
Request
Path Parameters
id
required
string
​
Headers
Authorization
required
string
Deepomatic API Key
Body Parameters
*
optional
string
New metadata object you want to put 
Response
200: OK
​
post
Analyze inputs
https://api.{$SITE_ID}.customers.deepomatic.com/v0.2/work-orders/{id}/analyze/
Send one or several inputs and get the result of the analysis in the response.
Request
Response
Request
Path Parameters
id
required
string
Id of the work order to send the input to
This id corresponds to the id transmitted in the response to the request to create a work order.
Headers
Authorization
required
string
Deepomatic API Key
Body Parameters
inputs
required
array
List of inputs
See below for more information on the format of the inputs to be transmitted. 
The inputs depend on the logic of the Deepomatic application. Contact our team for more information on the inputs for your specific application.
Response
200: OK
The format of the response is similar to the response when retrieving a work order. But the task list is filtered to contain only those that are impacted by the analysis. 
{
  "id": "03b31cbc-ef89-4aec-bf2f-8427ac234168",
  "tasks": [
      {
        "id": "785e7f54-b10b-4fa6-96fc-cbb89e32c369",
        "name": "life-question",
        "label": "what is the answer to life ?",
        "type": "Text",
        "state": {
          "id": "42d926f8-8c2f-4e35-9611-8a2f058a36ef",
          "analyzed_value": "OK",
          "analyzed_date": "2021-02-24T18:21:06.814571+01:00",
          "message": "Everything went alright: OK",
          "analyzed_inputs": [{
                "input_id": "e265e644-6a7c-432d-8a6b-7588dd501e01",
                "regions": [
                    {
                      "bbox": {
                        "xmax": 0.5531774759292603,
                        "xmin": 0.26091110706329346,
                        "ymax": 0.6088465452194214,
                        "ymin": 0.26795440912246704
                      },
                      "score": 0.9999864101409912,
                      "concept": "Etiquette Cable",
                    }
                }]
            ],
        }
    ],
    "inputs": [
     {
          "id": "e265e644-6a7c-432d-8a6b-7588dd501e01",
          "name": "image_input"
      }
    ]
  ]
}
post
Analyze inputs with callback
https://api.{$SITE_ID}.customers.deepomatic.com/v0.2/work-orders/{id}/analyze/callback/
Send one or several inputs and get the result of the analysis pushed to a specific URL.
Request
Response
Request
Path Parameters
id
required
string
Id of the work order to send the input to
This id corresponds to the id transmitted in the response to the request ti create a work order.
Headers
Authorization
required
string
Deepomatic API Key
Body Parameters
url
required
string
Callback URL
Once the analysis result has been processed, a POST is made to the specified URL to send the result in the format specified in the /analyze/. A response code 200 is expected in return. If the workflow execution error occurs, an error message will be sent to the URL.
inputs
required
array
List of inputs
See below for more information on the format of the inputs to be transmitted. 
The inputs depend on the logic of the Deepomatic application. Contact our team for more information on the inputs for your specific application.
Response
200: OK
​
"inputs": [
            {
                'name': 'windshield_image',
                'data':
                {
                    'type': 'image',
                    'value': 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRw...'
                },
                'metadata': {}
            },
            {
                'name': 'dog_image',
                'data':
                {
                    'type': 'image',
                    'value': 'https://link/to/my/image/dog.jpg'
                }
            },
            {
                'name': 'anything',
                'data':
                {
                    'type': 'text',
                    'value': 'something'
                }
            },
            {
                'name': 'pi',
                'data':
                {
                    'type': 'number',
                    'value': 3.14
                }
            }
    ]
patch
Correct a task
https://api.{$SITE_ID}.customers.deepomatic.com/v0.2/work-orders/{id}/tasks/{task_id}/correction/
Correct the value of a specific task.
Request
Response
Request
Path Parameters
id
required
string
Id of the work order owning the task to correct
This id corresponds to the id transmitted in the response to the request ti create a work order.
task_id
required
string
Task_id to correct
Headers
Authorization
required
string
Deepomatic API Key
Body Parameters
corrected_value
required
string
Corrected value
It must be compatible with the task type (Boolean, Text, Number). 
Response
200: OK
{
   "id":"f54b713c-8dad-401c-ad9d-2961e0205ec6",
   "name":"life-question",
   "label":"what is the answer to life ?",
   "type":"Text",
   "state":{
      "id":"2a78da05-6786-4d81-82b5-b31d3921e834",
      "analyzed_value":"None",
      "analyzed_date":"None",
      "corrected_value":"OK",
      "corrected_date":"2021-03-17T10:48:13.876288Z",
      "message":"Everything went alright: OK"
   }
}
Deepomatic Engage - Previous
Integrating Visual Automation Applications
Mobile application - Best practices
Last updated 4 days ago
Integrating the Augmented Technician API

Prerequisites

postCreate a work order

getRetrieve a list of work orders

getRetrieve a work order

getRetrieve a work order (timeline)

deleteDelete a work order

patchUpdate a work order

patchUpdate metadata of a work order

putUpdate a metadata

postAnalyze inputs

postAnalyze inputs with callback

patchCorrect a task

post
Create a work order

get
Retrieve a list of work orders

get
Retrieve a work order

get
Retrieve a work order (timeline)

delete
Delete a work order

patch
Update a work order

patch
Update metadata of a work order

put
Update a metadata

post
Analyze inputs

post
Analyze inputs with callback

patch
Correct a task
