API: Databases¶

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

Creating a Database¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `create`.
api_key	Must be set to your unique API key.
database_name	A string which specifies the name of your new database.

Optional Variables¶

Variable	Description
case_sensitivity	A boolean value which specifies whether database values are case sensitive. Once the database is created, this setting cannot be changed. Specify `1` for case-sensitive validation, or `0` for case-insensitive validation. Set to `0` (not case-sensitive) by default.

Response¶

If your database is successfully created, we will respond with raw XML containing a status of 1 and your new database ID.

Example:

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

Retrieving a List of Databases¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `retrieve`.
api_key	Must be set to your unique API key.

Optional Variables¶

Variable	Description
database_id	An integer or series of integers which specifies the numeric IDs of the databases you want to list. You can specify a single integer or a comma-separated list of integers (Examples: `1005` or `1005, 1010, 1254`). Set to `all` by default.
info_level	Possible values are `names` and `services`. Target just the info you need for faster response times. `names` - Only includes the name node (excluding associated services and potentially costly item count). `services` - Includes both name and associated service nodes (excluding the slower item count in the default request).

Response¶

If we successfully receive your variables, we will respond with raw XML containing status and database information.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
    <database id="120">
        <name>My tickets</name>
        <count>5000</count>
        <service id="123"/>
        <service id="124"/>
    </database>
    <database id="125">
        <name>My inventory</name>
        <count>1574</count>
        <service id="323"/>
        <service id="524"/>
    </database>
</xml>

Renaming a Database¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `update`.
api_key	Must be set to your unique API key.
database_id	An integer which specifies the numeric ID of the database you want to rename.
database_name	A string which specifies the new name of your database.

Response¶

If your database is successfully renamed, we will respond with raw XML containing a status of 1.

Example:

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

Deleting a Database¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `delete`.
api_key	Must be set to your unique API key.
database_id	An integer which specifies the numeric ID of the database you want to delete.

Response¶

If your database is successfully deleted, we will respond accordingly with raw XML containing a status of 1.

Example:

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

Clearing a Database¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `clear`.
api_key	Must be set to your unique API key.
database_id	An integer which specifies the numeric ID of the database you want to clear.

Response¶

If your database is successfully cleared, we will respond with raw XML containing a status of 1.

Example:

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

Retrieving Values of a Database / Search for Values in a Database¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `showvalues`.
api_key	Must be set to your unique API key.
database_id	An integer which specifies the numeric ID of the database.

Optional Variables¶

Variable	Description
value	A string to perform an exact match search against the value. (Example: `value=abc` will limit results to one value).
valuelike	A string to perform a partial match search against the value. (Example: `valuelike=abc` will match abc1 , 123abc , 123abc123 , etc).
response	A string to perform an exact match search against the response. (Example: `response=abc` will limit results to one value).
responselike	A string to perform a partial match search against the response. (Example: `responselike=abc` will match values with responses abc1 , 123abc , 123abc123 , etc).
validity	An integer to filter results by validity. Set to `1` to show only valid values, and set it to `0` to show only invalid.
limit	An integer which limits the maximum number of results displayed within the list.
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 values that begins with the 6^th value).

Response¶

We will respond with raw XML containing a status of 1, results count and search results.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
    <count>2</count>
    <value validity="1">
        <id>A1</id>
        <response>A2</response>
    </value>
    <value validity="1">
        <id>B1</id>
        <response>B2</response>
    </value>
</xml>

Uploading a CSV File to a Database¶

NOTE: This API is a HTTP multipart/form-data POST request to submit normal variables i.e. section, action, etc and the actual CSV data file under the param csvfile.

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `upload`.
api_key	Must be set to your unique API key.
database_id	An integer which specifies the numeric ID of the database.
csvfile	A CSV file as part of a multipart/form-data POST. (Not the url to the file) For formatting guidelines, see this page.

Optional Variables¶

Variable	Description
trim_value	Set to `1` to trim or `0` to not trim value white space. Defaults to `1`.
is_deferred	Set to `1` to asynchronous import your CSV file. This is recommended for uploads of more than 10,000 values.

Response¶

If your CSV file is successfully imported, we will respond accordingly with raw XML containing a status of 1.

Example:

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

API Request Examples¶

Curl Command Example:

curl -F section=databases -F action=upload -F database_id=YOUR_DB_ID -F api_key=YOUR_API_KEY -F csvfile=@./YOUR_LOCAL_FILE.csv https://api.codereadr.com/api/

HTML Form Example:

<html><body>
    <form action="https://api.codereadr.com/api/" enctype="multipart/form-data" method="POST">
      <input name="api_key" placeholder="YOUR_API_KEY" type="text"> <br/>
      <input name="section" type="hidden" value="databases">
      <input name="action" type="hidden" value="upload">
      <input name="database_id" type="text" placeholder="YOUR_DATABASE_ID">  <br/>
      Choose <i>csvfile</i> <input name="csvfile" type="file">  <br/>
      <input type="submit" value="Import CSV File Into My Database">
    </form>
</body></html>

Link to simple HTML form that imports the entries of a CSV file into a specified CodeREADr database.

