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

  • you must have added the customer-api service to your application

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
Authorization
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
}
]
}
400: Bad Request
A required field is not specified.
{'name': ["Field 'name' is missing. This field is required."]}
{'metadata': ["Field 'metadata' is missing. This field is required."]}
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}

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"
}
}
]
}
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}

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": {}
}
]
]
}
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}
404: Not Found
Work order not found
{'detail': 'WorkOrder not found!'}

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",
}
}]
]
}
]
}
]
}
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}
404: Not Found
Work order not found
{'detail': 'WorkOrder not found!'}

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
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}
404: Not Found
Work order not found.
{'detail': 'WorkOrder not found!'}

patch
Update a work order

https://api.{$SITE_ID}.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
}
]
}
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}
404: Not Found
Work order not found.
{'detail': 'WorkOrder not found!'}

patch
Update metadata of a work order

https://api.{$SITE_ID}.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"
}
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}
404: Not Found
Work order not found
{'detail': 'WorkOrder not found!'}

put
Update a metadata

https://api.{$SITE_ID}.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
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}
404: Not Found
Work order not found
{'detail': 'WorkOrder not found!'}

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"
}
]
]
}
400: Bad Request
A required field is not specified or wrong.
{'inputs': [{'data': ["Field 'type' is missing. This field is required."]}, {}, {}, {}]}
OR
{'inputs': [{}, {'data': ['Failed to download image https://storage.googleapis.com/dp-vulcan/tests/imgs/dog.jpgWRONG']}, {}, {}]}
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}
404: Not Found
Work order not found
{'detail': 'WorkOrder not found!'}
500: Internal Server Error
WorkflowServerExecutionError

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
400: Bad Request
A required field is not specified.
{'inputs': [{'data': ["Field 'type' is missing. This field is required."]}, {}, {}, {}]}
OR
{'inputs': [{}, {'data': ['Failed to download image https://storage.googleapis.com/dp-vulcan/tests/imgs/dog.jpgWRONG']}, {}, {}]}
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}
404: Not Found
Work order not found
{'detail': 'WorkOrder not found!'}
500: Internal Server Error
WorkflowServerExecutionError
"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"
}
}
403: Forbidden
{'detail': 'Authentication credentials not provided.'}
OR
{'detail': 'No user found for such apiKey.'}
404: Not Found
Work order not found
{'detail': 'WorkOrder not found!'}