Streamoid logo
API docs by Redocly

Streamoid API Docs (v2)

API Support: [email protected]

Run in Postman

OpenAPI 3.0 spec

Introduction

Our suite of headless APIs enable end to end management of your fashion store. If you have any questions, please do not hesitate to contact us at support@streamoid.com

Getting Started

In Streamoid Headless Platform, your company or organization is treated as a Workspace. Within the workspace, a store is defined as a channel for selling your products. Stores can be an eCommerce website in a specific country, a mobile app, a printed catalog, a chatbot, a 3rd party marketplace, or even physical retail locations.

Once you share your store's product feed or product images with Streamoid via our Feed API or using a CSV/XML file, we process your catalog and enable our APIs and services for your store.

Each store has a unique store_id which is automatically encoded in your access token and does not need to be specified when making API requests. Please read the section on Authentication for more information on how this works.

Authentication

auth

Streamoid's APIs use the OAuth2.0 protocol via the Refresh Token flow (part of Authorization Code flow)

Security Scheme Type: OAuth2
Flow type: authorizationCode
Authorization URL:
Token URL: /auth/refresh_token

Streamoid's REST APIs use the OAuth 2.0 protocol to authenticate and authorize calls. Follow the steps listed here to get started.

Step 1: Registering your store and getting a Refresh Token

Streamoid will register your store and provide you a Refresh Token. Please reach out to sales@streamoid.com to get started.


Step 2: Pass the Refresh Token to get a new Access Token

Call the /auth/refresh_token API to get a new Access Token.


Access Token lifetime

The Access Token is valid for 24 hours (86400 seconds), so make sure you get a new Access Token before it expires.
Call /auth/refresh_token to get a new Access Token.


Step 3: Calling an API

You can call any API included in your subscription using the generated Access Token.

Pass the access token in the header as follows:

Authorization: Bearer {access token}

You can use the same Access Token for all APIs until the token expires.

Data Centers and Region

Streamoid Headless Platform is available in multiple regions with more coming soon. There are 2 different domains for Streamoid Headless Platform APIs, and you will have to use the one that is applicable to you.

Data Center Domain Base API URI
India .com https://api.streamoid.com/
Europe .eu https://api.streamoid.eu/

The APIs on this page are hosted on the .com domain. If your organization is on a different domain, then you must replace .com with the appropriate domain for API endpoints on this page before using them.

For example, here's how you would modify the domain in an API endpoint for the .eu domain:

API endpoint for the .com domain, as available on this page:

https://api.streamoid.com/v2/trends

API endpoint after replacing the .com domain with .eu:

https://api.streamoid.eu/v2/trends

HTTP Methods

Streamoid Headless Platform APIs use appropriate HTTP commands for every action.

Method Description
GET Used for retrieving resources from the server
POST Used to create a new resource
PUT Used to insert or replace the resource.
DELETE Used to delete a resource.

Errors

Streamoid Headless Platform uses HTTP status codes to indicate success or failure of an API call. In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicate server side errors. Commonly used HTTP status codes are listed below.

Status Code Description
200 Success: The request was successfully completed.
201 Created: The request was a success and one or more resources have been created.
400 Bad request: The request cannot be performed. Usually because of malformed parameter or missing parameter.
401 Unauthorized (Invalid AuthToken): Request was rejected because of invalid AuthToken
404 Resource Not Found: The URL youʼve sent is wrong. Itʼs possible that the resource youʼve requested has been moved to another URL.
405 Method Not Found: The HTTP method that the API is calling with is not supported for this API.
429 Too many requests: Too many requests within a certain time frame. To know more about api call limits, click here.
500 Server error: Streamoid Headless Platform server encountered an error which prevents it from fulfilling the request. Although this rarely happens, we recommend you to contact us at support@streamoid.com if you receive this error.

For details about the structure and application-specific error-codes of a specific Streamoid service, consult the documentation dedicated to that service.

Pagination

Streamoid's APIs return upto 100 items by default. Use 'limit' parameter to change the number of records to be returned. Pass the parameter 'offset' to request the API to skip that many records.

For example, if the total number of records are 250,
First call: offset=0, limit=100 -> first 100 items are returned,
Second call: offset=100, limit=100 -> second 100 items are returned,
Third call: offset=200, limit=100 -> final 50 items are returned.

API Rate Limiting

