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:
- Connect internal or external systems to Orca Scan
- Add barcode tracking to your systems
- Connect Zebra, Honeywell or Datalogic device to your system
- Build tools to enrich Orca Scan data, such as analyse images
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:
- Download the Orca Scan app onto a device
- Create a new sheet
- Add fields for the data you would like to capture
- Login to the Orca Scan web app
- Open Account Settings (top right menu)
- Copy your API key
- Open the command line on your computer
- 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