1. Home
  2. guides
  3. Barcode Scanner API

Barcode Scanner REST API

You can collect barcode scans from scanners, mobile phones, and tablets using the Orca Scan app and the Barcode Scanner REST API. Users scan barcodes in the Orca Scan app, and each scan sends structured data to your application via standard HTTP endpoints or webhooks. Unlike device specific SDKs, one API works across consumer and enterprise barcode scanners.

How to use the Barcode Scanner API

You can access the REST API 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. Use the endpoints below with your API key to access data

Barcode Scanner API endpoints

You can think of a sheet as a mini-database with its own unique configuration. The following endpoints let you manage sheets, rows, fields, 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/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": "",
    "dateTimeFormat": "(DD/MM/YYYY HH:mm:ss) 01/12/2019 13:30:00"
  }
}
PUT /sheets/:sheetId/settings = update sheet settings
curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer orca_aYUClq9tI0oxqKPfXwVHo3mVy7v" \
    -d '{ "allowPublicExport": true, "allowPublicEntry": true, "allowWebHookIn": true, "lookupUrl": "", "validationUrl": "", "webHookOutUrl": "" }' \
    https://api.orcascan.com/v1/sheets/:sheetId/settings
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 DELETE \
    -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
# by default, it returns the field keys, to return the field titles pass `?withTitles=true`.
# 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
# by default, it returns the field keys, to return the field titles pass `?withTitles=true`.
# 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)
# if a barcode is not provided in the row data, it will be auto generated
#
# add a single row.
# by default, it returns the field keys, to return the field titles pass `?withTitles=true`.
# 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"
  }
}

# if a barcode is not provided in the row data, it will be auto generated
#
# by default, updates replace the entire row with the provided data. To update only specific fields while keeping the rest of the row unchanged, 
# include ?partial=true in the URL. This ensures that only the fields you provide are modified, while all other fields remain intact.
# i.e. https://api.orcascan.com/v1/sheets/:sheetId/rows?partial=true
#
# add multiple rows (if a row already exists, it will be updated)
# 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 single row
# by default, an update replaces the entire row with the provided data. To update only specific fields while keeping the rest of the row unchanged, 
# include ?partial=true in the URL. This ensures that only the fields you provide are modified, while all other fields remain intact.
# i.e. https://api.orcascan.com/v1/sheets/:sheetId/rows/:rowId?partial=true
#
# by default, it returns the field keys, to return the field titles pass `?withTitles=true`.
#
# 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"
  }
}
PUT /sheets/:sheetId/rows = update multiple rows
# by default, updates replace the entire row with the provided data. To update only specific fields while keeping the rest of the row unchanged, 
# include ?partial=true in the URL. This ensures that only the fields you provide are modified, while all other fields remain intact.
# i.e. https://api.orcascan.com/v1/sheets/:sheetId/rows?partial=true
#
# by default, it returns the field keys, to return the field titles pass `?withTitles=true`.
#
# if a row does not exist, it will be added
# request (replace :sheetId)
curl -X PUT \
    -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"
    }
  ]
}
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/:rowId/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": "",
    }
  ]
}

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 WebHooks to be notified when data 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",
    "columns:update",
    "columns:delete",
    "columns:add",
    "sheet:clear",
    "sheet:settings:update",
    "*" // catch-all, fires for all events
  ]
}
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/hooks

// 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

Fields

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,
            "format": "text",
            "autofocus": false,
            "autoselect": false,
            "emptyOnEdit": false,
            "emptyOnScan": false,
            "hiddenWeb": false,
            "hiddenMobile": false,
            "readonlyWeb": false,
            "readonlyMobile": false,
            "useInMobileSearch": false,
            "useValueInList": true
        },
        {
            "key": "name",
            "label": "Name",
            "type": "string",
            "required": false,
            "format": "text",
            "autofocus": true,
            "autoselect": false,
            "default": "Orca",
            "emptyOnEdit": false,
            "emptyOnScan": false,
            "hiddenWeb": false,
            "hiddenMobile": false,
            "locked": true,
            "placeholder": "Enter the name here",
            "readonlyWeb": true,
            "readonlyMobile": false,
            "useInMobileSearch": false,
            "useValueInList": true
        },
        {
            "key": "location",
            "label": "Location",
            "type": "gps",
            "required": false,
            "format": "gps location (automatic)",
            "autofocus": false,
            "autoselect": false,
            "emptyOnEdit": false,
            "emptyOnScan": false,
            "hiddenWeb": false,
            "hiddenMobile": true,
            "readonlyWeb": false,
            "readonlyMobile": false,
            "useInMobileSearch": false,
            "useValueInList": false
        },
        {
            "key": "date",
            "label": "Date",
            "type": "datetime",
            "required": false,
            "format": "date time (automatic)",
            "autofocus": false,
            "autoselect": false,
            "emptyOnEdit": false,
            "emptyOnScan": false,
            "hiddenWeb": false,
            "hiddenMobile": true,
            "readonlyWeb": false,
            "readonlyMobile": false,
            "useInMobileSearch": false,
            "useValueInList": false
        }
    ]
}
POST /sheets/:sheetId/fields = add a field to the sheet
# request (replace :sheetId)
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer API-KEY" \
    -d '{ "label": "Category", "format": "drop-down list", "listOptions": ["Category 1", "Category 2"], "readonlyWeb": true }' \
    https://api.orcascan.com/v1/sheets/:sheetId/fields/

