{"_id":"59778bb932f043002002f5e0","category":{"_id":"59778bb932f043002002f5d5","version":"59778bb932f043002002f5d3","project":"5425e663ffd4411c319a65b4","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-09-29T20:18:57.785Z","from_sync":false,"order":1,"slug":"reference","title":"Reference"},"project":"5425e663ffd4411c319a65b4","user":"5425e31affd4411c319a65b1","version":{"_id":"59778bb932f043002002f5d3","project":"5425e663ffd4411c319a65b4","__v":1,"createdAt":"2017-07-25T18:19:37.272Z","releaseDate":"2017-07-25T18:19:37.272Z","categories":["59778bb932f043002002f5d4","59778bb932f043002002f5d5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.5.0","version":"2.5"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-06-26T20:13:43.313Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":18,"body":"Providing barcode scanning functionality to your drivers through our mobile applications requires that you be familiar with two key actions: requesting barcodes and capturing barcodes.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Barcode scanning is a premium feature which can be enabled by the organization administrator from the dashboard settings. In addition to this documentation, you may find [this support center article](https://support.onfleet.com/hc/en-us/articles/115003148286F) helpful.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Requesting\"\n}\n[/block]\nTo request a barcode means to create a task with barcode data that will inform the driver that one or more barcodes should be scanned prior to completing a task. You can optionally block task completion on a per barcode basis, effectively turning your barcode request into a barcode requirement. \n\nIn order to request barcodes for a task, you can create a new task or update an existing task while providing the `barcodes` object array, top-level task property. \n\nThe structure of the object members of this array property is as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"data\\\": \\\"aGVsbG8gd29ybGQh\\\", // string, the base64 representation of the data encoded within the barcode to be captured, max length of 500 characters\\n\\n\\t\\\"blockCompletion\\\": true // boolean, whether the worker must capture this data prior to task completion, defaults to false\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nRequesting a barcode will ensure that your driver can see the barcodes requested when they are about to complete a task. The driver will be prevented from completing the task unless all requested barcodes with `blockCompletion` set to `true` have been captured.\n\nIf you would like to request that any barcode be scanned, regardless of `data`, you may simply omit the `data` property in your request.\n[block:api-header]\n{\n  \"title\": \"Creating a new task with requested barcodes\"\n}\n[/block]\nThe following request creates a new task with one mandatory and one optional barcode.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X POST \\\"https://onfleet.com/api/v2/tasks\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -d '{\\\"destination\\\":{...},\\\"recipients\\\":[...],...,\\\"barcodes\\\":[{\\\"data\\\":\\\"aG VsbG8gd29ybGQh\\\",\\\"blockCompletion\\\":true},{\\\"data\\\":\\\"aG93IGFyZSB5b3U/\\\"}]}'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" {\\n  \\\"id\\\": \\\"0VuO6yDq5YrGeZ7NVwUqK8hu\\\",\\n  //...,\\n  \\\"barcodes\\\": {\\n    \\\"required\\\": [ \\n      { \\\"data\\\": \\\"aGVsbG8gd29ybGQh\\\", \\\"blockCompletion\\\": true },\\n      { \\\"data\\\": \\\"aG93IGFyZSB5b3U/\\\", \\\"blockCompletion\\\": false }\\n    ],\\n    \\\"captured\\\": [ ]\\n  },\\n  //... \\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nNote that these barcode requests are now found under the `barcodes.required` property.\n[block:api-header]\n{\n  \"title\": \"Updating an existing task with requested barcodes\"\n}\n[/block]\nThe following request will update an existing task containing no barcode requirements such that it requires one non-blocking barcode to be scanned by the driver. Note that updating a task’s `barcodes` property will entirely overwrite any previously existing values.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X PUT \\\"https://onfleet.com/api/v2/tasks/0VuO6yDq5YrGeZ7NVwUqK8hu\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -d '{\\\"barcodes\\\":[{\\\"data\\\":\\\"bXkgc25lYWt5IHVwZGF0ZQ==\\\"}]}'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" {\\n  \\\"id\\\": \\\"0VuO6yDq5YrGeZ7NVwUqK8hu\\\",\\n  //...,\\n  \\\"barcodes\\\": {\\n    \\\"required\\\": [ \\n      { \\\"data\\\": \\\"bXkgc25lYWt5IHVwZGF0ZQ==\\\", \\\"blockCompletion\\\": false }\\n    ],\\n    \\\"captured\\\": [ ]\\n  },\\n  //... \\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Capturing\"\n}\n[/block]\nBarcodes can be only be captured via the Onfleet iOS or Android driver app. \n\nNote that capturing barcodes can be done for any task, regardless of barcode request status, provided the organization has the feature enabled. You only need to use the requesting functionality if you wish to inform the driver about barcodes to be scanned or enforce their collection.\n\nOnce a task is completed for which barcodes have been captured, you may access the details of these barcodes by fetching the task via API, using any of the relevant methods from the [Tasks](doc:tasks) section of the docs.\n\nEach object member of the `barcodes.captured` array property returned for completed tasks will have the following properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"1-0\": \"symbology\",\n    \"1-1\": \"string\",\n    \"1-2\": \"The symbology that was captured. You can read more about these [here](https://en.wikipedia.org/wiki/Barcode#Symbologies).\",\n    \"2-0\": \"data\",\n    \"2-1\": \"string\",\n    \"2-2\": \"The base64 string of the data contained in the captured barcode.\",\n    \"3-0\": \"location\",\n    \"3-1\": \"number array\",\n    \"3-2\": \"The `[ lon, lat ]` coordinates where the barcode capture took place.\",\n    \"4-0\": \"time\",\n    \"4-1\": \"number\",\n    \"4-2\": \"The time at which the barcode capture happened.\",\n    \"5-0\": \"wasRequested\",\n    \"5-1\": \"boolean\",\n    \"5-2\": \"Whether the barcode was captured as a result of a barcode request.\",\n    \"0-0\": \"id\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The ID of the captured barcode.\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\nHere is an example of the `barcodes` property for a completed task with no required barcodes:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"9I4cmNGtVTm5VRcq7B*lymEA\\\",\\n  //...\\n  \\\"barcodes\\\": {\\n    \\\"required\\\": [],\\n    \\\"captured\\\": [\\n      {\\n        \\\"symbology\\\": \\\"CODE39\\\",\\n        \\\"data\\\": \\\"QkMzMjE=\\\",\\n        \\\"wasRequested\\\": false,\\n        \\\"time\\\": 1498500964205,\\n        \\\"location\\\": [\\n          -122.42855072021484,\\n          37.78808138412046\\n        ],\\n        \\\"id\\\": \\\"ku0fpiCqJPC25h3W0cnfgqNn\\\"\\n      },\\n      {\\n        \\\"symbology\\\": \\\"UPCA\\\",\\n        \\\"data\\\": \\\"MDEyMzQ1Njc4OTA1\\\",\\n        \\\"wasRequested\\\": false,\\n        \\\"time\\\": 1498500964205,\\n        \\\"location\\\": [\\n          -122.49481201171875,\\n          37.75307256315459\\n        ],\\n        \\\"id\\\": \\\"leElaPdbWobzlwDoP5MuHA~h\\\"\\n      }\\n    ]\\n  },\\n  //...\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"barcode-scanning","type":"basic","title":"Barcode Scanning"}
Providing barcode scanning functionality to your drivers through our mobile applications requires that you be familiar with two key actions: requesting barcodes and capturing barcodes. [block:callout] { "type": "info", "body": "Barcode scanning is a premium feature which can be enabled by the organization administrator from the dashboard settings. In addition to this documentation, you may find [this support center article](https://support.onfleet.com/hc/en-us/articles/115003148286F) helpful." } [/block] [block:api-header] { "title": "Requesting" } [/block] To request a barcode means to create a task with barcode data that will inform the driver that one or more barcodes should be scanned prior to completing a task. You can optionally block task completion on a per barcode basis, effectively turning your barcode request into a barcode requirement. In order to request barcodes for a task, you can create a new task or update an existing task while providing the `barcodes` object array, top-level task property. The structure of the object members of this array property is as follows: [block:code] { "codes": [ { "code": "{\n\t\"data\": \"aGVsbG8gd29ybGQh\", // string, the base64 representation of the data encoded within the barcode to be captured, max length of 500 characters\n\n\t\"blockCompletion\": true // boolean, whether the worker must capture this data prior to task completion, defaults to false\n}", "language": "javascript" } ] } [/block] Requesting a barcode will ensure that your driver can see the barcodes requested when they are about to complete a task. The driver will be prevented from completing the task unless all requested barcodes with `blockCompletion` set to `true` have been captured. If you would like to request that any barcode be scanned, regardless of `data`, you may simply omit the `data` property in your request. [block:api-header] { "title": "Creating a new task with requested barcodes" } [/block] The following request creates a new task with one mandatory and one optional barcode. [block:code] { "codes": [ { "code": "$ curl -X POST \"https://onfleet.com/api/v2/tasks\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -d '{\"destination\":{...},\"recipients\":[...],...,\"barcodes\":[{\"data\":\"aG VsbG8gd29ybGQh\",\"blockCompletion\":true},{\"data\":\"aG93IGFyZSB5b3U/\"}]}'", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": " {\n \"id\": \"0VuO6yDq5YrGeZ7NVwUqK8hu\",\n //...,\n \"barcodes\": {\n \"required\": [ \n { \"data\": \"aGVsbG8gd29ybGQh\", \"blockCompletion\": true },\n { \"data\": \"aG93IGFyZSB5b3U/\", \"blockCompletion\": false }\n ],\n \"captured\": [ ]\n },\n //... \n}", "language": "json" } ] } [/block] Note that these barcode requests are now found under the `barcodes.required` property. [block:api-header] { "title": "Updating an existing task with requested barcodes" } [/block] The following request will update an existing task containing no barcode requirements such that it requires one non-blocking barcode to be scanned by the driver. Note that updating a task’s `barcodes` property will entirely overwrite any previously existing values. [block:code] { "codes": [ { "code": "$ curl -X PUT \"https://onfleet.com/api/v2/tasks/0VuO6yDq5YrGeZ7NVwUqK8hu\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -d '{\"barcodes\":[{\"data\":\"bXkgc25lYWt5IHVwZGF0ZQ==\"}]}'", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": " {\n \"id\": \"0VuO6yDq5YrGeZ7NVwUqK8hu\",\n //...,\n \"barcodes\": {\n \"required\": [ \n { \"data\": \"bXkgc25lYWt5IHVwZGF0ZQ==\", \"blockCompletion\": false }\n ],\n \"captured\": [ ]\n },\n //... \n}", "language": "json" } ] } [/block] [block:api-header] { "title": "Capturing" } [/block] Barcodes can be only be captured via the Onfleet iOS or Android driver app. Note that capturing barcodes can be done for any task, regardless of barcode request status, provided the organization has the feature enabled. You only need to use the requesting functionality if you wish to inform the driver about barcodes to be scanned or enforce their collection. Once a task is completed for which barcodes have been captured, you may access the details of these barcodes by fetching the task via API, using any of the relevant methods from the [Tasks](doc:tasks) section of the docs. Each object member of the `barcodes.captured` array property returned for completed tasks will have the following properties: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "1-0": "symbology", "1-1": "string", "1-2": "The symbology that was captured. You can read more about these [here](https://en.wikipedia.org/wiki/Barcode#Symbologies).", "2-0": "data", "2-1": "string", "2-2": "The base64 string of the data contained in the captured barcode.", "3-0": "location", "3-1": "number array", "3-2": "The `[ lon, lat ]` coordinates where the barcode capture took place.", "4-0": "time", "4-1": "number", "4-2": "The time at which the barcode capture happened.", "5-0": "wasRequested", "5-1": "boolean", "5-2": "Whether the barcode was captured as a result of a barcode request.", "0-0": "id", "0-1": "string", "0-2": "The ID of the captured barcode." }, "cols": 3, "rows": 6 } [/block] Here is an example of the `barcodes` property for a completed task with no required barcodes: [block:code] { "codes": [ { "code": "{\n \"id\": \"9I4cmNGtVTm5VRcq7B*lymEA\",\n //...\n \"barcodes\": {\n \"required\": [],\n \"captured\": [\n {\n \"symbology\": \"CODE39\",\n \"data\": \"QkMzMjE=\",\n \"wasRequested\": false,\n \"time\": 1498500964205,\n \"location\": [\n -122.42855072021484,\n 37.78808138412046\n ],\n \"id\": \"ku0fpiCqJPC25h3W0cnfgqNn\"\n },\n {\n \"symbology\": \"UPCA\",\n \"data\": \"MDEyMzQ1Njc4OTA1\",\n \"wasRequested\": false,\n \"time\": 1498500964205,\n \"location\": [\n -122.49481201171875,\n 37.75307256315459\n ],\n \"id\": \"leElaPdbWobzlwDoP5MuHA~h\"\n }\n ]\n },\n //...\n}", "language": "json" } ] } [/block]