API calls are limited to provide better quality of service and availability to all the users. You can send a maximum number of requests per day per store depending on your plan. Please contact support@streamoid.com if you need to know which plan you are on.

Authorization

APIs for authentication

Get new Access Token

Get a new Access Token by passing the Refresh Token.

The Refresh Token would be provided to you by Streamoid.

Pass the Access Token as 'Authorization: Bearer {access token}' to call other APIs.
It is valid for 24hrs and can be used to call all other APIs for this duration.

Authorizations:
auth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "eyJjdHkiOiJ..."
}

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Test API

Test if your access token works.
Pass the access token in the request header as 'Authorization: Bearer {access token}'

Authorizations:
auth

Responses

Request samples 

curl --request GET \
  --url https://api.streamoid.com/v2/auth/test \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
No sample

About PIM

This section will help you manage all the product information in our system, from adding SKUs to fetching collections.

Products

What is a Product

A product is a uniquely identified item in a store catalog which can be sold to customers. A product typically contains information such as an identifier (eg: SKU, Style Code, GTIN), a title, a description, images, brand name, price, sale price, and other such attributes.

Where can it be implemented?

The APIs shown in the section below help you to create new products in the Streamoid platform, modify existing product information, and fetch product information which can be used in many ways such as populating the content of a Product Details Page.

Product Model

category
required
string

Product category

available
required
number

Number of products available

title
required
string non-empty

Product title

discounted_price
required
number

Price after discount

gender
required
string

User Gender

price
required
number

Price of the product

product_url
required
string

URL of the product

currency
required
string

Currency of the product price

thumbnail_url
required
Array of strings

Thumbnail URL array

product_code
required
string

Product Code

size
required
string

Product size

{}

Add products in bulk

Enables you to add products to the system in bulk

Authorizations:
auth
Request Body schema: application/json

List of products in a fixed format. Maximum number of products to be passed is 100.

Array of objects

List of products in a fixed format. Maximum number of products to be passed is 100.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": {
    },
  • "products": [
    ]
}

Update products in bulk

Enables you to update products in bulk

Authorizations:
auth
Request Body schema: application/json

List of products in a fixed format. Maximum number of products to be passed is 100.

Array of objects

List of products in a fixed format. Maximum number of products to be passed is 100.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": {
    },
  • "products": [
    ]
}

Retrieve products in bulk

Enables you to retrieve many product details

Authorizations:
auth
query Parameters
product_id
required
Array of strings
Example: product_id=61160af04c7c4f367ea5eb26&product_id=61160afd4c7c4f367ea5eb35

your unique product identifier

pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/products?product_id=61160af04c7c4f367ea5eb26%2C61160afd4c7c4f367ea5eb35&pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category&offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{}

Retrieve products in bulk (POST)

Enables you to retrieve many product details

Authorizations:
auth
Request Body schema: application/json
product_id
Array of strings

List of product Ids. Maximum number of product Ids to be passed is 1000.

pi_response_style
string (pi_response_style)

Response style

pi_include_fields
string (pi_include_fields)

A comma-separated list of fields to include in addition to the fields specified by the 'default' response_field_group

offset
integer (offset)

Result offset. Default offset=0

limit
integer (limit)

Result limit. Default limit=100

Responses

Request samples

Content type
application/json
{
  • "product_id": [
    ],
  • "pi_response_style": "light, default, rich",
  • "pi_include_fields": "vendor_brand, meta_comprehensive_category",
  • "offset": 0,
  • "limit": 100
}

Response samples

Content type
application/json
{}

Collections (Categories)

What are Collections?

A collection is a group of products you can bundle together any which way you choose. Collections are typically shown as product listing pages and could represent apparel categories (eg: dresses), promotions (eg: fall sale) or long tail collections (eg: The Essentials Edit).

You can create and manage your collections from the dashboard. Collections can be nested up to 3 times, meaning they are arranged in a heirarchical order, so you can have a top level collection (eg: Menswear) and child collections (eg: Topwear) each with their own child collections (eg: T-shirts). From the dashboard you can also publish and unpublish collections directly to your website without involving a developer after the initial integration.

In addition to naming a collection, you can also upload a banner image and set various SEO information (page url, meta title, meta description). Once this is done, you can add products to your collections either based on a product code, or if products match a certain set of criteria you define (eg: Color = red, Sleeve Length = half).