// response
{
    "data": {
        "key": "category",
        "label": "Category",
        "type": "string",
        "required": false,
        "format": "drop-down list",
        "autofocus": false,
        "autoselect": false,
        "emptyOnEdit": false,
        "emptyOnScan": false,
        "hiddenWeb": false,
        "hiddenMobile": false,
        "listOptions": [
            "Category 1",
            "Category 2"
        ],
        "readonlyWeb": true,
        "readonlyMobile": false,
        "useInMobileSearch": false,
        "useValueInList": false
    }
}
PUT /sheets/:sheetId/fields/:fieldKey = update a field in a sheet
# request (replace :sheetId & :fieldKey)
curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer API-KEY" \
    -d '{ "readonlyWeb": false, "hiddenWeb": false }' \
    https://api.orcascan.com/v1/sheets/:sheetId/fields/:fieldKey

// response
{
    "data": {
        "key": "name",
        "label": "Name",
        "type": "string",
        "required": false,
        "format": "text",
        "autofocus": true,
        "autoselect": false,
        "emptyOnEdit": false,
        "emptyOnScan": false,
        "hiddenWeb": false,
        "hiddenMobile": false,
        "readonlyWeb": false,
        "readonlyMobile": false,
        "useInMobileSearch": false,
        "useValueInList": true
    }
}
DELETE /sheets/:sheetId/fields/:fieldKey = delete a field from a sheet
# request (replace :sheetId & :fieldKey)
curl -X DELETE \
    -H "Authorization: Bearer API-KEY" \
    https://api.orcascan.com/v1/sheets/:sheetId/fields/:fieldKey

Field options:

Name Type Description
key string Internal identifier (readonly)
label string Title of the field in the app
type string Data type
format string Orca Scan Field Type
default any Default value for the field when empty
listOptions array If dropdown, options to present to users
multiSelect boolean If true, allows multiple selection
formula string Calculation for “formula” fields
currencyType string Currency code for “currency” fields, following the ISO 4217 standard (e.g. USD, EUR, GBP)
locked boolean Prevent users changing field properties
minLength integer Minimum number of characters allowed
maxLength integer Maximum number of characters allowed
minimum integer Minimum number allowed
maximum integer Maximum number allowed
placeholder string Guidance to the user when field is empty
prefix string If Unique ID, text before value
suffix string If Unique ID, text after value
length integer If Unique ID, total length of ID
required boolean User must provide a value (default: false)
autofocus boolean Auto select this field first (default: false)
autoselect boolean Highlight existing text on focus (default: false)
emptyOnEdit boolean Clear value when record edited (default: false)
emptyOnScan boolean Remove existing value on scan (default: false)
hiddenMobile boolean Hide the field on mobile (default: false)
hiddenWeb boolean Hide the field on web (default: false)
readonlyWeb boolean Prevent user input on web (default: false)
readonlyMobile boolean Prevent user input on mobile (default: false)
useInMobileSearch boolean Include value in mobile search (default: false)
useValueInList boolean Show field value in mobile list (default: false)

API Authentication

The Orca Scan REST 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.

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

API Rate Limits

You can send up to 15 requests per second. If you exceed this limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

To handle rate limits correctly:

This avoids unnecessary retries and keeps performance stable.

Is there an Open API specification?

Yes. You can find Orca Scan OpenAPI specifications here.

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 return structured data?

Yes. Barcode scans are processed at capture time and delivered through the API as structured data. Field types and formats are applied before the data reaches your application, so you can consume it directly without additional parsing.

What barcode types does the Barcode Scanner API support?

Barcodes are captured using the Orca Scan app on a device, the Orca Scan app supports common 1D and 2D barcode formats, including QR codes and Code 128.

Can I extract data from barcodes before sending it to my API?

Yes. You can use Orca Variables to extract structured data from barcodes, such as GS1 elements, before the scan data is sent to your application via the Barcode Scanner REST API.

Barcode Scanner REST API questions?

As with everything at Orca Scan, our REST API will evolve based on your feedback. If you have any issues, suggestions, or something is not quite clear, chat with us live.

Was this guide helpful?

Ready to start scanning?

Get Started Book a demo
Close Icon
Get the Orca scan app QR code

Scan the QR code to download the mobile app

Scan the QR code to open this guides on your mobile device