API: Services¶

Make sure to read the API Overview before reading this document.

Retrieving a Service List¶

Required Variables¶

Optional Variables¶

Response¶

After we receive these variables, we will respond with raw XML containing status and service information.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
    <service id="120">
        <name>Friday event</name>
        <validationmethod>postback</validationmethod>
        <postback>https://www.postbackurl.com</postback>
        <user id="123"/>
        <user id="124"/>
        <question id="480"/>
    </service>
    <service id="380">
        <name>Boston Marathon</name>
        <validationmethod>database</validationmethod>
        <database>757</database>
        <duplicateScanValue>1</duplicateScanValue>
        <user id="124"/>
        <user id="125"/>
        <question id="482"/>
        <question id="484"/>
    </service>
</xml>

Creating a Service¶

Required Variables¶

If validation_method is set to database or ondevicedatabase:

If validation_method is set to postback:

If validation_method is set to webview:

Optional Variables¶

Variable	Description
service_name	A string which specifies the desired name of your new service. The default is Service $i, where $i is the next available sequential number.
description	A string which specifies the desired description of your new service. Blank by default.
duplicate_value	An integer value that specifies the status of a duplicate scan if validation_method is set to database or ondevicedatabase. Set to 1 for valid scan status and 0 for invalid scan status. The default status of duplicates are valid (e.g. value set to 1).
device_duplicate_value	An integer value that specifies the status of a duplicate scan when scanning on-device. It’s only for checking against scans currently stored on the device. Set to 1 to make the status of duplicate scans currently on the device valid and set to 0 to make them invalid. The default status of duplicates on-device are valid (e.g. value set to 1). This only applies when the validation_method is set to record, ondevicerecord, database or ondevicedatabase. NOTE: if the duplicate_value option is set to 0 (invalid) then this option is overridden.
period_start_date	A string which specifies the date when the new service should become active. Can be formatted as MM/DD/YYYY or YYYY-MM-DD (Examples: 12/20/2012 or 2012-12-20). If this parameter is not specified, the service is always active.
period_start_time	A string which specifies the time when the new service should become active. Can be formatted as hhss or hh:mma (Examples: 18:30:00 or 6:30pm). If this parameter is not specified, the service is activated at 12:00AM on the specified period_start_date.
period_end_date	A string which specifies the date when the new service should become inactive. Can be formatted as MM/DD/YYYY or YYYY-MM-DD (Examples: 12/20/2012 or 2012-12-20). If this parameter is not specified, the service is always active.
period_end_time	A string which specifies the time when the new service should become inactive. Can be formatted as hhss or hh:mma (Examples: 18:30:00 or 6:30pm). If this parameter is not specified, the service remains active until 11:59:59PM on the specified period_end_date.
upload_email	A string which specifies the email address the accountholder would like a CSV file of scan data automatically sent to after each upload. If this parameter is not specified, scan data is not emailed.
upload_email_format	A string which specifies the format of the CSV file to be emailed to the email address specified under upload_email. Possible values are regular (do not include scan properties information) and properties (includes scan properties). Default value is regular.
viewOtherScans	A boolean value which specifies which scans an authorized user can view on their device. If set to 0, the user can only view their own scans. If set to 1, the user can view the scans of every user authorized for the service. This value is set to 1 by default.
direct_history_url	Set to the URL you want to loaded in web view when the user clicks the History option in the app. Set to empty to disable.
direct_lookup_url	Set to the URL you want to loaded in web view when the user clicks the Lookup option in the app. Set to empty to disable.
enable_direct_scan	An integer which only needs to be specified if the validation_method is set to postback. It specifies that the scans will not be routed through the codeREADr servers but instead go directly to your Postback URL server. Input 1 to enable and 0 to disable. Default value is 0.
postback_receiver_only	Set to 1 if your postback_url can only receive. Set to 0 if it can receive and respond with the expected XML. The default value is 0.
postback_real_time_scans	Set to 1 enable or 0 to disable the postback of each online scan made directly to the server. This variable must be submitted together with the postback_url variable to add postback functionality to non-postback service types such as record, database, etc. It does not work with services of type postback.
postback_uploaded_scans	Set to 1 enable or 0 to disable the postback each on-device scan uploaded to the server. This variable must be submitted together with the postback_url variable to add postback functionality to non-postback service types such as record, database, etc. It does not work with services of type postback.
regex_response_pattern	The first half of a regular expression match and replace pair. Set to a regular expression pattern you want to match in the scan response and replace with regex_response_replacement. Set to empty to disable. This variable must be submitted together with regex_response_replacement.
regex_response_replacement	The second half of a regular expression match and replace pair. Set to the value that will replace the corresponding regex_response_pattern match. Set to empty to disable. This variable must be submitted together with regex_response_pattern.
regex_scan_pattern	The first half of a regular expression match and replace pair. Set to a regular expression pattern you want to match in the scan value and replace with regex_scan_replacement. Set to empty to disable. This variable must be submitted together with regex_scan_replacement.
regex_scan_replacement	The second half of a regular expression match and replace pair. Set to the value that will replace the corresponding regex_scan_pattern match. Set to empty to disable. This variable must be submitted together with regex_scan_pattern.
symbologies	An integer or set of integers specifying the barcode symbolgy IDs. You can specify a single integer or a comma-separated list of integers (Examples: 33 or 33, 34, 12). By selecting only those symbologies which your app users will scan, the scan process will be quicker and more accurate. See the table of symbology ID numbers. Note: All symbologies are not available to all accounts. Updating the service without submitting the 'symbologies' parameter will reset to default.
auto_next_scan	An integer value to enable or disable the Auto-Next Scan feature. This option is not enabled by default. Set to 0 to disable this feature. Set to 1 for Only when valid mode. Set to 2 for Always and save if Error mode. Set to 3 for Always and discard if Error mode.
auto_next_scan_delay	An integer value specifying the delay in seconds before the Auto-Next Scan feature will trigger after the scan response is displayed. Default delay is approximately 1 second. Only for services with auto_next_scan enabled.
enableGPS	A boolean value which makes the service submit GPS location with every scan as a scan property. If set to 1, location will be submitted. If set to 0, it will not be submitted. This value is set to 0 by default. Background GPS.
block_camera_scan	A boolean value which specifies if users are allowed to scan barcode using the device's camera. If set to 0, users are allowed to scan using device camera. If set to 1, users will not be able to scan via the device's camera. This value is set to 0 by default.
block_manual_scan	A boolean value which specifies if users are allowed to enter scan values manually. If set to 0, users are allowed to enter scan data manually. If set to 1, users are not allowed to enter scan data manually. This value is set to 0 by default.
block_db_search	A boolean value which specifies if users are allowed to lookup values in database. If set to 0, users are allowed to lookup. If set to 1, users are not allowed lookup in database. This value is set to 0 by default.
auto_sync	Set to 1 to enable Auto Sync. By default we will sync scans saved on-device to codeREADr servers and sync down database updates if the service is an ondevicedatabase type service. Note: currently only on-device databases containing up to 50,000 values are supported. Contact us if your database exceeds that limit and learn your options.
auto_sync_up_url	Set it to your own Postback URL to skip us and auto sync scans directly to your server. Only for services with auto_sync enabled.
auto_sync_up_delay	An integer value specifying the delay in seconds between attempts to upload scans to the server. Default delay is 2 seconds. Only for services with auto_sync enabled.
auto_sync_down_url	Set to 0 to disable automatic downloading of database updates. Users will have to manual download database updates. If you need to re-enable set to 1. Only for on-device database services with auto_sync enabled. Note: specifying your own cutom URL is not publicly supported at this time.
auto_sync_down_delay	An integer value specifying the delay in seconds between checks to sync down new database updates from the server. Default delay is 120 seconds. Only for services with auto_sync enabled.
decoder_config	A JSON string defining the barcode scanner configuration for the service. Configurations have many options, so rather than authoring the JSON by hand, define it in the website UI and copy the resulting value (see Scanner Configuration below). We validate only that the value is well-formed JSON and store it verbatim. To clear an existing configuration, submit an empty JSON object {}.

