API Documentation - Data Import
Find out how brands and retailers can benefit from automated fashion e-commerce imagery
The API can be used for:
Push Events
Image Storage
Image Padding
Image Resize
Image Metadata
Data Import
The Looklet data import works by contacting an HTTP endpoint created by the customer. Looklet polls this endpoint for information about items (garments). The data import improves upon the Looklet experience in the following ways:
-
Item Creator Time Saver: Item information is automatically filled in the sidebar.
-
Look Creator Search: Search for items using custom properties.
-
Image Metadata: Custom properties that were imported can be used in Look Creator and exported together with the images as a JSON sidecar file.
HTTP Endpoint Basics
The HTTP endpoints receives the item “externalId” as a parameter. This “externalId” is the SKU of the item. It’s the barcode scanned into the Item Creator sidebar.
Example URL: https://example.com/something/something?externalId=1400099535764
The request type is GET and the response should be JSON.
Response Code
Response code “200 OK” should be used if the item was successfully found in the customer system.
Response code “404 Not Found” should be used if the item could not be found.
Any other response code will be treated as failure. This would for example mean a warning message in Item Creator and that the item information sidebar does not automatically get filled as expected.
Authentication
We support two types of auth. Basic auth (username and password) and API key header auth.
Basic Authentication
Basic auth is also known as username and password auth.
We need the following information
-
the username, for example “Looklet“
-
the password, for example “ZZGFZBH8YTLG76EYK41H“
API Header Key Authentication
API header key auth works by sending a custom http header.
We need the following information
-
the header name, for example “X-API-KEY“ or “api_key“
-
the header value, for example “ZZGFZBH8YTLG76EYK41H“
Response Example
Here is an example response from the customer http endpoint:
{
"id": "1400099535764",
"properties": {
"CustomDate1": "2018-01-20",
"CustomDate2": "2020-12-31",
"CustomNumber1": "105",
"CustomNumber2": "3.14",
"CustomBoolean1": "True",
"CustomBoolean2": "False",
"CustomString1": "Custom String Here",
"CustomString2": ""
},
"warnings": [
"A red warning message to be displayed in Item Creator."
],
"messages": [
"A green information message to be displayed in Item Creator."
],
"categoryName": "Dress",
"designerName": "Adidas",
"batchNames": [
"example-batch-1",
"example-batch-2"
],
"itemGroupNames": [
"example-item-group-1",
"example-item-group-2"
],
"preStylingItemIds": [
"1100099535764",
"2200099535764",
"3300099535764"
],
"colorLabelName": "GREEN",
"fastTrack": false,
"comment": "This comment will be placed in the text area at the bottom of the the Item Creator sidebar."
}
Optional Fields
Only “id“ and “properties“ are required. All other fields are optional. This means the minimal response looks like this:
{
"id": "1400099535764",
"properties": {
"CustomDate1": "2018-01-20",
"CustomDate2": "2020-12-31",
"CustomNumber1": "105",
"CustomNumber2": "3.14",
"CustomBoolean1": "True",
"CustomBoolean2": "False",
"CustomString1": "Custom String Here",
"CustomString2": ""
}
}
Note that only supplied fields will be changed.
So if you for example don’t supply the field “colorLabelName“ the dropdown in Item Creator will remain at the value manually selected by the studio operator.
The “properties“ field should always contains all custom properties setup for the customer. Use the empty string (““) if the property has no value in your system.
Response Fields
|
Field |
Required |
Description |
Auto Creation |
Editable After Item Creator |
|---|---|---|---|---|
|
id |
yes |
The externalId/SKU if the item. Same value as in the externalId request parameter. |
- |
- |
|
properties |
yes |
Custom properties defined by the customer. Values are always strings in the JSON. They are later interpreted as types date, number, boolean, and string. Requires setup together with Looklet. More documentation about this in the next section. |
no |
yes |
|
warnings |
no |
Custom warnings to be displayed to the studio operator in Item Creator. Appears with green text and an info icon. |
- |
no |
|
messages |
no |
Custom messages to be displayed to the studio operator in Item Creator. Appears with red text and a warning icon. |
- |
no |
|
categoryName |
no |
The name of a single item category such as “Dress“ or “Shoes“. Defined together with Looklet. Does not auto create. |
no |
no |
|
designerName |
no |
The name of the designer. |
yes |
no |
|
batchNames |
no |
The names of the batches. |
yes |
no |
|
itemGroupNames |
no |
The names of the item groups. |
yes |
no |
|
preStylingItemIds |
no |
The externalIds/SKUs of the items to use for pre styling. |
- |
no |
|
colorLabelName |
no |
"NONE", "RED", "ORANGE", "YELLOW", "GREEN", "BLUE", or "PURPLE". |
no |
no |
|
fastTrack |
no |
Use either true or false. Defaults to false for new items. Decides if the item should be prioritised higher for faster processing. |
- |
no |
|
comment |
no |
The contents of the item comment at the bottom of the item info sidebar in Look Creator. |
- |
no |
Properties
The “properties“ field requires an extra setup step. It’s used for custom customer specific properties. The properties need to be configured by Looklet before they import correctly and become searchable in the Look Creator GUI.
We support 4 different types:
|
Type |
Format |
Description |
|---|---|---|
|
Date |
“YYYY-MM-DD“ |
ISO standard date without time and zone. |
|
Number |
“105“ or “3.14“ |
Whole or decimal number with a dot. |
|
Boolean |
“True“ or “False“ |
A boolean property. |
|
String |
“arbitrary content“ |
An arbitrary text/string property. |
Remember to always pass all external properties for all items. Use ““ (the empty string) if the property has no value for the item.
The properties have no maximum length. Pretty much all characters are allowed. Newlines are for example allowed.
Value Auto Creation
The “properties” and “categoryName“ must be configured together with Looklet. For “colorLabelName” there’s a fixed set of values available. But some properties will auto create.
The auto creating properties are: "designerName", "batchNames", "itemGroupNames".
If the value does not exist it’s created automatically. The values are case insensitive, meaning “Adidas“ and “aDiDAS“ will result in the same designer. The casing used for display is set in stone the first time.
Modified Data Import
Some external properties may change over time. Perhaps you have a custom property for whether the item is in stock or not? It can be useful to avoid styling with items that are out of stock in Look Creator.
A second endpoint must be implemented by the customer for continuous updates of the custom properties. It is similar to the previous one but return a JSON array instead.
The HTTP endpoints receives an “offset” parameter. This “offset” is in milliseconds. It is the amount of milliseconds passed since the last time Looklet asked the customer endpoint. The endpoint should return only the items changed during that time frame.
Example URL: https://example.com/this/that/something?offset=2700000
The request type is GET and the response should be JSON.
Note that only properties can be altered from this endpoint. You are free to return the other fields as well, but the data will be ignored.
Example response:
[
{
"id": "ABCD-1234",
"properties": {
"CustomDate1": "2018-01-20",
"CustomDate2": "2020-12-31",
"CustomNumber1": "105",
"CustomNumber2": "3.14",
"CustomBoolean1": "True",
"CustomBoolean2": "False",
"CustomString1": "Custom String Here",
"CustomString2": ""
}
},
{
"id": "EFGH-1234",
"properties": {
"CustomDate1": "2018-01-20",
"CustomDate2": "2020-12-31",
"CustomNumber1": "105",
"CustomNumber2": "3.14",
"CustomBoolean1": "True",
"CustomBoolean2": "False",
"CustomString1": "Custom String Here",
"CustomString2": ""
}
}
]