1. Home
  2. guides
  3. Barcode Scanner API
Close Icon
Get the Orca scan app QR code

Scan the QR code to download the mobile app

Barcode Scanner API

The Orca Scan Barcode Scanner API simplifies adding barcode tracking to any system by eliminating the need for developers to write device specific code. Simply install the Orca Scan app on any device and connect to the Barcode Scanner API using any language - it’s one API, hundreds of devices.

What devices does Orca Scan support?

The Orca Scan barcode scanner app works with any:

TIP: start with low cost smartphones, add enterprise scanners if needed.

How to use the Barcode Scanner API

The Barcode Scanner API is a REST based API that can be accessed using any programming language. To get started:

  1. Install the Orca Scan app on an iOS or Android device
  2. Open the app and create a new sheet
  3. Customise your data capture fields
  4. Login to the Orca Scan web app
  5. Go to Account Settings and copy your API key
  6. Launch the command line on your computer
  7. Run the following curl command to list your sheets
curl -X GET "https://api.orcascan.com/v1/sheets" -H "Authorization: Bearer API_KEY"

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.

Endpoints

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

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"
}

Rate limit

You can send a maximum of 15 requests per second, exceeding this limit will result in a HTTP 503 Service Unavailable response.

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.

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.

Ready to start scanning?

Get Started Book a demo