Collections can have a minimum product threshold to be published. If many products are unavailable (out of stock) and the collection has too few products (below the threshold), it will automatically unpublish.

Where can it be used?

Collections can be used to populate the navigation menu of your website, and they can be used to manage various promotions and sales shown on the home page as well. The collections dashboard can also be used to quickly bundle products and export them for advertising feeds such as Google Shopping or Facebook/Instagram.

We typically recommend that you define top level collections depending on where on your website you will be showing your collections. For example all Menswear Categories can be placed under "Menswear" and all Womenswear Categories can be placed under "Womenswear" and Homepage Banners can be placed under "Homepage".

This way, whenever a new collection is added under "Homepage", the developers can automatically look for it under that nested collection. Collections can be empty, meaning they are only used for nesting purposes without having any products within.

Categories are used to organize products and can be nested, creating a hierarchy that resembles a tree structure. Since categories aren't necessarily tied to store navigation, you may find uses for categories both visible and invisible to customers.

Collection Model

_id
required
string

Id of the collection

name
string

Collection Name

thumbnail
string

Collection Thumbnail URL

url
string <uri>

Collection URL

object

Meta data information

status
string
Enum: "active" "inactive"

Collection Status

bannerUrl
string <uri> [ 1 .. 2083 ] characters

Collection Banner URL

displayPreference
string

Collection Display preference

autoRefresh
boolean
Default: false

Autofresh possible

minProducts
number

Minimum products in collection

sortBy
Array of strings

Sort By

object

Collection Filters

attributeFilters
Array of strings

Filters for collection attribute

heroProducts
Array of strings

Products

totalProducts
number

Total number of products

addedBy
string

Collection AddedBy

createdAt
string <date-time>

When the collection was created

updatedAt
string <date-time>

When the collection was updated

{}

Retrieve active collections

Returns the list of all active collections with a system generated unique identifier, and user defined settings such as its name, banner image, URL, meta title and meta description.

Authorizations:
auth
query Parameters
offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/collections?offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{}

Retrieve collection hierarchy

Returns the nested heirarchical order of collections as parents and children.

Authorizations:
auth

Responses

Request samples 

curl --request GET \
  --url https://api.streamoid.com/v2/collections/hierarchy \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Retrieve single collection

Returns details for a specific collection

Authorizations:
auth
path Parameters
collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

Responses

Request samples 

curl --request GET \
  --url https://api.streamoid.com/v2/collections/%7Bcollection_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{}

About Shopping Tool Management

This section will help you manage shopping experiences on your online store.

Search

What is search?

Offer an intuitive advanced search experience built for fashion. Streamoid search is designed to understand what the customer is looking for beyond mechanical parameters. Streamoid’s search turns natural language queries into relevant results.

Where can it be used?

Streamoid search offers powerful personalization and merchandising features, allowing boosts and buries for specific queries, allowing the ordering of products on pages to be controlled. A store manager can choose to further optimize search based on any attributes important to them.

You can implement this in the search box on your website, mobile site, or mobile apps.

Search Model

num_found
number

Number of records

object (Facets)

Facets model

Array of objects (Product) non-empty unique
{}

Search products

Find products matching a customer’s query. You can also use this API to apply listing page features such as sorting, pagination, and faceting (filters) to multiple query products.

Authorizations:
auth
query Parameters
q
required
string
Example: q=*

urlencoded query string

Facet Name1
string
Example: Facet Name1={"shoes": 619}

Facet name and value. Could be Category or Gender or Brand

Facet Name2
string
Example: Facet Name2={"Men": 27}

Facet name and value. Could be Category or Gender or Brand

pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/search/text/products?Facet%20Name1=%7B%22shoes%22%3A%20619%7D&Facet%20Name2=%7B%22Men%22%3A%2027%7D&q=*&pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category&offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{}

Search suggestions

Show relevant search suggestions while a customer is entering their query

Authorizations:
auth
query Parameters
query
required
string
Example: query=*

urlencoded query string

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/search/text/autosuggest?query=*' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Most popular searches

This API gives the list of most popular searches (by absolute popularity) as well as momentum-based trending searches (based on increase in popularity over a certain time frame)

Authorizations:
auth
query Parameters
start
string
Example: start=2022-09-10