Inserting or Updating Multiple Barcodes¶

The upsertmultivalue action allows you to specify up to 100 database values to insert/update as without having to upload a CSV file like you do with the upload action. It's also more flexible than the upload action. You can choose to specify some variables globally that will apply to all values in the request but also specify some variables locally to specific values in the request. This means in the same request you can insert/update values to multiple databases. Locally specifying value variables follows the array syntax values[0][VARIABLE] to values[99][VARIABLE].

When a value does not specify it's own local values[i][database_id] or values[i][trim_value], the setting falls back to the global variable (database_id or trim_value) if it was specified.
The value will be ignored if no local or global database_id is specified.
trim_value will default to 1 if no local or global trim_value is specified.

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `upsertmultivalue`.
api_key	Must be set to your unique API key.
values	An array of up to 100 database values.
values[i][value]	A string specifying the barcode value. Values longer than 500 characters are silently truncated to 500; no error is returned. `i` is the index in the values array.

Optional Variables¶

Variable	Description
database_id	An integer which specifies the numeric ID of the database. Will apply to all values that do not have the local variable set via `values[i][database_id]`.
trim_value	Set to `1` to trim or `0` to not trim value white space. Defaults to `1`. This option applies to all values that do not have the local variable set via `values[i][trim_value]`.
values[i][database_id]	An integer which specifies the numeric ID of the database. Only applies to `value[i]` and not all values in the array.
values[i][trim_value]	Set to `1` to trim or `0` to not trim value white space. Only applies to `value[i]` and not all values in the array.
values[i][response]	A string which specifies the barcode value's associated response text.
values[i][validity]	A boolean type which specifies the validity of the barcode. Input `0` and the new barcode value will be treated as invalid whenever it is scanned. Set to `1` (valid) by default.

Response¶

This action allows you to update your database without first checking the state of the value. If your barcode value is successfully inserted or updated to match your request options, will respond accordingly with raw XML containing a status of 1.

Example:

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

Example Specifying Variables with XML¶

<xml>
   <action>upsertmultivalue</action>
   <api_key>API_KEY</api_key>
   <database_id>DB_ID</database_id>
   <section>databases</section>
   <trim_value>1</trim_value>
   <values>
      <database_id>36156</database_id>
      <response>Thank you!</response>
      <validity>1</validity>
      <value>ABC</value>
   </values>
   <values>
      <database_id>36156</database_id>
      <response>Hello world!</response>
      <trim_value>0</trim_value>
      <validity>1</validity>
      <value>  spaces  </value>
   </values>
</xml>

Inserting or Updating a Barcode¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `upsertvalue`.
api_key	Must be set to your unique API key.
database_id	An integer which specifies the numeric ID of the database.
value	A string which specifies the barcode value. Values longer than 500 characters are silently truncated to 500; no error is returned.

Optional Variables¶

Variable	Description
response	A string which specifies the barcode value's associated response text.
validity	A boolean type which specifies the validity of the barcode. Input `0` and the new barcode value will be treated as invalid whenever it is scanned. Set to `1` (valid) by default.
trim_value	Set to `1` to trim or `0` to not trim value white space. Defaults to `1`.

Response¶

This action allows you to update your database without first checking the state of the value. If your barcode value is successfully inserted or updated to match your request options, will respond accordingly with raw XML containing a status of 1.

Example:

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

Adding a Barcode Value to a Database¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `addvalue`.
api_key	Must be set to your unique API key.
database_id	An integer which specifies the numeric ID of the database.
value	A string which specifies the barcode value. Values longer than 500 characters are silently truncated to 500; no error is returned.

Optional Variables¶

Variable	Description
response	A string which specifies the barcode value's associated response text.
validity	A boolean type which specifies the validity of the barcode. Input `0` and the new barcode value will be treated as invalid whenever it is scanned. Set to `1` (valid) by default.
trim_value	Set to `1` to trim or `0` to not trim value white space. Defaults to `1`.

Response¶

If your barcode value is successfully added, we will respond accordingly with raw XML containing a status of 1.

Example:

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

Editing Barcode Responses and Results¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `editvalue`.
api_key	Must be set to your unique API key.
database_id	An integer which specifies the numeric ID of the database.
value	A string which specifies the barcode value to edit. This is matched against the stored value, which is capped at 500 characters — so a longer string will not match anything.

Optional Variables¶

Variable	Description
response	A string which specifies the barcode value's associated response text.
validity	A boolean type which specifies the validity of the barcode. Input `0` and the new barcode value will be treated as invalid whenever it is scanned. Validity remains unchanged by default.

Response¶

If your barcode response text and/or validity is successfully edited, we will respond accordingly with raw XML containing a status of 1.

Example:

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

Deleting Values From a Database¶

Required Variables¶

Variable	Description
section	Must be set to `databases`.
action	Must be set to `deletevalue`.
api_key	Must be set to your unique API key.
database_id	An integer which specifies the numeric ID of the database.
value	A string which specifies the barcode value to delete. This is matched against the stored value, which is capped at 500 characters — so a longer string will not match anything.

Response¶

If your barcode value is successfully deleted, we will respond with raw XML containing a status of 1.

Example:

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