Introduction
Welcome to the i.LEVEL Connect API. You can use our API to access i.LEVEL Connect endpoints, which can get information on various resources in the i.LEVEL Connect system. The introduction looks at some key concepts that apply to the various API calls.
The following sections detail the key resources exposed with the API. Examples are provided in JSON format. Please review the Change Log for important updates.
It is important to note that we have developed the entire i.LEVEL Connect portal using the API as the only data access method. As such there has been significant testing carried out to ensure it works.
We value feedback in order to improve the documentation and the API.
Authentication
In order to use the API it is necessary to obtain an API key. API access can be granted by Platform sponsors or by our support team allowing access to the resources required for the tasks you need to perform. Please specify which resources and methods you will be using as these will be set up based on our agreement with our Platform sponsors.
If you log into the system and go to the "Admin" section you will see an API Key that you can copy to clipboard.
When making a call such as https://yumi.ilevelconnect.co.uk/api/warehouse the developers must use Basic Auth to generate the "Authorization" header. The user should follow Basic Auth principles (https://en.wikipedia.org/wiki/Basic_access_authentication) and pass the username and the API key for authentication. You can use Postman setting up Basic Auth to test your calls before putting into production.
All API calls must be sent over https.
Scope
The system will manage the scope of the returned data to ensure that you will be returned only information relating to the user type and access defined for the API. As a result some resources may not return any data or in some cases the data will be filtered or properties restricted.
Response Details
Example of header details
{
"response": {
"page": 1,
"pageCount": 1,
"recordsSent": 1,
"recordsFound": 1,
"stock": [
{
"code": "A0000001010A"
}
]
}
}
Each response from a GET call returns the same base structure. Header details provide information about pagination and record details.
| Property | Example | Description |
|---|---|---|
| page | 1 | The current page returned for the GET request |
| pageCount | 13 | The total number of pages that would need to be parsed based on the request and PageSize specified |
| recordsSent | 100 | The number of records returned by the request |
| recordsFound | 1296 | The number of records found based on the request parameters |
Request Pagination
Due to the number of records that can be returned from any given request it is necessary to control the size of the response. This is done through pagination control. The table below shows the pagination request parameters which can be used.
| Property | Example | Description |
|---|---|---|
| page | URL/api/stock?page=2 | The page that you wish to retrieve. By default the first page will be returned. |
| pageSize | URL/api/stock?page=2&pagesize=250 | The maximum number of records you wish to return. The default is 100 and the maximum is set at 1000 |
Count
Sometimes you may simply want to check how many records might be returned by a GET request. This can be done with the count parameter.
Example count response
{
"count": 581
}
| Property | Example | Description |
|---|---|---|
| count | URL/api/stock/count?sku=a@ | Returns a count of the number of records where SKU starts with 'A'. |
Filtering
It is possible to use simple filtering on resources by passing key pair values for field names and values. Simply pass the field you wish to filter on and the value you wish to find. Please see the individual resources for details of fields which filters can be used with. For more complex queries please see Query for details. Example below is from the stock resource.
http://URL/api/stock?stock_variant.barcode=5051829215354
{
"response": {
"page": 1,
"pageCount": 1,
"recordsSent": 1,
"recordsFound": 1,
"stock": [
{
"id": "C8F0D5C87583194FB8E2DE1EF5D4170E",
"fk_warehouse": "325EACF57C0EF2429F620E85612D7694",
"fk_variant": "E8B21D73AE5BFB48B4A395CE11F9270C",
"inStock": 1,
"demand": 0,
"supply": 0,
"lastUpdate": "2020-08-05T12:27:08",
"stock_warehouse": {
"id": "325EACF57C0EF2429F620E85612D7694",
"fk_company": "7AE1E6E5FAE546499B36C013916DDEEC",
"code": "Main",
"name": "Main Warehouse",
"detail": null,
"warehouse_company": {
"__KEY": "7AE1E6E5FAE546499B36C013916DDEEC"
}
},
"stock_variant": {
"id": "E8B21D73AE5BFB48B4A395CE11F9270C",
"fk_product": "7F1F51F350490A41BE5E705C66180E34",
"code": "7042792 B",
"barcode": "5051829215354",
"colour": "Cream/Navy Broken Stripe",
"sequence": 2,
"size": "S",
"detail": {
"rrp": 36,
"price": 28,
"importFile": "7F2EE4A8A4A7704F8F823F37343E08E4"
},
"vatable": false,
"rrp": 36,
"variant_product": {
"id": "7F1F51F350490A41BE5E705C66180E34",
"fk_brand": "17076BDDE29E96478A3F1C8E711BF122",
"code": "7042",
"title": "Long skirt",
"category": "Skirts",
"description": "Long summer skirt in various colours",
"productBrand": "Tester",
"season": "AW20",
"origin": "China",
"composition": "100% Cotton",
"careInstructions": "Wash at 40\r",
"createdDate": "",
"status": "",
"detail": {
"importFile": "7F2EE4A8A4A7704F8F823F37343E08E4"
},
"commodityCode": "",
"product_brand": {
"id": "17076BDDE29E96478A3F1C8E711BF122",
"fk_company": "7AE1E6E5FAE546499B36C013916DDEEC",
"name": "i.LEVEL",
"detail": null,
"code": "ILEVEL",
"brand_company": {
"__KEY": "7AE1E6E5FAE546499B36C013916DDEEC"
}
}
}
}
}
]
}
}
| Property | Example | Description |
|---|---|---|
| count | URL/api/stock?stock_variant.barcode=5060395910013 | Returns all stock with a Barcode equal to 5051829215354. |
Ordering
Ordering returned data can be done using the order_by property in the web url.
http://URL/api/stock?order_by=stock_variant.variant_product.season
Will return all stock ordered by season.
http://URL/api/stock?order_by=stock_variant.variant_product.season;stock_variant.variant_product.season
Will return all stock ordered by season and then by colour in reverse order.
It is possible to use perform server side ordering on the returned data. Simply use the order_by keyword followed by the field you wish to order by. By default the order will be performed in alphabetic, numerical or date order dependent on the field type. If the sort order indicator is used > or < you can control the order.
Multiple order fields can be combined to carry out multi level sorting of the returned data.
Fields
The fields property can be used to spcifiy only specific properties to return. This can reduce the payload significantly in some cases and make the data returned more specific to your needs.
Will return all orders with just the primary order template plus additional variant and product data.
{
"response": {
"page": 1,
"pageCount": 1,
"recordsSent": 1,
"recordsFound": 1,
"order": [
{
"id": "788F9E86F23B0A46B458983FB1B5AA38",
"fk_brandStore": "A0E87AE771BAC84DBA994FEC70537912",
"brandOrderRef": "",
"hostOrderRef": "166774",
"hostCustOrderRef": "",
"orderDate": "2020-09-04T10:16:06",
"shipDate": "",
"sentToWH": "",
"status": "",
"carrier": "YMUK48HR",
"trackingRef": "",
"fk_warehouse": "1571945CAB99744086F9FDFC9D9332D5",
"detail": {
"hostCarrier": "UK* Standard Delivery (3 - 5 working days)",
"hostStatus": "Awaiting Fulfillment",
"customerMessage": "",
"net": 52.455,
"gross": 62.95,
"vat": 7.16,
"shippingGross": 2.95,
"shippingTax": 0.49
},
"shipAddress": {
"id": 166670,
"title": "Mrs",
"forename": "Shirley",
"surname": "Johnson",
"company": "",
"line1": "12 Windy Avenue",
"line2": "Pitturbury",
"town": "Beltchworth",
"county": "",
"postcode": "KL2 9PL",
"country": "United Kingdom",
"countryCode": "GB",
"phone": "",
"email": "shirley.johnson@email.com"
},
"billAddress": {
"forename": "Shirley",
"surname": "Johnson",
"company": "",
"line1": "12 Windy Avenue",
"line2": "Pitturbury",
"town": "Beltchworth",
"county": "",
"postcode": "KL2 9PL",
"country": "United Kingdom",
"countryCode": "GB",
"phone": "",
"email": "shirley.johnson@email.com"
},
"deliveryDate": "",
"order_brandStore": {
"id": "A0E87AE771BAC84DBA994FEC70537912",
"fk_brand": "252DF4B7194C8E4599CB0430920AFB5D",
"fk_store": "5AEE4DB4C520B740ABA582528E1E8ABB",
"fk_warehouse": "1571945CAB99744086F9FDFC9D9332D5",
"detail": {
"stockType": "inStock",
"adjustType": "Absolute",
"adjustValue": 0
},
"brandStore_store": {
"__KEY": "5AEE4DB4C520B740ABA582528E1E8ABB"
},
"brandStore_brand": {
"__KEY": "252DF4B7194C8E4599CB0430920AFB5D"
},
"brandStore_warehouse": {
"__KEY": "1571945CAB99744086F9FDFC9D9332D5"
}
},
"order_orderItem": [
{
"id": "C0458E1496D21B499A3DCAE799A2DC87",
"fk_order": "788F9E86F23B0A46B458983FB1B5AA38",
"fk_variant": "E3DDB440D1E0554D957B029B3F58D361",
"orderQty": 1,
"itemPrice": 49.995,
"lineNet": 49.995,
"lineTax": 6.67,
"lineGross": 60,
"currency": "",
"shipQty": 0,
"returnQty": 0,
"detail": {
"gift": "N"
},
"status": "ACC",
"hostItemRef": "338510",
"returnDate": "",
"orderItem_order": {
"__KEY": "788F9E86F23B0A46B458983FB1B5AA38"
},
"orderItem_variant": {
"barcode": "5052011764155",
"colour": "Tan",
"size": "12",
"vatable": false,
"variant_product": {
"title": "Button Through Coat With Check Print Lin"
}
}
}
]
}
]
}
}
Using the "fields" key word you can specify which fields and related entities that you wish to return from the resource. Some resources will also return mandatory fields. By default a defined template is reurned. using fields will only return the specified fields. To return the base template plus additional field relations you can pass * as one of the field values. In this way you can extend the base model without having to type all of the required fields.
Exclude
The exclude property allows you to exclude properties and entity relations from the returned data.
Will return all brands with the specified fields ommitted.
{
"response": {
"page": 1,
"pageCount": 1,
"recordsSent": 1,
"recordsFound": 1,
"brand": [
{
"id": "17076BDDE29E96478A3F1C8E711BF122",
"name": "i.LEVEL",
"code": "ILEVEL"
}
]
}
}
Using the "exclude" key word you can exclude fields and related resources from the returned data. Some resources may ignore a call to exclude mandatory fields. Exclude will also support the @ wildcard to exclude a group of fields with a similar name pattern.
Query
Sometimes simple filtering is not sufficient to return complex selection requirements. In these cases you can use the request query object to carry out more complex queries on the resource. The example code finds all stock items where the value of sell_price1 is less than or equal to 12 and the size is equal to "S".
http://URL/api/stock with request containing a query object array
{
"query": [
{
"field": "sell_price1",
"operator": "<=",
"value": "12"
},
{
"conjunction": "&",
"field": "size",
"operator": "=",
"value": "s"
}
]
}
The query object can be used in conjunction with filtering but be aware that the query object will be applied first and then any filtering will be carried out on the subsequent selection.
| Property | Example | Description |
|---|---|---|
| field | size | Should be any valid field in the resource model. |
| operator | = | Valid values are =, #, <=, >=, >, < |
| value | "S" | Values should be consistent with the data type of the field you are searching in. Text values are case insensitive. Dates should be in the format 2017-06-27. Booleans should be expressed as True or False. |
| conjunction | & | Valid values are '&' = AND, '|' = OR and '#' = EXCEPT. |
Query Selection
While our developers were working on a project using the REST services they realised that sometimes more complex queries are more easily broken up by doing a query and then a further query on th resulting selection. This can be achieved by passing queryselection in the same way as query but as a seperate array of arguments.
http://URL/api/stock with request containing a query object array and a queryselection array
{
"query": [
{
"conjunction": "&",
"field": "size",
"operator": "=",
"value": "s"
},
{
"conjunction": "|",
"field": "size",
"operator": "=",
"value": "m"
}
],
"queryselection": [
{
"field": "sell_price1",
"operator": "<=",
"value": "12"
}
]
}
The queryselection object will be performed after any query and before any filters.
| Property | Example | Description |
|---|---|---|
| field | size | Should be any valid field in the resource model. |
| operator | = | Valid values are =, #, <=, >=, >, < |
| value | "S" | Values should be consistent with the data type of the field you are searching in. Text values are case insensitive. Dates should be in the format 2020-06-27. Booleans should be expressed as True or False. |
| conjunction | & | Valid values are '&' = AND, '|' = OR and '#' = EXCEPT. |
Query With Array
The query with array object allows for the passing of a field and an array of values. This will return a selection that matches the elements of the arrays.
http://URL/api/stock with request containing a querywitharray
{
"querywitharray": {
"field": "stock_variant.barcode",
"values": [
"5052011764155",
"5052011764168"
]
}
}
The querywitharray should not be used in conjunction with the query object but can be used before either the queryselection or queryselectionwitharray objects.
| Property | Example | Description |
|---|---|---|
| field | store_code | Should be any valid field in the resource model. |
| operator | = | Valid values are =, #, <=, >=, >, < |
| values | [] | Array of values should be consistent with the data type of the field you are searching in. Text values are case insensitive. Dates should be in the format 2017-06-27. Booleans should be expressed as True or False. |
Query Selection With Array
The query selection with array object allows for the passing of a field and an array of values. This will return a selection that matches the elements of the arrays.
http://URL/api/stock with request containing a queryselectionwitharray
{
"queryselectionwitharray": {
"field": "stock_variant.barcode",
"values": [
"5052011764155",
"5052011764168"
]
}
}
The queryselectionwitharray should be used sfter the query or querywitharray objects and can be used in conjunction with the queryselection object but can be used before either the queryselection or queryselectionwitharray objects. The queryselectionwitharray object will be performed after any query and before any filters.
| Property | Example | Description |
|---|---|---|
| field | store_code | Should be any valid field in the resource model. |
| operator | = | Valid values are =, #, <=, >=, >, < |
| values | [] | Array of values should be consistent with the data type of the field you are searching in. Text values are case insensitive. Dates should be in the format 2017-06-27. Booleans should be expressed as True or False. |
Query using POST
http://URL/api/stock/query pass queryObject as the request body. If using POST specify the additional query parameter.
When testing the REST API with jQuery and ajax it became apparent that some environments restrict the sending of a body with a GET request. Following this we went through various steps to understand how to allow the query functionality whilst keeping our rules simple. Looking at other environments they seem to have got round the restriction by using a POST. Whilst this is not elegant it does work.
OPTION 1 - USE GET with BODY (if allowed from your environment) http://URL/api/stock pass queryObject as the body defined as one of the above object formats.
OPTION 2 - USE POST method http://URL/api/stock/query where query is passed as an additional parameter similar to how count works.
In this usage the client can send a body payload because POST is used but the server will treat it like a GET and process the request as normal using the request body.
Q. Why can I not use get and just pass a query key pair parameter with the URL? A. We did consider this as an option but quickly hit the limitations of the text which can be sent as part of the URL.