Response¶

If your service is successfully created after we receive these variables, we will respond with raw XML containing a status of 1 and your new service ID.

Example:

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

Editing a Service¶

Variables omitted when editing a service will not affect their correspondent service settings.

Required Variables¶

Optional Variables¶

Variable	Description
database_id	A string which only needs to be specified if validation_method is set to database or ondevicedatabase. This needs to be set to the ID of the database the scans will be validated against.
direct_history_url	Set to the URL you want to loaded in web view when the user clicks the History option in the app. Set to empty to disable.
direct_lookup_url	Set to the URL you want to loaded in web view when the user clicks the Lookup option in the app. Set to empty to disable.
postback_url	A string which only needs to be specified if validation_method is set to postback. This needs to be set to the destination URL all scans will be forwarded to. More info.
postback_receiver_only	Set to 1 if your postback_url can only receive. Set to 0 if it can receive and respond with the expected XML. The default value is 0.
postback_real_time_scans	Set to 1 enable or 0 to disable the postback of each online scan made directly to the server. This variable must be submitted together with the postback_url variable to add postback functionality to non-postback service types such as record, database, etc. It does not work with services of type postback.
postback_uploaded_scans	Set to 1 enable or 0 to disable the postback each on-device scan uploaded to the server. This variable must be submitted together with the postback_url variable to add postback functionality to non-postback service types such as record, database, etc. It does not work with services of type postback.
regex_response_pattern	The first half of a regular expression match and replace pair. Set to a regular expression pattern you want to match in the scan response and replace with regex_response_replacement. Set to empty to disable. This variable must be submitted together with regex_response_replacement.
regex_response_replacement	The second half of a regular expression match and replace pair. Set to the value that will replace the corresponding regex_response_pattern match. Set to empty to disable. This variable must be submitted together with regex_response_pattern.
regex_scan_pattern	The first half of a regular expression match and replace pair. Set to a regular expression pattern you want to match in the scan value and replace with regex_scan_replacement. Set to empty to disable. This variable must be submitted together with regex_scan_replacement.
regex_scan_replacement	The second half of a regular expression match and replace pair. Set to the value that will replace the corresponding regex_scan_pattern match. Set to empty to disable. This variable must be submitted together with regex_scan_pattern.
service_name	A string which specifies what you'd like to rename your service.
description	A string which specifies the new or modified description of your service.
duplicate_value	An integer value that specifies the status of a duplicate scan if validation_method is set to database or ondevicedatabase. Set to 1 for valid scan status and 0 for invalid scan status. The default status of duplicates are valid (e.g. value set to 1).
device_duplicate_value	An integer value that specifies the status of a duplicate scan when scanning on-device. It’s only for checking against scans currently stored on the device. Set to 1 to make the status of duplicate scans currently on the device valid and set to 0 to make them invalid. The default status of duplicates on-device are valid (e.g. value set to 1). This only applies when the validation_method is set to record, ondevicerecord, database or ondevicedatabase. NOTE: if the duplicate_value option is set to 0 (invalid) then this option is overridden.
period_start_date	A string which specifies the date when the new service should become active. Can be formatted as MM/DD/YYYY or YYYY-MM-DD (Examples: 12/20/2012 or 2012-12-20). If this parameter is not specified, the service is always active.
period_start_time	A string which specifies the time when the new service should become active. Can be formatted as hhss or hh:mma (Examples: 18:30:00 or 6:30pm). If this parameter is not specified, the service is activated at 12:00AM on the specified period_start_date.
period_end_date	A string which specifies the date when the new service should become inactive. Can be formatted as MM/DD/YYYY or YYYY-MM-DD (Examples: 12/20/2012 or 2012-12-20). If this parameter is not specified, the service is always active.
period_end_time	A string which specifies the time when the new service should become inactive. Can be formatted as hhss or hh:mma (Examples: 18:30:00 or 6:30pm). If this parameter is not specified, the service remains active until 11:59:59PM on the specified period_end_date.
upload_email	A string which specifies the email address the accountholder would like a CSV file of scan data automatically sent to after each upload. If this parameter is not specified, scan data is not emailed.
upload_email_format	A string which specifies the format of the CSV file to be emailed to the email address specified under upload_email. Possible values are regular (do not include scan properties information) and properties (includes scan properties). Default value is regular.
viewOtherScans	A boolean value which specifies which scans an authorized user can view on their device. If set to 0, the user can only view their own scans. If set to 1, the user can view the scans of every user authorized for the service. This value is set to 1 by default.
symbologies	An integer or set of integers specifying the barcode symbolgy IDs. You can specify a single integer or a comma-separated list of integers (Examples: 33 or 33, 34, 12). By selecting only those symbologies which your app users will scan, the scan process will be quicker and more accurate. See the table of symbology ID numbers. Note: All symbologies are not available to all accounts. Updating the service without submitting the 'symbologies' parameter will reset to default.
auto_next_scan	An integer value to enable or disable the Auto-Next Scan feature. This option is not enabled by default. Set to 0 to disable this feature. Set to 1 for Only when valid mode. Set to 2 for Always and save if Error mode. Set to 3 for Always and discard if Error mode.
auto_next_scan_delay	An integer value specifying the delay in seconds before the Auto-Next Scan feature will trigger after a scan response is displayed. Default delay is approximately 1 second. Only for services with auto_next_scan enabled.
enableGPS	A boolean value which makes the service submit GPS location with every scan as a scan property. If set to 1, location will be submitted. If set to 0, it will not be submitted. This value is set to 0 by default. Background GPS.
block_camera_scan	A boolean value which specifies if users are allowed to scan barcode using the device's camera. If set to 0, users are allowed to scan using device camera. If set to 1, users will not be able to scan via the device's camera. This value is set to 0 by default.
block_manual_scan	A boolean value which specifies if users are allowed to enter scan values manually. If set to 0, users are allowed to enter scan data manually. If set to 1, users are not allowed to enter scan data manually. This value is set to 0 by default.
block_db_search	A boolean value which specifies if users are allowed to lookup values in database. If set to 0, users are allowed to lookup. If set to 1, users are not allowed lookup in database. This value is set to 0 by default.
auto_sync	Set to 1 to enable Auto Sync. By default we will sync scans saved on-device to codeREADr servers and sync down database updates if the service is an ondevicedatabase type service. Note: currently only on-device databases containing up to 50,000 values are supported. Contact us if your database exceeds that limit and learn your options.
auto_sync_up_url	Set it to your own Postback URL to skip us and auto sync scans directly to your server. Only for services with auto_sync enabled.
auto_sync_up_delay	An integer value specifying the delay in seconds between attempts to upload scans to the server. Default delay is 2 seconds. Only for services with auto_sync enabled.
auto_sync_down_url	Set to 0 to disable automatic downloading of database updates. Users will have to manual download database updates. If you need to re-enable set to 1. Only for on-device database services with auto_sync enabled. Note: specifying your own cutom URL is not publicly supported at this time.
auto_sync_down_delay	An integer value specifying the delay in seconds between checks to sync down new database updates from the server. Default delay is 120 seconds. Only for services with auto_sync enabled.
decoder_config	A JSON string defining the barcode scanner configuration for the service. Configurations have many options, so rather than authoring the JSON by hand, define it in the website UI and copy the resulting value (see Scanner Configuration below). We validate only that the value is well-formed JSON and store it verbatim. To clear an existing configuration, submit an empty JSON object {}.

