CodeREADr

Insert one new barcode value into a database, via action=addvalue. INSERT-ONLY, and that is the whole difference from 'Insert or update a barcode value': a value already in the database is refused with error 1027 rather than overwritten. Use this when a duplicate should be an error and `upsertvalue` when it should not. VALUES OVER 500 CHARACTERS ARE SILENTLY TRUNCATED to 500 with no error returned, so a long value is stored as something the scanner will never match.

Delete every value in a database, keeping the database itself. PERMANENT AND UNFILTERED: there is no value, prefix or date argument, so this empties the whole database in one call. The database and its service links survive, which is the difference from 'Delete a database' -- and also why it is the more dangerous of the two in practice, since every service pointed at it keeps running and starts rejecting every scan. Answers a bare `<status>1</status>` with no count of what was removed.

Create an empty validation database, via action=create. Returns the new database's id. `case_sensitivity` IS PERMANENT: CodeREADr states that once the database is created this setting cannot be changed, so a database created with the default (case-INsensitive) cannot be made case-sensitive later -- it has to be recreated and refilled. A name already in use is error 216.

Permanently delete one database and every value in it. PERMANENT, and it destroys every barcode value the database holds. CodeREADr REFUSES to delete a database still linked to a service (error 205, 'Unlink those services from the database and try again'), which is a genuine guard -- but it protects the service, not the data, so an unlinked database with a million values is removed without further comment. 'Clear a database' empties one while keeping it and its service links.

Permanently remove one barcode value from a database. PERMANENT. Matched by the value itself rather than an id, against a stored value capped at 500 characters, so a longer string matches nothing and deletes nothing. One value per call -- there is no bulk delete and no `all` keyword here; emptying a database is 'Clear a database'. A value that is not present is error 1017.

Change the response or validity of an existing barcode value. Edits by MATCHING the barcode value, not by an id -- and the stored value is capped at 500 characters, so a longer string matches nothing. Only `response` and `validity` can be changed; unlike the upsert actions, `validity` here is left UNCHANGED when omitted rather than defaulting to valid. A value that is not present is error 1017.

List the account's validation databases, via section=databases. A database is the list of barcode values a `database` or `ondevicedatabase` service validates scans against. `info_level` is a real performance control rather than a formatting one: the default reply counts the items in each database, which CodeREADr calls 'potentially costly', and `names` or `services` skips that count.

Read the barcode values in a database, with search and paging. The read side of a validation database: each row is a barcode `value`, its `response` text and its `validity`. The four search fields pair an exact form with a `like` partial form and compose with each other. PAGE IT: a validation database can hold hundreds of thousands of values and there is no documented default cap on this action, so send `limit` -- and `offset` is honoured only alongside it.

Rename one database, via section=databases & action=update. Renaming is ALL this action does -- despite the `update` verb it reaches none of the database's other settings, and `case_sensitivity` in particular is fixed at creation. Both fields are required. A name already in use is error 216.

Write a batch of barcode values in one call, via action=upsertmultivalue. THE BULK-LOAD TOOL ON THIS SURFACE, and the substitute for the CSV upload action this integration does not ship (that one takes a real multipart file, which a tool call has no channel for). Up to 100 values per call. Each entry may name its OWN `database_id`, so one call can write to several databases; an entry with no local and no global `database_id` is SILENTLY IGNORED rather than refused. CodeREADr's wire format is `values[0][value]` and the connector builds that from the array sent here -- an entry is an object, not a bare string. Same 500-character silent truncation on every value.

Insert a barcode value, or overwrite it if it already exists. The idempotent form of 'Add a barcode value': an existing value is OVERWRITTEN rather than refused, so its `response` and `validity` are replaced by what this call sends. Same 500-character silent truncation. For more than one value at a time use 'Insert or update up to 100 barcode values', which is one API call instead of a hundred.

List the devices activated on this account. A device is a phone or scanner that has activated against the account; device ids are what 'List scans' and 'List scan uploads' filter by. There is no action to delete or deactivate a device on this API -- measured 2026-09-25, `devices` accepts only `retrieve` and `update`, and `delete` and `create` both answer error 110 ('Invalid action Parameter'). Renaming is the only write.

Rename one activated device, via section=devices & action=update. Both fields are required: this action renames and does nothing else, so there is no partial form of it. The name is what identifies the device in 'List scans' output, which is the reason to set it.

Read this account's API rate limits and what is left of them. The cheapest call on the surface and the one worth making first. Answers `<minute left=... limit=.../>` and `<day left=... limit=.../>`; `-1` means unlimited. Exceeding the per-minute allowance is error 111 and the per-day allowance error 113, both of which arrive as HTTP 200 like everything else here. THIS IS NOT A CREDENTIAL CHECK and must not be used as one: with a wrong key or no key it answers `<status>0</status>` with error 101 ('The API key is missing.'), the SAME reply either way -- see the `probe_gap` on this provider's adapter.