date, format YYYY-MM-DD, default = this day last week

end
string
Example: end=2022-10-10

date, format YYYY-MM-DD, default = yesterday

interval
integer
Default: 1
Example: interval=1

aggregation period for queries, to consider momentum change

trending
boolean
Default: true

Includes “trending” section in response if true

popular
boolean
Default: true

Includes “popular” section in response if true

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/search/text/queries' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Search products with image url

Search for products by giving an image url.

Authorizations:
auth
query Parameters
url
string <uri> [ 1 .. 2083 ] characters
Example: url=https://cdn.pixabay.com/photo/2016/10/02/22/17/red-t-shirt-1710578_1280.jpg

Url to the image file. Either url or image_key have to be given.

image_key
string
Example: image_key=1ee2f3e26b3bcca5053af10480fe0878

Image key is returned in the initial response, and can be passed in place of the url for subsequent calls for the same image. image_key is valid for an hour after the initial call. Either url or image_key have to be given.

selected
number
Example: selected=1

Index (0 based) of the item in [detections] from the initial response, for which search is to be done.

gender
string
Example: gender=Men

Specify the gender on which search is to be done for selected product. Can be either Men or Women

category
string
Example: category=dresses

Can be any of the values in [available_categories] from the initial response

pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/search/image/products?url=https%3A%2F%2Fcdn.pixabay.com%2Fphoto%2F2016%2F10%2F02%2F22%2F17%2Fred-t-shirt-1710578_1280.jpg' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "visual_search": {
    },
  • "product_infos": {
    }
}

Search products with image upload

Search for products uploading an image

Authorizations:
auth
Request Body schema: multipart/form-data
image
string <base64>

Image file (jpg, png), multipart form data

image_key
string

Image key is returned in the initial response, and can be passed in place of the image upload for subsequent calls for the same image. image_key is valid for an hour after the initial call. Either image or image_key have to be given.

selected
string

Index (0 based) of the item in [detections] from the initial response, for which search is to be done.

gender
string

Specify the gender on which search is to be done for selected product. Can be either Men or Women

category
string

Can be any of the values in [available_categories] from the initial response

pi_response_style
string (pi_response_style)

Response style

pi_include_fields
string (pi_include_fields)

A comma-separated list of fields to include in addition to the fields specified by the 'default' response_field_group

Responses

Request samples

Content type
multipart/form-data
No sample

Response samples

Content type
application/json
{
  • "status": {
    },
  • "visual_search": {
    },
  • "product_infos": {
    }
}

Recommendations

What are recommendations?

Recommendations are suggestions generated by Streamoid AI or manually curated that help with your customers product discovery. At the end this translates to higher overall revenue, higher clicks, and increased conversions.

Where can it be used?

Streamoid offers a variety of recommendations that have been optimized for fashion out of the box. Typically, our customers implement recommendations on the Product Detail Pages and Cart/Basket Pages. In some cases, customers have even implemented these recommendations in Product Listing Pages, and as webhooks into 3rd party tools for marketing and email campaigns.

Recommendations model

products
required
Array of strings (List of product ids)
title
string (Title of the outfit)
description
string (Description of the outfit)
collage_url
string <uri> (URL of the collage of this outfit) [ 1 .. 2083 ] characters
{
  • "products": [
    ],
  • "title": "Urban Chic",
  • "description": "Some pieces are so essential, you canΓÇÖt imagine your closet without them! Take this off-white striped sweater for example. Pair it with a regular fit solid semi-formal full sleeve shirt, solid gray shorts and ankle length black almond toe boots. A basic look that still looks effortlessly fashionable? You bet!",
  • "collage_url": "http://example.com"
}

Retrieve similar products

Show products that are visually similar

Authorizations:
auth
path Parameters
product_id
required
string
Example: 334523

Id of the product

query Parameters
attribute
integer
Enum: 0 1 2
Example: attribute=1

Attribute value. 0 or 1 or 2

pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/recommendations/product/%7Bproduct_id%7D/similar?attribute=1&pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category&offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "metadata": { },
  • "similar": {
    },
  • "status": {
    },
  • "product_infos": {
    }
}

Retrieve matching products

Pair products from complementary categories

Authorizations:
auth
path Parameters
product_id
required
string
Example: 605043

Merchant store product id

query Parameters
pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/recommendations/product/%7Bproduct_id%7D/matcher?pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category&offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "complementary_products": [
    ],
  • "product_infos": {
    }
}

Retrieve outfits

Showcase outfits including a given product

Authorizations:
auth
path Parameters
product_id
required
string
Example: 6120

Merchant store product id

query Parameters
pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/recommendations/product/%7Bproduct_id%7D/outfits?pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category&offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "outfits": [
    ],
  • "product_infos": {
    }
}

Retrieve themes

Find the themes that a product can be worn in.

Authorizations:
auth
path Parameters
product_id
required
string
Example: 390206

Merchant store product id

Responses

Request samples 

curl --request GET \
  --url https://api.streamoid.com/v2/recommendations/product/%7Bproduct_id%7D/outfit-themes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Retrieve suggestions for a user collection

Suggest products customers are likely to buy given an existing set of products.

Authorizations:
auth
path Parameters
collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

query Parameters
pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/recommendations/collection/%7Bcollection_id%7D?pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category&offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

About User Management

In fashion, it is difficult to understand a customer’s style preference and manage personalization for everyone. Our system makes this easy and will allow you to manage all your customer’s information and share their shopping behavior.

Users

What are users?

Users are typically registered customers or guests in your store.

Where can it be used?

There are two types of user information we use to build a customer’s style profile and enable a personalized experience across all our shopping tools:
  1. Explicit information is provided by the user and can be immediately used
  2. Implicit information is what can be inferred from user actions. Implicit information typically takes a few months to truly reflect a user’s preferences.
Explicit information can be collected directly through a style quiz or assessment which can be shared with your customers in any format of your choosing.

User Model

userId
required
string

id of the user

static
required
string

name of the vendor

gender
string

user gender

{
  • "userId": "5f7d52885b35d2605ce1c66c",
  • "gender": "men",
  • "static": "\"selectedConcern'':{\"skintone\":\"medium_neutral\"}"
}

Retrieve all users

Retrieve a list of all users in the system.

Authorizations:
auth
query Parameters
offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/users?offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": [
    ]
}

Create user

Initialize a user in the Streamoid platform. Typically, these users will match any existing users created using other CDPs or user management platforms. We strongly recommend passing a unique DB identifier for each user.

Authorizations:
auth
Request Body schema: application/json

User details

userId
required
string

id of the user

gender
string

user gender

static
string

Any static information passed for a user

quizEntries
string

User style details

Responses

Request samples

Content type
application/json
{
  • "userId": "5f7d52885b35d2605ce1c66c",
  • "gender": "Men",
  • "static": "{\"selectedSkinTone\":\"porcelain_beige\"}",
  • "quizEntries": "{\"color\":\"red\"}"
}

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": [
    ]
}

Add user behavior

Add behavioral information on each user such as what they viewed, clicked on, add to their carts, purchased, and returned.

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

Responses

Request samples 

curl --request POST \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/behaviour \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

Retrieve user details

Retrieve information on a specific user in the system.

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

Responses

Request samples 

curl --request GET \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": [
    ]
}

Replace user details

Replace information on a specific user in the system.

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

Request Body schema: application/json

User details to be updated

gender
string

user gender

static
string

Any static data user wish to pass

quizEntries
string

User style details

Responses

Request samples

Content type
application/json
{
  • "gender": "men",
  • "static": "{\"selectedSkinTone\":\"porcelain_beige\"}",
  • "quizEntries": "{\"color\":\"blue,pink\"}"
}

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": [
    ]
}

Delete user

Remove a user from the system.

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

Responses

Request samples 

curl --request DELETE \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

User Collections

What is a user collection?

A user collection is defined as a collection of products, outfits, or images (media) and is created by your customers. It is a plug and play solution that offer your customers the ability to gather inspiration and shop collaboratively with other users.

Where can it be used?

User collections can be used in a basic form as wishlists.

User Collection Model

shareStatus
required
string
Enum: "active" "inactive"

Share Status

collaborativeStatus
required
string
Enum: "active" "inactive"

Collaborative Status

_id
required
string

ID of the collection

addedBy
required
string

Collection added by

name
required
string

Collection name

createdAt
required
string <date-time>

when the collection was created

updatedAt
required
string <date-time>

when the collection was updated

updatedBy
required
string

Collection last updated by

imageUrl
string <uri> [ 1 .. 2083 ] characters

URL of the image

shareLink
string

Share Link

notificationFrequency
string

Frequency of the notification

notificationThreshold
string

Threshold of the notification

products
Array of strings (UserCollection-Product)

Array of product Ids

object (UserCollection-Outfit)

Outfit details used with user Collection

media
Array of strings (UserCollection-Media)

Array of Media Ids

collaborativeWith
Array of strings (UserCollection-Collaborator)

Array of collaborators string

{
  • "imageUrl": "http://d1q9qhpdr6ehzh.cloudfront.net/52b58e15da0908288ad1e1237985f09e",
  • "shareStatus": "active",
  • "shareLink": "http://localhost:3000/collection/static/61160ab54c7c4f367ea5eb08",
  • "collaborativeStatus": "inactive",
  • "notificationFrequency": "1 week",
  • "notificationThreshold": "1 week",
  • "products": [
    ],
  • "outfits": {
    },
  • "media": [
    ],
  • "collaborativeWith": [
    ],
  • "_id": "611645c1a5f98d3c546ced98",
  • "addedBy": "60238d2d50759666c04d06c7",
  • "name": "Summer-2021",
  • "createdAt": "2021-08-13T10:13:21.834Z",
  • "updatedAt": "2021-08-24T07:36:10.985Z",
  • "updatedBy": "60238d2d50759666c04d06c7"
}

Retrieve user collection

Retrieve user collection

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

query Parameters
offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/users/5f7d52885b35d2605ce1c66c/collections?offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": [
    ]
}

Create user collection

Create user collection

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

Request Body schema:
name
required
string

Name of the collection

imageUrl
string <uri> [ 1 .. 2083 ] characters

Url of the image

shareStatus
string
Enum: "active" "inactive"

Sharestatus

shareLink
string <uri> [ 1 .. 2083 ] characters

Sharelink

notificationFrequency
string

Frequency of the notification

notificationThreshold
string

Threshold of the notification

collaborativeStatus
string
Enum: "active" "inactive"

Collaborative Status

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{}

Retrieve user collection details

Retrieve user collection details

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

Responses

Request samples 

curl --request GET \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": [
    ]
}

Replace user collection

Replace user collection

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

Request Body schema: application/json
name
required
string >= 0 characters

Name of the collection

imageUrl
required
string <uri> [ 1 .. 2083 ] characters

Image Url

shareStatus
required
string
Enum: "active" "inactive"

Share status

shareLink
required
string <uri> [ 1 .. 2083 ] characters

Share link

notificationFrequency
required
string

Frequency of the notification

notificationThreshold
required
string

Threshold of the notification

collaborativeStatus
required
string >= 0 characters
Enum: "active" "inactive"

Collaborative status

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete user collection

Delete user collection

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

Responses

Request samples 

curl --request DELETE \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

Retrieve products

Retrieve products

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

product_id
required
string
Example: 61160ace4c7c4f367ea5eb14

Id of the product

query Parameters
pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/products/%7Bproduct_id%7D?pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Delete product

Delete product

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

product_id
required
string
Example: 61160ace4c7c4f367ea5eb14

Id of the product

Responses

Request samples 

curl --request DELETE \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/products/%7Bproduct_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

Retrieve outfit

Retrieve outfit

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

outfit_id
required
string
Example: 6127c8e348332919124fa827

Id of the outfit

query Parameters
pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/outfits/%7Boutfit_id%7D?pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Delete outfit

Delete outfit

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

outfit_id
required
string
Example: 6127c8e348332919124fa827

Id of the outfit

Responses

Request samples 

curl --request DELETE \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/outfits/%7Boutfit_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

Retrieve media

Retrieve media

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

media_id
required
string
Example: 61160b1b4c7c4f367ea5eb70

Id of the media

Responses

Request samples 

curl --request GET \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/media/%7Bmedia_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Delete media

Delete media

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

media_id
required
string
Example: 61160b1b4c7c4f367ea5eb70

Id of the media

Responses

Request samples 

curl --request DELETE \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/media/%7Bmedia_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

Add products

Add products

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c78d

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb10

Id of the collection

Request Body schema: application/json
product_id
required
string

Id of the product

Responses

Request samples

Content type
application/json
{
  • "product_id": "61160ace4c7c4f367ea5eb14"
}

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Collaboration

What is collaboration?

Users can vote on products, outfits, and media (images) in other users collections as well as leave comments.

Users even have the option to shop collaboratively with their friends with shared carts or shared wishlists.

Where can it be used?

Collaboration can be used to power a social shopping experience on any fashion store. Users can share a collection link on their social media and receive feedback from all their friends and followers on which product to buy.

Add a collaborator

Add a collaborator

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collaborator_id
required
string
Example: 5f7d52885b35d2605ce1c66c

User id of the collaborator

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

Responses

Request samples 

curl --request POST \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/collaborators/%7Bcollaborator_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

Remove collaborator

Remove collaborator

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collaborator_id
required
string
Example: 5f7d52885b35d2605ce1c66c

User id of the collaborator

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

Responses

Request samples 

curl --request DELETE \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/collaborators/%7Bcollaborator_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

Add vote on product

Add vote on product

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

product_id
required
string
Example: 61160af04c7c4f367ea5eb26

Id of the product

Responses

Request samples 

curl --request POST \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/products/%7Bproduct_id%7D/like \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

Remove vote on product

Remove vote on product

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

product_id
required
string
Example: 61160af04c7c4f367ea5eb26

Id of the product

Responses

Request samples 

curl --request DELETE \
  --url https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/products/%7Bproduct_id%7D/like \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    }
}

Aggregate User Collections

Aggregate User Collections

Retrieve all products for a user

Retrieve all products for a user

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c78d

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb10

Id of the collection

query Parameters
pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/users/%7Buser_id%7D/collections/%7Bcollection_id%7D/products?pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category&offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "data": {
    }
}

Retrieve all outfits for a user

Retrieve all outfits for a user

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

Request Body schema: application/json
products
required
Array of strings (UserCollection-Product)

Array of product Ids

Responses

Request samples

Content type
application/json
{
  • "products": [
    ]
}

Response samples

Content type
application/json
{}

Retrieve all media for a user

Retrieve all media for a user

Authorizations:
auth
path Parameters
user_id
required
string
Example: 5f7d52885b35d2605ce1c66c

Id of the user

collection_id
required
string
Example: 61160ab54c7c4f367ea5eb08

Id of the collection

Request Body schema:
imageURL
string <uri> [ 1 .. 2083 ] characters

Pass imageUR

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{}

About UGC Management

User Generated Content allows you to manage content that your customers and potential customers have created including reviews, product ratings, and social media posts on Instagram.

Social Shopper

What is Social Shopper

Social Shopper allows you to showcase user generated content on your store, which are linked to products from your catalogue products enabling customers to discover new products.

Use the dashboard to manage this content and link Instagram posts to relevant products from your catalog.

Where can it be implemented?

The Social shopper API should be used in your store to showcase trending images, relatable models, real-world images, and to improve product discoverability.

Our clients frequently include a Social Shopper powered gallery on their websites and mobile apps:

  • A dedicated Instashop or Social Shop page that can be accessed from the explore/browse menu.

  • A section/widget on the home page

  • A section/widget on the product details page

Keep in mind that you can create multiple campaigns and can implement different campaigns in different parts of your store.

Retrieve campaigns

Returns the list of a store's published campaigns

Authorizations:
auth
query Parameters
offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/ugc/campaigns?offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "campaigns": [
    ]
}

Retrieve campaign posts

Gets information about the campaign along with the published posts and products from catalog linked to each post.

Authorizations:
auth
path Parameters
campaignId
required
string
Example: 123e4567-e89b-12d3-a456-426614174000

Id of the campaign

query Parameters
pi_response_style
string
Default: "default"
Enum: "light" "default" "rich"
Example: pi_response_style=default

Response style

pi_include_fields
string
Example: pi_include_fields=vendor_brand

A comma-separated list of fields to include in addition to the fields specified by the response_field_group passed

offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set. Default 0

limit
integer >= 1
Default: 100
Example: limit=100

The number of items to return. Default 100

Responses

Request samples 

curl --request GET \
  --url 'https://api.streamoid.com/v2/ugc/campaigns/%7BcampaignId%7D?pi_response_style=default&pi_include_fields=vendor_brand%2C%20meta_comprehensive_category&offset=0&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "status": {
    },
  • "name": "Tommy Super Sale Campaign",
  • "posts": [],
  • "product_infos": {
    }
}