API: Scans¶
Make sure to read the API Overview before reading this document.
Retrieving a List of Scans / Searching Scans¶
Required Variables¶
| Variables | Description |
|---|---|
| section | Must be set to scans. |
| action | Must be set to retrieve. |
| api_key | Must be set to your unique API key. |
Optional Variables¶
| Variables | Description |
|---|---|
| keyword | A string which specifies a keyword with which to run a search query. Blank by default. |
| service_id | An integer or series of integers which specifies the particular services you'd like to search for scans within. You can specify a single integer or a comma-separated list of integers (Examples: 1005 or 1005, 1010, 1254). You can also use the keyword all to include all services. This parameter is set to all by default. |
| device_id | An integer or series of integers which will return only scans conducted by the specified devices. You can specify a single integer or a comma-separated list of integers (Examples: 1005 or 1005, 1010, 1254). You can also use the keyword all to include all devices in your search. This parameter is set to all by default. |
| user_id | An integer or series of integers which will return only scans conducted by the specified users. You can specify a single integer or a comma-separated list of integers (Examples: 1005 or 1005, 1010, 1254). You can also use the keyword all to include all users in your search. This parameter is set to all by default. |
| scan_id | You can specify a single integer or a comma-separated list of integers (Examples: 1005 or 1005, 1010, 1254) to only retrieve scans with the specified IDs. By default all scans are included in your search. |
| status | An enum type which specifies the scan result type you would like to search within. Input 1 to only display valid scans, 0 to only display invalid scans and -1 to display scans which could not be validated due to lost Internet connectivity. You can also use a comma-separated list to specify multiple scan result types (Examples: 1, 0) or the keyword all to include all scan result types in your search. This parameter is set to all by default. |
| start_date | A date (formatted as YYYY-MM-DD). Use this to search for scans conducted after a given date. Blank by default. |
| start_time | A timestamp (24-hour, formatted as HH ss). Use this to search for scans conducted after a given time. Only valid if start_date is provided. |
| end_date | A date (formatted as YYYY-MM-DD). Use this to search for scans conducted before a given date. Blank by default. |
| end_time | A timestamp (24-hour, formatted as HHss). Use this to search for scans conducted before a given time. Only valid if end_date is provided. |
| upload_id | An integer or comma-separated series of integers which can be used to retrieve scans from a specific upload. |
| limit | An integer which limits the maximum number of results displayed within the list. Default value is 10000. |
| offset | An integer which offsets the results shown. Only valid if limit is provided. (Example: a limit of 20 and an offset of 5 will display a list of 20 scans that begins with the 5th scan). |
| showProperties | A boolean which toggles showing scan properties in the returned XML. Set it to 1 to show properties. Default value is 0 (hide properties). |
| includeProperty | A string which takes a comma-separated list of property names. Only scans that contain these properties will be included in the result set of scans. |
| excludeProperty | A string which takes a comma-separated list of property names. Scans that contain any of these properties will be excluded from the result set of scans. |
| with_property | An array to perform an exact match search for a property value that is present in the scan. Array key stands for the property name, while array value stands for the property value. Example: with_property[mode]=auto&with_property[color]=blue |
| without_property | An array to perform an exact match search for a property value that is not present in the scan. Array key stands for the property name, while array value stands for the property value. Example: without_property[mode]=auto&without_property[color]=blue |
| value | A string to perform an exact match search against the scan value (tid). (Example: value=abc). |
| valuelike | A string to perform a partial match search against the scan value (tid). (Example: value=abc will match abc1, 123abc, 123abc123, etc). |
| response | A string to perform an exact match search against the scan response (result). (Example: response=abc). |
| responselike | A string to perform a partial match search against the scan response (result). (Example: responselike=abc will match values with responses abc1, 123abc, 123abc123, etc). |
| timestamp_received | An integer which toggles the display of timestamp_received XML node. If this variable is set to 1 or 2 the timestamp_received node is added to the XML and will contain the timestamp when the scan was actually received by codeREADr (e.g. scan upload timestamp for on-device made scans). Additionally, if timestamp_received=1, then variables start_date, start_time, end_date, end_time will use timestamp_received column to perform filtering, instead of regular timestamp (which is the timestamp when the scan was made on device). You can also use timestamp_received=1 and timestamp_modified=1 together. If both are set then start_date/time and end_date/time are applied to both received and modified timestamps using the OR condition. |
| timestamp_modified | An integer which toggles the display of timestamp_modified XML node. If this variable is set to 1 or 2 the timestamp_modified node is added to the XML and will contain the timestamp when the scan was most recently modified. Additionally, if timestamp_modified=1, then variables start_date, start_time, end_date, end_time will use the timestamp_modified value to perform filtering, instead of regular timestamp (which is the timestamp when the scan record was created). You can also use timestamp_received=1 and timestamp_modified=1 together. If both are set then start_date/time and end_date/time are applied to both received and modified timestamps using the OR condition. |
| modified_diff | Filter by the difference between the regular timestamp (when the scan was made) and the modified_timestamp (when the scan was most recently modified). Parameter value should be in the format of operator number metric. Operator can be either > or <, number - any numeric value, and metric one of second, minute, hour, day, month or year. Example: < 2 minute or > 1 hour |
| timezone | A string which specifies a timezone for the scan timestamps. (Examples: timezone=America/New_York, or timezone=Asia/Hong_Kong works for Beijing, timezone=Europe/London works for London etc.) The parameter is set to codeREADr's local time by default (America/New_York, Eastern Time US & Canada). You can dynamically use the timezone configured by the account holder by setting the parameter to the keyword account. See the list of Available Timezones. |
| timezone_offset | Deprecated - please use timezone variable instead. A string which specifies a GMT timezone offset for the scan timestamps. You can dynamically use the timezone configured by the account holder by setting the parameter to the keyword account. (Examples: timezone_offset=account, or timezone_offset=+08:00 works for Beijing, timezone_offset=00:00 works for London, timezone_offset=-03:00 works for Brazil, etc.) The parameter is set to codeREADr's local time by default (-05:00 GMT, Eastern Time US & Canada). See a list of timezone offsets here. |
| order_by | An enum type which specifies the order in which you would like your scan list to be sorted. You must set it from the order_by key set below. For ascending order use the key without the _desc suffix (e.g. device_id) and for descending use the key with the _desc suffix (e.g. device_id_desc). You can also use a comma-separated list of keys to specify multiple sub-levels of ordering (e.g. device_id,service_id_desc,timestamp). |
| only_recent | A boolean value which specifies if response should contain only recent scan for each barcode. If set to 1 response will include only the recent scan for each barcode. Set to 0 to view all scans of each barcode. This value is set to 0 by default. |
order_by key set: * barcode or barcode_desc (alphabetical by barcode value) * device_name or device_name_desc (alphabetical by device name) * device_id or device_id_desc (numerical by device ID) * response or response_desc (alphabetical by barcode response) * scan_id or scan_id_desc (numerical by scan ID) * service_id or service_id_desc (numerical by service ID) * service_name or service_name_desc (alphabetical by service name) * status or status_desc (numerical by validation status) * timestamp or timestamp_desc (chronological order) * timestamp_received or timestamp_received_desc (chronological order) * timestamp_modified or timestamp_modified_desc (chronological order) * user_id or user_id_desc (numerical by user ID) * user_name or user_name_desc (alphabetical by username)
Response¶
After we receive these variables, we will respond with raw XML containing status and scan data.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<xml>
<status>1</status>
<count>3</count>
<scan id="13193">
<device id="573">iPhone 3</device>
<service id="927">Lead Retrieval</service>
<user id="3">demo</user>
<status>1</status>
<tid>A1B2C3D</tid>
<result>Item # 123450. New location on Floor 2, station 4.</result>
<timestamp>2010-08-06 16:42:35</timestamp>
<answer qid="386" qtext="Primary Interest:">Product A</answer>
<answer qid="387" qtext="Action Items:">Call</answer>
<answer qid="390" qtext="Special Notes:">grub</answer>
<properties>
<mode>auto</mode>
</properties>
</scan>
<scan id="13194">
<device id="579">My android device</device>
<service id="926">Inventory</service>
<user id="3">demo</user>
<status>1</status>
<tid>A1B2C3D</tid>
<result>Information has been saved.</result>
<timestamp>2010-08-06 16:46:09</timestamp>
<answer qid="389" qtext="Enter Quantity:">24</answer>
<properties>
<mode>auto</mode>
<color>blue</color>
</properties>
</scan>
<scan id="13195">
<device id="571">new phone</device>
<service id="926">Inventory</service>
<user id="3">demo</user>
<status>1</status>
<tid>A1B2C3D</tid>
<result>Information has been saved.</result>
<timestamp>2010-08-06 16:46:24</timestamp>
<answer qid="389" qtext="Enter Quantity:">99</answer>
</scan>
</xml>
Deleting Scans¶
Required Variables¶
| Variables | Description |
|---|---|
| section | Must be set to scans. |
| action | Must be set to delete. |
| api_key | Must be set to your unique API key. |
| scan_id | One or more integers specifying the scan(s) you would like to delete. When deleting multiple scans, please separate each integer with commas. |
Response¶
After we receive these variables, we will respond with raw XML containing a status of 1.
Example: