Skip to content
/Items

Sortly API (1.0.0)

Sortly API can be used to manage items and folders in your Sortly account. Our API is organized around REST. It returns JSON-encoded responses and uses standard HTTP response codes. This API is only available on Sortly Enterprise Plan subscription.

NOTE:

  • This feature is currently under beta. Please expect minor updates in the near future.

  • Contact dev-support@sortly.com for developer support.

Authentication

Authentication to the API is performed via OAuth 2.0. Under this, you must provide your secret key as the Bearer token in the Authorization header. All requests must be made over HTTPS.

Getting Started

  • Visit: https://app.sortly.com/public-api to obtain an API access key pair for your account.

  • Use the secret key as the Bearer token.

Rate Limiting

Sortly API calls are rate limited. You can make 1000 requests per API in a 15-minute window. Rate limit information in available in the HTTP headers of the API response.

HeaderDescription
Sortly-Rate-Limit-MaxMaximum number of requests allowed within the 15-minute window
Sortly-Rate-Limit-RemainingNumber of requests remaining in the current 15-minute window
Sortly-Rate-Limit-ResetThe time at which the current rate limit window resets.(in seconds)

Once you go over the rate limit you will receive a HTTP 429 Too Many Requests error response.

Download OpenAPI description
index.json
index.yaml
Languages
Servers
Mock server
https://developer.sortly.com/_mock
https://api.sortly.co

Items

Operations

Create an Item

Request

Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
Bodyapplication/json
idnumber

ID of the instance

namestringrequired

Name of item

pricenumber

Price of an item

quantitynumber

Quantity of an item

min_quantitynumber

Minimal quantity of an item

notesstring

Item notes

parent_idstring

ID of parent folder

typestringrequired

Type of item ( folder | item )

sidstring

Sortly system ID of the item

label_urlstring

QR url OR barcode value

label_url_typestring

QR OR barcode type.

Allowed values: [ org.gs1.UPC-E, org.iso.Code39, org.iso.Code39Mod43, org.gs1.EAN-13, org.gs1.EAN-8, com.intermec.Code93, org.iso.Code128, org.iso.PDF417, org.iso.Aztec, org.iso.QRCode, org.ansi.Interleaved2of5, org.iso.DataMatrix, com.sortly.textEntry ]

label_url_extrastring

QR url OR barcode value

label_url_extra_typestring

QR OR barcode type.

Allowed values: [ org.gs1.UPC-E, org.iso.Code39, org.iso.Code39Mod43, org.gs1.EAN-13, org.gs1.EAN-8, com.intermec.Code93, org.iso.Code128, org.iso.PDF417, org.iso.Aztec, org.iso.QRCode, org.ansi.Interleaved2of5, org.iso.DataMatrix, com.sortly.textEntry ]

tagsArray of objects

List of Item tags' names

custom_attribute_valuesArray of objects

List of Custom Fields

photo_idsArray of objects

List of photo ids

photosArray of objects

Could be one of:

measured_quantityobject(MeasuredQuantity)
option_value_idsArray of objects

ID of option of attribute in Item Variant Group for Item. Required if populated item_group_id. See Item Groups

item_group_idstring

ID Item Variant Group for Item. Required if populated option_value_ids. See Item Groups

curl -i -X POST \
  https://developer.sortly.com/_mock/api/v1/items \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My New Folder",
    "type": "folder"
  }'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
dataobject
Response
application/json
{
  "id": 2,
  "name": "itemName",
  "price": 10,
  "quantity": 1,
  "min_quantity": 1,
  "notes": "newNotes",
  "type": "item",
  "parent_id": 1,
  "created_at": "2019-01-22T18:31:42",
  "updated_at": "2019-01-22T18:31:42",
  "sid": "S01QSR0001",
  "label_url": "AB123AB45",
  "label_url_type": "org.iso.Code128",
  "label_url_extra": "9780066620992",
  "label_url_extra_type": "org.gs1.EAN-13",
  "tag_names": [
    "T1",
    "T2"
  ],
  "tags": [
    { … },
    { … }
  ],
  "photos": [
    { … },
    { … }
  ],
  "custom_attribute_values": [
    { … }
  ],
  "measured_quantity": {
    "value": 1,
    "type": "weight",
    "name": "lbs",
    "scale": 4
  },
  "option_value_ids": [
    "a03faad7-5689-4c6d-aee1-f282052fad8d",
    "b527720d-19ec-478c-8a06-ac11713f47a1"
  ],
  "item_group_id": "309ec621-bcf1-4567-922f-f64a52900fff"
}

List Items

Request

Query
per_pagenumber

Page size | Defaults to 10

Example: per_page=2
pagenumber

Page number | Defaults to 1

Example: page=1
folder_idstring

