Close Icon
Get the Orca scan app QR code

Scan the QR code to download the mobile app

Add barcode tracking to your system using a REST API

Add barcode tracking to your system using a REST API
Add barcode tracking to your system using a REST API

What is a REST API?

A RESTful API is an industry-standard, secure and efficient way for two computer systems to communicate and exchange data over the Internet. It enables business applications to seamlessly interact with other internal and third-party systems to perform various tasks, such as synchronising data.

Do I have to be a developer to use a REST API?

No. REST APIs were originally designed to be used by developers, who would write code to connect the systems. However, in recent years, tools such as Zapier make it possible for anyone to connect APIs without writing code.

What can I do with the Orca Scan REST API?

You can use the Orca Scan REST API to do things like:

How do I use the Orca Scan REST API?

You can open the command line or terminal application on your computer and use the curl commands below to test the Orca REST API. To get started:

  1. Download the Orca Scan app onto a device
  2. Create a new sheet
  3. Add fields for the data you would like to capture
  4. Login to the Orca Scan web app
  5. Open Account Settings (top right menu)
  6. Copy your API key
  7. Open the command line on your computer
  8. Enter the following to list your sheets
curl https://api.orcascan.com/v1/sheets -H "Authorization: Bearer YOUR-API-KEY"

Security

The Orca Scan REST API is secured using https and requires your API key to be sent as a HTTP Header with each request:

curl https://api.orcascan.com/v1/sheets -H "Authorization: Bearer YOUR-API-KEY"

Endpoints

Sheets

Endpoint Description
GET /sheets get a list of sheets in your account
GET /sheets/:sheetId/fields get a list of fields in a sheet
GET /sheets/:sheetId/settings get the settings of a sheet (WebHook URL etc)
PUT /sheets/:sheetId/clear clear all rows in a sheet

Rows

Endpoint Description
GET /sheets/:sheetId/rows get all rows in a sheet
GET /sheets/:sheetId/rows/:rowId get a single row from a sheet
POST /sheets/:sheetId/rows add a row to a sheet
PUT /sheets/:sheetId/rows/:rowId update a row in a sheet
DELETE /sheets/:sheetId/rows/:rowId delete a row from a sheet

Sheets

Get Sheets

Request:

curl https://api.orcascan.com/v1/sheets \
	-X GET \
	-H "Authorization: Bearer YOUR-API-KEY"

Response:

{
  "data": [
    {
      "_id": "62a3188f098a6343fe0d9c1b",
      "name": "My sheet",
      "isOwner": true,
      "canAdmin": true,
      "canUpdate": true,
      "canDelete": true,
      "canExport": true
    },
    {
      "_id": "62a31e89098a6343fe0d9c1e",
      "name": "Sheet shared with me",
      "isOwner": false,
      "canAdmin": false,
      "canUpdate": false,
      "canDelete": false,
      "canExport": false
    }
  ]
}

Get Fields

Request:

curl https://api.orcascan.com/v1/sheets/SHEET-ID/fields \
	-X GET \
	-H "Authorization: Bearer YOUR-API-KEY"

Response:

{
  "data": [
    {
      "key": "barcode",
      "label": "Barcode",
      "type": "string",
      "required": true,
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "integer",
      "required": false,
    },
    {
      "key": "date",
      "label": "Date",
      "type": "datetime",
      "required": false,
    }
  ]
}

Get Settings

Request:

curl https://api.orcascan.com/v1/sheets/SHEET-ID/settings \
	-X GET \
	-H "Authorization: Bearer YOUR-API-KEY"

Response:

{
  "data": {
    "allowPublicExport": true,
    "publicExportUrl": "https://api.orcascan.com/sheets/sJ0KYsnp-9b7Rl7i.json",
    "allowPublicEntry": false,
    "publicEntryUrl": "https://api.orcascan.com/62a3188f098a6343fe0d9c1b",
    "allowWebHookIn": false,
    "webHookInUrl": "https://api.orcascan.com/sheets/Ej6ls4lQX4Xgb-QT",
    "lookupUrl": "",
    "validationUrl": "",
    "webHookOutUrl": "",
    "secret": ""
  }
}

Clear a sheet

Request:

curl https://api.orcascan.com/v1/sheets/SHEET-ID/clear \
	-X PUT \
	-H "Authorization: Bearer YOUR-API-KEY"

Rows

Get all rows

Request:

# get all rows
curl https://api.orcascan.com/v1/sheets/SHEET-ID/rows \
		-X GET \
		-H "Authorization: Bearer YOUR-API-KEY"

# get a row by barcode
curl https://api.orcascan.com/v1/sheets/SHEET-ID/rows?barcode=BARCODE-VALUE \
		-X GET \
		-H "Authorization: Bearer YOUR-API-KEY"

Response:

{
  "data": [
    {
      "_id": "62b8abeb1a3f8d11e2ad781e",
      "barcode": "6344554293308",
      "name": "Fantastic Cotton Gloves",
      "quantity": "20",
      "description": "Sit tenetur iusto error eum.",
      "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.",
      "date": "2017-01-14T04:10:16.000Z",
      "location": "51.6993409, 0.9225196"
    }
  ]
}

Get a single row

Request:

curl https://api.orcascan.com/v1/sheets/SHEET-ID/rows/ROW-ID \
	-X GET \
	-H "Authorization: Bearer YOUR-API-KEY"

Response:

{
  "data": {
    "_id": "62a322f13a2579cd32b66c14",
    "barcode": "barcode123456",
    "name": "Hello World"
  }
}

Add a new row

Request:

curl https://api.orcascan.com/v1/sheets/SHEET-ID/rows \
	-X POST \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer YOUR-API-KEY" \
	-d '{ "barcode": "12345", "name": "Hello World"}'

Response:

{
  "data": {
    "_id": "629d313d74e4a61bf1517d3a",
    "barcode": "12345",
    "name": "Hello World"
  }
}

Update a row

Request:

curl https://api.orcascan.com/v1/sheets/SHEET-ID/rows/ROW-ID \
	-X PUT \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer YOUR-API-KEY" \
	-d '{ "barcode": "789", "name": "Hello World"}'

Response:

{
  "data": {
    "_id": "629d313d74e4a61bf1517d3a",
    "barcode": "789",
    "name": "Hello World"
  }
}

Delete a row

Request:

curl https://api.orcascan.com/v1/sheets/SHEET-ID/rows/ROW-ID \
	-X DELETE \
	-H "Authorization: Bearer YOUR-API-KEY"

What is the 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 REST API questions?

As with everything at Orca Scan, our REST API will evolve based on your feedback. So if you have any issues, or something is not quite clear, please chat with us live or drop us an email hello@orcascan.com


Ready to start scanning?