Response¶

If your service is successfully edited 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>

Scanner Configuration (decoder_config)¶

The decoder_config variable (available on both create and update) holds the service's barcode scanner configuration as a JSON string. A configuration can include many options, so the recommended way to produce a valid value is:

1. In the website, open the service and define its barcode scanner configuration. See Barcode Scanner Configurations in the knowledge base.
2. Copy the configuration's JSON value and submit it as the decoder_config variable (as a standard POST parameter, like the other variables above).

The API validates only that the value is well-formed JSON and stores it verbatim. To clear an existing configuration, submit an empty JSON object {}.

Notes:

• Setting a scanner configuration on the service locks it for that service. Without a service-level configuration, app users can set the scan mode and barcode formats from the app's Settings tab (unless the admin hides that tab); once decoder_config is set, those choices are fixed for the service.
• A service's scanner configuration applies to its primary scan action and to its barcode-type questions, unless a barcode question defines its own configuration, which takes precedence for that question.

Deleting a Service¶

Required Variables¶

Response¶

If your service is successfully deleted 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>

Authorizing / De-Authorizing Users For Services¶

Required Variables¶

Response¶

If your users are successfully authorized / de-authorized for the specified services 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>

Adding / Removing Questions from a Service¶

Required Variables¶

Optional Variables¶

Response¶

If your questions are successfully added / removed from the specified services 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>