Add a choice to a multiple-choice question, via action=addanswer. Required for `option`, `dropdown`, `checkbox` and `webcollect` questions, which do not work without answers. `question_id` accepts a comma-separated list and `all`, so the same answer text can be added to many questions at once. Answer text must be unique within a question (error 1036); a failure to add is error 265.

Create a data-collection question, via section=questions & action=create. Returns the new question's id. CREATING IS USUALLY NOT ENOUGH: `option`, `dropdown`, `checkbox` and `webcollect` questions are unusable until answer options are added with 'Add an answer option' using the id this returns, and a multiple-choice question must keep at least two of them (error 206). The question is not shown to anyone until it is also attached to a service.

Permanently delete one or more questions. PERMANENT, AND IT TAKES `all`, which removes every question on the account. Deleting a question removes it from every service it was attached to. Use 'Remove questions from services' instead when the intent is to stop asking it on ONE service and keep the question. A question that cannot be deleted answers error 261.

Remove choices from a question, via action=deleteanswer. Takes ANSWER ids, not question ids -- the one place in this section where that is true, and the ids come from 'List questions'. PERMANENT. A multiple-choice question must keep at least two answers, so removing the second-to-last is refused with error 206 rather than leaving a question nobody can answer; a failure to delete is error 266.

List the account's data-collection questions. Questions are the data-collection form the app shows around a scan; they exist at account level and are attached to services with 'Add questions to services'. Unfiltered it returns every question.

Attach a named value to scans, via section=scan_properties. Scan properties are arbitrary name/value metadata on a scan record, and what 'List or search scans' filters on with `with_property` and `includeProperty`. THIS IS ALSO THE UPDATE PATH: the provider's own reference heads a section 'Updating a Scan Property' and its entire body is 'Same as Creating a Scan Property', so setting an existing name replaces its value. `scan_id` takes a comma-separated list, so one call can tag many scans at once. Name and value are each limited to 100 characters, and BOTH ARE CASE-SENSITIVE here -- while the retrieve action matches the name case-INsensitively, which is the provider's own asymmetry and a real source of confusion.

Permanently remove one named property from one scan. PERMANENT, though narrow: one property on one scan, and the scan record itself is untouched. The name is CASE-SENSITIVE here, matching create rather than retrieve, so a name that reads back fine may not delete unless the case matches exactly.

Read one named property from one scan. One scan and one property name per call -- unlike the create action, `scan_id` here is a single id. The name is matched case-INsensitively, which is the opposite of how create and delete treat it. To read every property on a scan without knowing the names, use 'List or search scans' with `showProperties=1` instead.

Permanently delete scan records by id. PERMANENT, and it destroys collected field data: a scan record carries the barcode, the response, the timestamp, the device and user, and every question answer attached to it. Unlike most delete actions here this one takes ONLY explicit ids -- CodeREADr documents no `all` keyword for it -- so it cannot wipe the account in one call. A scan that cannot be deleted is error 804. Confirm with 'List or search scans'.

Read scan records, with the provider's full filter grammar. THE REASON MOST ACCOUNTS HAVE AN API KEY: this is the scan data. Each `<scan>` carries its device, service, user, status, the barcode value (`tid`), the response (`result`), a timestamp, one `<answer>` per question answered and, with `showProperties=1`, its scan properties. DEFAULT LIMIT IS 10000, which is the one default on this surface large enough to matter -- page with `limit` and `offset` rather than relying on it. TIMESTAMPS DEFAULT TO CODEREADR'S OWN TIME ZONE, America/New_York, NOT to UTC and not to the account's setting; send `timezone` explicitly, or the keyword `account` to follow the account holder's. `timestamp_received` and `timestamp_modified` do double duty: set to `1` each also REDIRECTS the date filters onto that column instead of the scan's own timestamp, and setting both applies the range to either with OR.

Attach data-collection questions to services, via action=addquestion. Attaches every id in `question_id` to every id in `service_id`; both take comma-separated lists and `all`. `condition` decides WHEN the app asks, and the default (`pre_submit`) is not always what is wanted. `required` is honoured only when ADDING, which is why it is not offered on the remove tool.

Let app users scan against services, via action=adduserpermission. Grants the cross product: every id in `user_id` is authorised for every id in `service_id`. Both accept a comma-separated list and the keyword `all`, so `service_id=all&user_id=all` authorises the whole account for everything in one call. Read the result back with 'List services', whose `<user>` elements are this wiring.

