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:mm: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 HH:mm:ss). 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).
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 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)
  • 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>

Back to Top

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:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
</xml>

Back to Top