The Orca Scan Barcode Scanner API lets you integrate barcode scanning into your systems through a single REST API. No device-specific code needed – just simple endpoints that work with any scanning device, from smartphones to professional hardware.
Getting Started with the Orca Scan Barcode Scanner API
You’re a developer who needs to add barcode scanning to your application, but writing native code for multiple devices is time-consuming and complex. Instead of managing different scanning libraries and hardware compatibilities, you can use our REST API to handle all scanning operations.
Your users capture data through the Orca Scan mobile app, while you focus on integrating the data through familiar REST endpoints – supporting everything from iOS and Android devices to professional scanning hardware.
Supported Devices and Hardware Compatibility
The Orca Scan barcode scanner app works with any:
- iOS or Android smartphone or tablet
- Barcode scanners from Honeywell, Datalogic, Zebra and others
- Bluetooth scanner connected to an iOS or Android device
TIP: start with low cost smartphones, add enterprise scanners if needed.
Implementation Guide for the Barcode Scanner API
The Barcode Scanner API is a REST based API that can be accessed using any programming language. To get started:
- Install the Orca Scan app on an iOS or Android device
- Open the app and create a new sheet
- Customise your data capture fields
- Login to the Orca Scan web app
- Go to Account Settings and copy your API key
- Launch the command line on your computer
- Run the following
curl
command to list your sheets
curl -X GET "https://api.orcascan.com/v1/sheets" -H "Authorization: Bearer API_KEY"
API Authentication and Security
The Barcode Scanner API is secured using HTTPS and requires an API key with each request. Please note: you must have a Business subscription to use this feature.
Orca Scan Endpoints and Methods
You can think of a sheet as a mini-database with its own unique configuration. The following endpoints let you manage sheets, rows, history, and user access.
Sheets
GET /sheets
= get a list of sheets
# request
curl https://api.orcascan.com/v1/sheets -H "Authorization: Bearer API-KEY"
// response
{
"data": [
{
"_id": "62a3188f098a6343fe0d9c1b",
"name": "Public API Owned",
"isOwner": true,
"canAdmin": true,
"canUpdate": true,
"canDelete": true,
"canExport": true
},
{
"_id": "62a31e89098a6343fe0d9c1e",
"name": "Public API Readonly",
"isOwner": false,
"canAdmin": false,
"canUpdate": false,
"canDelete": false,
"canExport": false
},
{
"_id": "62a32045098a6343fe0d9c1f",
"name": "Public API Can Update",
"isOwner": false,
"canAdmin": false,
"canUpdate": true,
"canDelete": false,
"canExport": false
},
{
"_id": "62a32061098a6343fe0d9c22",
"name": "Public API Can Delete",
"isOwner": false,
"canAdmin": false,
"canUpdate": false,
"canDelete": true,
"canExport": false
},
{
"_id": "62a32112098a6343fe0d9c25",
"name": "Public API Can Export",
"isOwner": false,
"canAdmin": false,
"canUpdate": false,
"canDelete": false,
"canExport": true
},
{
"_id": "62a3214f098a6343fe0d9c2a",
"name": "Public API Can Admin",
"isOwner": false,
"canAdmin": true,
"canUpdate": true,
"canDelete": true,
"canExport": false
}
]
}
GET /sheets/:sheetId/fields
= get a list of fields in a sheet
# request (replace :sheetId)
curl https://api.orcascan.com/v1/sheets/:sheetId/fields -H "Authorization: Bearer API-KEY"
// response
{
"data": [
{
"key": "barcode",
"label": "Barcode",
"type": "string",
"required": true
},
{
"key": "quantity",
"label": "Quantity",
"type": "integer",
"required": false
},
{
"key": "expires",
"label": "Expires",
"type": "datetime",
"required": false
},
{
"key": "photo",
"label": "Photo",
"type": "image"
},
{
"key": "certificate",
"label": "Certificate",
"type": "attachment"
}
]
}
GET /sheets/:sheetId/settings
= get sheet settings
# request (replace :sheetId)
curl https://api.orcascan.com/v1/sheets/:sheetId/settings \
-H "Authorization: Bearer API-KEY"
// response
{
"data": {
"allowPublicExport": true,
"publicExportUrl": "https://api.orcascan.com/v1/sheets/sVVKYsnp-9b7Rl7i.json",
"allowPublicEntry": false,
"publicEntryUrl": "https://api.orcascan.com/v1/62a3188f098a6343fe0d9c1b",
"allowWebHookIn": false,
"webHookInUrl": "https://api.orcascan.com/v1/sheets/XbC5Xc1CMgv9wq-C",
"lookupUrl": "",
"validationUrl": "",
"webHookOutUrl": "",
"secret": ""
}
}
PUT /sheets/:sheetId/clear
= clear all rows in a sheet
# request (replace :sheetId)
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
https://api.orcascan.com/v1/sheets/:sheetId/clear
POST /sheets
= create a sheet
# request
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
-d '{ "name": "My things", "templateName": "Inventory" }' \
https://api.orcascan.com/v1/sheets
// response
{
"data": {
"_id": "6664ff416518d60a3c1c700a",
"name": "My things",
"rows": 0
}
}
PUT /sheets/:sheetId/rename
= rename a sheet
# request (replace :sheetId)
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer orca_aYUClq9tI0oxqKPfXwVHo3mVy7v" \
-d '{ "name": "New sheet name", "description": "Backup 27 May 2004" }' \
https://api.orcascan.com/v1/sheets/:sheetId/rename
DELETE /sheets/:sheetId
= delete a sheet
# request (replace :sheetId)
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
https://api.orcascan.com/v1/sheets/:sheetId
Rows
GET /sheets/:sheetId/rows
= get all rows
# request (replace :sheetId)
curl https://api.orcascan.com/v1/sheets/:sheetId/rows \ -H "Authorization: Bearer API-KEY"
// response
{
"data": [
{
"_id": "62b8abeb1a3f8d11e2ad781e",
"barcode": "6344554293308",
"name": "Fantastic Cotton Gloves",
"quantity": "20",
"description": "Sit tenetur iusto error eum laboriosam laboriosam.",
"date": "2017-01-01T18:38:17.000Z",
"location": "52.4319404, 0.5114626"
},
{
"_id": "62b8abeb1a3f8d11e2ad781f",
"barcode": "8162055462301",
"name": "Unbranded Frozen Table",
"quantity": "71",
"description": "Inventore aut rerum. Ea tempore error cupiditate",
"date": "2017-01-14T04:10:16.000Z",
"location": "51.6993409, 0.9225196"
}
]
}
GET /sheets/:sheetId/rows/:rowId
= get a single row
# request (replace :sheetId and :rowId)
curl https://api.orcascan.com/v1/sheets/:sheetId/rows/:rowId \
-H "Authorization: Bearer API-KEY"
// response
{
"data": {
"_id": "62a322f13a2579cd32b66c14",
"barcode": "barcode123456",
"name": "Hello World"
}
}
POST /sheets/:sheetId/rows
= add row(s)
# add row
# request (replace :sheetId)
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
-d '{ "barcode": "12345", "name": "Hello World", "photo": "base64..." }' \
https://api.orcascan.com/v1/sheets/:sheetId/rows
// response
{
"data": {
"_id": "629d313d74e4a61bf1517d3a",
"barcode": "12345",
"name": "Hello World",
"photo": "https://cdn.orca.storage/.../photo/jEIM9pSWdC2NG6HbmpebwA.jpg"
}
}
# add rows
# request (replace :sheetId)
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
-d '[ { "barcode": "1234", "name": "Hello World", "photo": "base64..." }, { "barcode": "5678", "name": "Hello Again", "photo": "base64..." } ]' \
https://api.orcascan.com/v1/sheets/:sheetId/rows
// response
{
"data": [
{
"_id": "669fc3b9d74909b0542638c1",
"barcode": "1234",
"name": "Hello World",
"photo": "https://cdn.orca.storage/.../photo/jEIM9pSWdC2NG6HbmpebwA.jpg"
},
{
"_id": "669fc3b9d74909b0542638c2",
"barcode": "5678",
"name": "Hello Again",
"photo": "https://cdn.orca.storage/.../photo/jEIM9pSWdC2NG6HbmpebwB.jpg"
}
]
}
PUT /sheets/:sheetId/rows/:rowId
= update a row
# request (replace :sheetId and :rowId)
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
-d '{ "barcode": "789", "name": "Hello World", "photo": "base64..." }' \
https://api.orcascan.com/v1/sheets/:sheetId/rows/:rowId
// response
{
"data": {
"_id": "629d313d74e4a61bf1517d3a",
"barcode": "789",
"name": "Hello World",
"photo": "https://cdn.orca.storage/.../photo/jEIM9pSWdC2NG6HbmpebwA.jpg"
}
}
DELETE /sheets/:sheetId/rows/:rowId
= delete a single row
# request (replace :sheetId and :rowId)
curl -X DELETE \
-H "Authorization: Bearer API-KEY" \
https://api.orcascan.com/v1/sheets/:sheetId/rows/:rowId
DELETE /sheets/:sheetId/rows
= delete multiple rows
# request (replace :sheetId)
curl -X DELETE \
-H "Authorization: Bearer API-KEY" \
-d '[ rowId1, rowId2 ]'
https://api.orcascan.com/v1/sheets/:sheetId/rows
History
GET /sheets/:sheetId/history
= get sheet history
# request (replace :sheetId)
curl https://api.orcascan.com/v1/sheets/:sheetId/history \
-H "Authorization: Bearer API-KEY"
// response
{
"data": [
{
"_id": "66678a4627b78f52140c12bc",
"barcode": "clx9ljgms0000z0dr0fop94zq",
"name": "new row",
"quantity": 20,
"_change": "add",
"_changedBy": "public-api-user@orcascan.com",
"_changedOn": "2024-06-10T23:20:38.704Z",
"_changedUsing": "",
},
{
"_id": "66678a4627b78f52140c12bd",
"barcode": "clx9ljgms0000z0dr0fop94zq",
"name": "updated row",
"quantity": 99,
"_change": "update",
"_changedBy": "public-api-user@orcascan.com",
"_changedOn": "2024-06-10T23:20:38.740Z",
"_changedUsing": "",
}
]
}
GET /sheets/:sheetId/:rowId/history
= get row history
# request (replace :sheetId and :rowId)
curl https://api.orcascan.com/v1/sheets/:sheetId/rows/:rowId \
-H "Authorization: Bearer API-KEY"
// response
{
"data": [
{
"_id": "66678a4627b78f52140c12bc",
"barcode": "clx9ljgms0000z0dr0fop94zq",
"name": "new row",
"quantity": 20,
"_change": "add",
"_changedBy": "public-api-user@orcascan.com",
"_changedOn": "2024-06-10T23:20:38.704Z",
"_changedUsing": "",
},
{
"_id": "66678a4627b78f52140c12bd",
"barcode": "clx9ljgms0000z0dr0fop94zq",
"name": "updated row",
"quantity": 99,
"_change": "update",
"_changedBy": "public-api-user@orcascan.com",
"_changedOn": "2024-06-10T23:20:38.740Z",
"_changedUsing": "",
}
]
}
Users
GET /sheets/:sheetId/users
= get users
# request (replace :sheetId)
curl https://api.orcascan.com/v1/sheets/:sheetId/users -H "Authorization: Bearer API-KEY"
// response
{
"data": [
{
"_id": "5f36ac26cdd51800ccdea10b",
"email": "jenny@orcascan.com",
"owner": false,
"canUpdate": true,
"canDelete": true,
"canExport": true,
"canAdmin": true
}
]
}
POST /sheets/:sheetId/users
= add a user to a sheet
# request (replace :sheetId)
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
-d '{
"email": "new.user@example.com",
"canUpdate": true,
"canDelete": true,
"canExport": true,
"canAdmin": false
}' \
https://api.orcascan.com/v1/sheets/:sheetId/users
// response
{
"data": {
"_id": "666b3d5f266e7bedc98a733f",
"email": "new.user@example.com",
"canUpdate": true,
"canDelete": true,
"canExport": true,
"canAdmin": false
}
}
PUT /sheets/:sheetId/users/:userId
= update a user in a sheet
# request (replace :sheetId and :userId)
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
-d '{
"email": "new.user@example.com",
"canUpdate": true,
"canDelete": true,
"canExport": true,
"canAdmin": false
}' \
https://api.orcascan.com/v1/sheets/:sheetId/users/:userId
// response
{
"data": {
"_id": "666b3d5f266e7bedc98a733f",
"email": "new.user@example.com",
"canUpdate": true,
"canDelete": true,
"canExport": true,
"canAdmin": false
}
}
DELETE /sheets/:sheetId/users/:userId
= remove a user from a sheet
# request (replace :sheetId and :userId)
curl -X DELETE \
-H "Authorization: Bearer API-KEY" \
https://api.orcascan.com/v1/sheets/:sheetId/users/:userId
Hooks
Register a webhook to receive a HTTP POST as your sheet changes (no need to poll).
GET /sheets/:sheetId/hook-events
= get list of supported events
# request (replace :sheetId)
curl -H "Authorization: Bearer API-KEY" \
https://api.orcascan.com/v1/sheets/:sheetId/hook-events
// response
{
"data": [
"rows:import:append",
"rows:import:replace",
"rows:add",
"rows:update",
"rows:delete",
"columns:clear",
"sheet:clear",
"sheet:settings:update"
]
}
GET /sheets/:sheetId/hooks
= get all hooks on a sheet
# request (replace :sheetId)
curl -H "Authorization: Bearer API-KEY" \
https://api.orcascan.com/v1/sheets/:sheetId
// response
{
"data": [
{
"_id": "66b33ed93f843a1fa88836b6",
"eventName": "rows:add",
"sheetId": "62a3188f098a6343fe0d9c1b",
"targetUrl": "https://example.com/add",
},
{
"_id": "66b33ed93f843a1fa88836b7",
"eventName": "rows:update",
"sheetId": "62a3188f098a6343fe0d9c1b",
"targetUrl": "https://example.com/update",
},
]
}
GET /sheets/:sheetId/hooks/:hookId
= get an existing hook
# request (replace :sheetId and :hookId)
curl -H "Authorization: Bearer API-KEY" \
https://api.orcascan.com/v1/sheets/:sheetId/hooks/:hookId
// response
{
"data": {
"_id": "66b33ed93f843a1fa88836b6",
"eventName": "rows:add",
"sheetId": "62a3188f098a6343fe0d9c1b",
"targetUrl": "https://example.com/add",
}
}
POST /sheets/:sheetId/hooks
= create a new hook
# request (replace :sheetId)
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
-d '{ "eventName": "rows:add", "targetUrl": "https://example.com/add" }' \
https://api.orcascan.com/v1/sheets/:sheetId/hooks
// response
{
"data": {
"_id": "66b33ed93f843a1fa88836b6",
"eventName": "rows:add",
"sheetId": "62a3188f098a6343fe0d9c1b",
"targetUrl": "https://example.com/add",
}
}
PUT /sheets/:sheetId/hooks/:hookId
= update an existing hook
# request (replace :sheetId and :hookId)
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
-d '{ "eventName": "rows:update", "targetUrl": "https://example.com/update" }' \
https://api.orcascan.com/v1/sheets/:sheetId/hooks/:hookId
// response
{
"data": {
"_id": "66b33ed93f843a1fa88836b6",
"eventName": "rows:update",
"sheetId": "62a3188f098a6343fe0d9c1b",
"targetUrl": "https://example.com/update",
}
}
DELETE /sheets/:sheetId/hooks/:hookId
= delete an existing hook
# request (replace :sheetId and :hookId)
curl -X DELETE \
-H "Authorization: Bearer API-KEY" \
https://api.orcascan.com/v1/sheets/:sheetId/hooks/:hookId
Status Codes and Error Handling
The following HTTP status codes indicate the success or failure of a request:
Status | Message | Description |
---|---|---|
200 |
Ok | Request successful |
400 |
Bad request | Your request is missing data |
401 |
Unauthorized | You do not have permission to access this resource |
403 |
Forbidden | You do not have permission to access this resource |
404 |
Not found | The requested URL was not found |
409 |
Conflict | The item you attempted to create already exists |
500 |
Server Error | Something unexpected happened |
501 |
Not implemented | The requested action is not supported |
503 |
Service Unavailable | Exceeded maximum number of requests per second |
All HTTP errors include a JSON body structured as follows:
{
"status": 400,
"error": "Bad request",
"message": "Invalid API key"
}
API Usage Guidelines and Rate Limit
You can send a maximum of 15 requests per second, exceeding this limit will result in a HTTP 503 Service Unavailable response.
Orca Scan Barcode Scanner API FAQs
How do I upload a file?
Add a photo or attachment field to your sheet and provide the file content as a base64 string:
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer API-KEY" \
-d '{ "barcode": "12345", "photo": "base64..." }' \
https://api.orcascan.com/v1/sheets/:sheetId/rows
What file types does the photo field support?
You can upload .jpg
, .png
, .gif
, .bmp
, .webp
, .tiff
and .svg
files to a photo field.
What files types does the attachment field support?
You can upload .doc
, .docx
, .csv
, .txt
, .ppt
, .pptx
, .pdf
, .xls
, .xlsx
and .mp4
files to an attachment field.
Does the API scrape barcodes?
The Orca Scan API doesn’t scrape barcodes – instead, it provides access to barcode data that’s captured through our mobile app. Your users scan barcodes using either iOS/Android devices or professional scanning hardware, and the API lets you retrieve and manage this scanned data in your applications.
Is the API simple to use?
Yes – the Orca Scan API is a standard REST API that uses familiar HTTP requests and returns JSON responses. To get started, your users install our mobile app for barcode capture, while you use standard GET, POST, PUT, and DELETE endpoints to access the data. You’ll need an API key (included with Business subscriptions) to begin making requests.
Does the API auto-populate fields?
Yes – when barcodes are scanned through our mobile app, you can customise field types (string, integer, datetime, etc.) that automatically structure your data. The Orca Scan API gives you immediate access to this structured data, and you can use webhooks to automatically receive updates in your system whenever new scans occur.
What barcode types does the API support?
Our API supports various barcode formats, including QR codes and Code 128. QR codes are versatile 2D barcodes that can store up to 7,089 numeric or 4,296 alphanumeric characters. Code 128 is a high-density linear barcode that can encode up to 128 characters, including letters, numbers, and special characters, making it particularly useful for logistics and inventory management. Your users can scan these barcode types through our mobile app, and the API will process the data consistently.
Barcode Scanner API related questions?
As with everything at Orca Scan, our Barcode Scanner API will evolve based on your feedback. If you have any issues, suggestions, or something is not quite clear, chat with us live.