Filter by parent ID | The null value means root | If folder id not provided, filter will not apply

Example: folder_id=1
includestring

Includes nested association

Example: include=custom_attributes,photos,options
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
curl -i -X GET \
  'https://developer.sortly.com/_mock/api/v1/items?per_page=2&page=1&folder_id=1&include=custom_attributes%2Cphotos%2Coptions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
dataArray of objects
metaobject
Response
application/json
{
  "data": [
    { … },
    { … }
  ],
  "meta": {
    "pagination": { … }
  }
}

Recent Items List

Request

Query
per_pagenumber

Page size | Defaults to 10

Example: per_page=2
pagenumber

Page number | Defaults to 1

Example: page=1
updated_sincenumber

Filter by updated at | If updated since is not provided, the end point functions similar to list endpoint | Number of seconds since the Epoch.

Example: updated_since=1559120004
includestring

Includes nested association

Example: include=custom_attributes,photos,options
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
curl -i -X GET \
  'https://developer.sortly.com/_mock/api/v1/items/recent?per_page=2&page=1&updated_since=1559120004&include=custom_attributes%2Cphotos%2Coptions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Body
Response
No content

Delete Item

Request

Path
item_idstringrequired

an item ID attribute

Example: 3
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
curl -i -X DELETE \
  https://developer.sortly.com/_mock/api/v1/items/3 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>'

Responses

OK

Bodyapplication/json
object
Response
application/json
{}

Fetch Item

Request

Path
item_idstringrequired

Item ID

Example: 1
Query
includestring

includes nested association

Example: include=custom_attributes,photos,options
Headers
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
Acceptstring

e.g. application/json

Example: application/json
curl -i -X GET \
  'https://developer.sortly.com/_mock/api/v1/items/1?include=custom_attributes%2Cphotos%2Coptions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>'

Responses

OK

Bodyapplication/json
dataobject
Response
application/json
{
  "data": {
    "id": 1,
    "name": "itemName",
    "price": 10,
    "quantity": 1,
    "min_quantity": 1,
    "notes": "newNotes",
    "type": "folder",
    "parent_id": 1,
    "created_at": "2019-01-22T18:31:42",
    "updated_at": "2019-01-22T18:31:42",
    "sid": "S01QSR0001",
    "label_url": "AB123AB45",
    "label_url_type": "org.iso.Code128",
    "label_url_extra": "9780066620992",
    "label_url_extra_type": "org.gs1.EAN-13",
    "tag_names": [ … ],
    "tags": [ … ],
    "photos": [ … ],
    "custom_attribute_values": [ … ],
    "option_value_ids": [ … ],
    "item_group_id": "309ec621-bcf1-4567-922f-f64a52900fff"
  }
}

Update Item

Request

Path
item_idstringrequired

Item ID

Example: 1
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
Bodyapplication/json
idnumber

ID of the instance

namestringrequired

Name of item

pricenumber

Price of an item

quantitynumber

Quantity of an item

min_quantitynumber

Minimal quantity of an item

notesstring

Item notes

parent_idstring

ID of parent folder

typestringrequired

Type of item ( folder | item )

sidstring

Sortly system ID of the item

label_urlstring

QR url OR barcode value

label_url_typestring

QR OR barcode type.

Allowed values: [ org.gs1.UPC-E, org.iso.Code39, org.iso.Code39Mod43, org.gs1.EAN-13, org.gs1.EAN-8, com.intermec.Code93, org.iso.Code128, org.iso.PDF417, org.iso.Aztec, org.iso.QRCode, org.ansi.Interleaved2of5, org.iso.DataMatrix, com.sortly.textEntry ]

label_url_extrastring

QR url OR barcode value

label_url_extra_typestring

QR OR barcode type.

Allowed values: [ org.gs1.UPC-E, org.iso.Code39, org.iso.Code39Mod43, org.gs1.EAN-13, org.gs1.EAN-8, com.intermec.Code93, org.iso.Code128, org.iso.PDF417, org.iso.Aztec, org.iso.QRCode, org.ansi.Interleaved2of5, org.iso.DataMatrix, com.sortly.textEntry ]

tagsArray of objects

List of Item tags' names

custom_attribute_valuesArray of objects

List of Custom Fields

photo_idsArray of objects

List of photo ids

photosArray of objects

Could be one of:

measured_quantityobject(MeasuredQuantity)
option_value_idsArray of objects

ID of option of attribute in Item Variant Group for Item. Required if populated item_group_id. See Item Groups

item_group_idstring

ID Item Variant Group for Item. Required if populated option_value_ids. See Item Groups