Create a scanning service, via section=services & action=create. `validation_method` is the only required field and it is the one that decides everything else -- three of its six values require a companion field and are refused without it. Returns the new service's `<id>`, which is what every other service tool takes. THE WIDEST WRITE ON THIS PROVIDER: this surface has thirty-odd optional settings and several of them have effects outside CodeREADr -- `upload_email` mails scan data out after every upload, `postback_url` forwards every scan to a third-party server, and `enableGPS` collects the location of the people using the app. `enable_direct_scan` can only be set HERE: CodeREADr refuses it on update with error 223.

Permanently delete one or more services. PERMANENT, AND IT TAKES `all`. `service_id` accepts a comma-separated list and the keyword `all`, so a single call can remove EVERY service on the account -- and a service is what the scanning app connects to, so deleting one stops every device configured for it. CodeREADr publishes no recycle bin and no undelete action. Answers a bare `<status>1</status>` with no record of what was removed, so confirm with 'List services'.

Detach questions from services, via action=removequestion. Detaches every id in `question_id` from every id in `service_id`, both accepting `all`. The QUESTION SURVIVES -- this unwires it from the service rather than deleting it, and 'Delete questions' is the tool that destroys one. Answers already collected are not touched. Not marked destructive for that reason.

List the account's services and how each one validates scans. A service is CodeREADr's unit of work: it decides what the scanning app does with a barcode. Each `<service>` carries its id, `name`, `validationmethod`, the `database` or `postback` it is bound to, `duplicateScanValue`, and a `<user>` and `<question>` element per authorised user and attached question -- which makes this the way to read the user and question wiring that 'Authorise users for services' and 'Add questions to a service' write. Unfiltered it returns every service.

Remove app users' access to services, via action=revokeuserpermission. The inverse of 'Authorise users for services', with the same cross-product semantics and the same `all` keyword on both fields. NOT MARKED DESTRUCTIVE -- no user, service or scan is deleted and the grant can be reissued -- but it does take working scanners offline: a de-authorised user cannot scan against that service until authorised again.

Change one service's settings, via section=services & action=update. Omitted fields are left alone -- 'Variables omitted when editing a service will not affect their correspondent service settings' -- WITH ONE DOCUMENTED EXCEPTION that is easy to lose money on: `symbologies`. CodeREADr states that updating a service without sending `symbologies` RESETS it to the default set, so a call that means to change only the name also changes which barcodes the service accepts. Read the service first and resend the value. `validation_method` is NOT settable here: a service's type is fixed at creation.

List the batches in which on-device scans were uploaded. An upload is one batch of scans a device sent to CodeREADr, which is how on-device services deliver their data. The ids returned here are what 'List or search scans' takes as `upload_id`, so this is the way to pull exactly the scans from one sync rather than a date range. Read-only: measured 2026-09-25, `uploads` accepts `retrieve` and nothing else -- `delete` answers error 110.

Create a scanner-operator login, via section=users & action=create. `password` IS CONDITIONALLY REQUIRED and the condition is what the username looks like: if `username` is an e-mail address CodeREADr IGNORES any password sent and requires the user to set their own; if it is not an e-mail address the password is required (error 341). A username already taken is error 320, and an invalid one (spaces, heavy punctuation) error 340. THIS TOOL TAKES A SECRET AS AN ARGUMENT -- the password travels as a form field like every other value here, so prefer an e-mail username and let the person set their own.

Permanently delete one or more app users. PERMANENT, AND IT TAKES `all` -- 'You can also use the keyword all to delete all users', which removes every scanner login on the account in one call and stops everyone scanning. The account owner's own app user is protected and answers error 343 instead. There is no undelete.

List the account's app users, via section=users & action=retrieve. An app user is a scanner-operator login for the CodeREADr mobile app, NOT a CodeREADr web-console administrator; the two are different populations and this section is the former. Unfiltered it returns every app user.

Rename an app user or change their password or device limit. Omitted fields are left alone. A `username` already in the system is refused (error 320). CANNOT TOUCH THE ACCOUNT OWNER'S app user: CodeREADr answers error 343, 'You cannot use this action to update or delete the app-user tied to the account owner'. Takes a password as an argument, with the same caution as 'Create an app user'.

Check an app user's username and password, via action=validate. Answers whether that username/password pair is a valid app-user login, for a caller building their own sign-in ahead of a scan session. THIS IS A PASSWORD ORACLE and should be granted deliberately: it takes a plaintext password as a tool argument and reports whether it is correct, so an agent holding this one action can test guesses against every app user on the account. IT DOES NOT VALIDATE THE API KEY and cannot be used as a connection check -- the two credentials are unrelated.