curl -i -X PUT \
  https://developer.sortly.com/_mock/api/v1/items/1 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "itemName",
    "notes": "newNotes",
    "price": 10,
    "quantity": 1,
    "min_quantity": 1,
    "parent_id": 1,
    "label_url": "AB123AB45",
    "label_url_type": "org.iso.Code128",
    "label_url_extra": "9780066620992",
    "label_url_extra_type": "org.gs1.EAN-13",
    "tags": [
      {
        "name": "Tag1"
      },
      {
        "name": "Tag2"
      }
    ],
    "custom_attribute_values": [
      {
        "custom_attribute_id": 2,
        "custom_attribute_name": "Custom Field",
        "value": "newValue"
      }
    ],
    "photo_ids": [
      1
    ],
    "option_value_ids": [
      "a03faad7-5689-4c6d-aee1-f282052fad8d",
      "b527720d-14rc-478c-8a06-ac11713f47a1"
    ]
  }'

Responses

No Content

Headers
Locationstring
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
object
Response
application/json
{}

Move an Item

Request

Path
item_idnumberrequired

Item ID

Example: 2
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
Bodyapplication/json
quantitynumberrequired

Move quantity of item

folder_idnumber

Target folder ID. If not defined then will be moved to root

leave_zero_quantityboolean

Determines wether items with zero quantity are kept or not. Default is false.

curl -i -X POST \
  https://developer.sortly.com/_mock/api/v1/items/2/move \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>' \
  -H 'Content-Type: application/json' \
  -d '{
    "quantity": 2,
    "folder_id": 1,
    "leave_zero_quantity": false
  }'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
dataobject
Response
application/json
{
  "data": {
    "id": 1,
    "name": "with photo id2",
    "price": 10,
    "quantity": 2,
    "notes": "some notes",
    "parent_id": 2,
    "sid": "S000XT3976",
    "tag_names": [ … ],
    "tags": [ … ],
    "type": "item",
    "created_at": "2019-02-14T16:49:55.006Z",
    "updated_at": "2019-02-15T11:11:11.167Z"
  }
}

Clone an Item

Request

Path
item_idnumberrequired

Item ID

Example: 2
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
Bodyapplication/json
quantitynumber

Copy item and set this quantity

folder_idnumber

Target folder ID. If not defined then will be moved to root

include_subtreeboolean

Copy with nested items or not

new_sidboolean

Copy with new SID generation or not

curl -i -X POST \
  https://developer.sortly.com/_mock/api/v1/items/2/copy \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>' \
  -H 'Content-Type: application/json' \
  -d '{
    "quantity": 2,
    "folder_id": 1,
    "include_subtree": true,
    "new_sid": true
  }'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
dataobject
Response
application/json
{
  "data": {
    "id": 3,
    "name": "itemName",
    "price": 10,
    "quantity": 1,
    "notes": "newNotes",
    "type": "folder",
    "parent_id": 1,
    "created_at": "2019-01-22T18:31:42",
    "updated_at": "2019-01-22T18:31:42",
    "sid": "S01QSR0002",
    "tag_names": [ … ],
    "tags": [ … ],
    "photos": [ … ],
    "custom_attribute_values": [ … ]
  }
}

Search Items

Request

Query
namestring

The name of the thing to search for (can be up 190 characters long)

typestring

The type of thing to search for. Allowed values are "all", "item", and "folder" with "all" being the default

item_group_idstring

ID of related Item Group. See Item Groups

folder_idsArray of arrays

Array of comma-separated numeric folder ids in which to search

Example: folder_ids=[1234, 5678]
sortArray of arrays

Array of objects with the key being the field to sort by (only name is currently supported) and the value being the direction. Acceptable sort directions are "asc" and "desc". Multiple sort objects are allowed.

Example: sort=[{ "name": "asc" }]
per_pagenumber

Page size | Defaults to 100

Example: per_page=2
pagenumber

Page number | Defaults to 1 (the same body should be passed to the next page url for pagination)

Example: page=1
includestring

Includes nested association

Example: include=custom_attributes,photos,options
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
Bodyapplication/json
curl -i -X POST \
  'https://developer.sortly.com/_mock/api/v1/items/search?name=string&type=string&item_group_id=string&folder_ids=%5B1234%2C+5678%5D&sort=%5B{+%22name%22%3A+%22asc%22+}%5D&per_page=2&page=1&include=custom_attributes%2Cphotos%2Coptions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "itemName",
    "folder_ids": [
      123456,
      7890123
    ],
    "sort": [
      {
        "name": "asc"
      }
    ]
  }'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
dataArray of objects
metaobject
Response
application/json
{
  "data": [
    { … },
    { … }
  ],
  "meta": {
    "pagination": { … }
  }
}

Item Groups

Operations

Units of Measure

Operations

Custom Fields

Operations

Alerts

Operations
© Sortly Inc.