API Reference

Overview

The Social Commerce API is a REST API that provides access to various types of content and products. Content can be of any media type (images, gifs, videos) and from a mix of sources like brand editorial or user-generated content (UGC). The API provides query options for filtering, sorting, and selecting a subset of a Social Commerce brand’s content and products to power a wide variety of user experiences and data integrations.

 

For instructions on setting up engagement metrics for your API integration:
http://developers.curalate.com/guide/setup-engagement-metrics-for-api-solutions/

Use Cases

Social Commerce has a suite of self-serve tools, as well as an on-call solutions engineering team, for integrating Social Commerce on to your commerce channels. The Social Commerce API allows you to extend the use of your shoppable content through:

  • Seamless integration to your mobile apps.
  • Flexible integration of your shoppable content onto your site.
  • Easy import of your shoppable content to your data warehouse for in-house analytics.
  • Fast integration into partners, including ESPs and Ad platforms

Status

Status of all Social Commerce Applications and APIs available on our status page.

Definitions

Data Source – A data source is a scope of the brand’s content. A data source identifier is required to make requests to the /media endpoints. Examples of a data source include broad scopes, like “brand editorial” or “rights approved UGC”, or more specific scopes, like “my fanreel campaign2017”. Data sources can be filtered further using the API filter options, so it’s common to power several onsite experiences with a single data source.

Content – Content is a piece of media plus metadata. Media can be an image, gif, or video. Metadata includes information about where the content originated (e.g. Instagram username and like count) and information attributed within the Social Commerce platform (like labels and products links).

Brand Content (brand editorial content) – Brand content is content that the brand either uploaded to Social Commerce directly or posted to a Social network, which was then ingested into the Social Commerce platform automatically. This content generally comes from the Brand’s own creative department where they have full distribution rights.

User Generated Content (UGC) – UGC is content that comes from a brand’s user following. The Social Commerce platform enables moderation and distribution rights collection for this content. The API only returns UGC that has been moderated.

Product – Products link to a web page and, at a minimum, have a title and image. Generally, products represent an actual product, style, or variant from the brand’s product feed, so they have structured metadata for the product like description, category, manufacturer, sku, price, sale_price, availability, etc.

Product Feed – Some of the API request filters and response data are directly mapped to the brand’s product feed. Product feeds come in many formats and Social Commerce normalizes product feeds to a standard set of fields: title, description, category, age, gender, brand, manufacturer, sku, mpn, gtin, color, material, size, price, sale_price, feed_id, and item_grouping_id. The Google Product Feed specification describes each field.

Getting Started

In order to get started using the API, you need to acquire a data source. At this time, data sources must be obtained through support@curalate.com. In your request, please describe the type of content you want to fit that data source.

Examples data source definitions

  • Approved Content from one or more Fanreel(s)
  • Featured Content from Like2Buy store
  • All product-tagged and moderated content including Like2Buy, Fanreel, and Reveal
  • Content from Fanreels or Like2Buy stores across brands within the same account

The data source DKQGLerBTQCDXwNS can be used to get a sense of the API capabilities and is used in some of the examples below.

API Endpoints

All endpoints are accessed on https from edge.curalate.com. For example, a request to access the media for the sample data source looks like:

https://edge.curalate.com/v1/media/DKQGLerBTQCDXwNS

Endpoints are RESTful and return JSON responses. Each response includes a traceId that can be used to communicate to the support team if issues are encountered.

API console
A swagger based API console is provided here.

Pagination

The responses on endpoints that return a results lists include pagination bookmarks before and after that can be passed to subsequent requests to fetch the next page of results. These endpoints have a default page size, which can be overridden with the limit parameter.

 

GET media

The /media resource gets content for a given datasource. A media request is a GET request of the form:

https://edge.curalate.com/v1/media/:dataSourceId?filter=[filter]&sort=[sort]&limit=[limit]…

Parameters

All parameters are optional.

Name Type Description Example
filter string Filters the requested content. See options in the Media Filter section below.

No default value

 filter=productId:leather-jacket
requireProduct bool If true, only content that has at least one piece of product metadata will be returned.

Default value = false

 requireProduct=true
productMetadata string Comma separate list of fields to return from the product feed.

No default value.

 productMetadata=age,gender
locale string The locale of the returned product data. IETF language tag format (e.g. fr-FR): ISO 639 two-letter language code and ISO 3166 two-letter country code

No default value.

The range of supported locales and default locale depends on the brand’s product feed setup. If a requested locale is not available, the default is used instead.

 locale=fr-FR
sort string Sorts

  • Latest – recent content based on when it was posted to the social network or uploaded to Social Commerce.
  • Likes – content that was liked more on social
  • Optimized – new and trending content that tends to get more engagement
  • Moderation – content that was recently moderated on the Social Commerce dashboard

Default value = Latest

 sort=Latest
limit number Limiting the number of results, where limit equals the number of media you want to retrieve.

Default value = 10

 limit=10
after string Bookmark used for paging in conjunction with the limit parameter. Every request made to the API returns an after bookmark that can be used on the next request. after=6ca1a4ad-fb10-41fa-abab-78531a80531e_1487593595790
before string Bookmark used for paging in reverse.  before=6ca1a4ad-fb10-41fa-abab-78531a80531e_1487593595790

GET media item

The /media item resource returns a single content item. A media item request is a GET request of the form:

https://edge.curalate.com/v1/media/:dataSourceId/items/:itemId

The itemId is the id (UUID) of the element in the items results array in a response from the GET media endpoint.

Parameters

None

GET media top image

The /media top image resource returns a 302 redirect to an image resource. Callers must follow the redirect to get the actual image bytes. The resource returned is the top image according to the sorting rule (default is Optimized). If using HTML or CSS, the redirect will be followed and image displayed automatically. This API is most useful in environments where javascript or other code is not available like Email.

https://edge.curalate.com/v1/media/:dataSourceId/images/top

Parameters

All parameters are optional.

Name Type Description Example
filter string Filters the requested content. See options in the Media Filter section below. filter=productId:leather-jacket
offset  number  Gets the top image at the Nth offset. This enables displaying a multiple images by simply varying the offset parameter. Valid values: 0…24 1
fallbackImage string URL to an image to use as the result if no matching content is available. https://img.curalate.com/1.jpg
width  number Pixel width. Set to resize the image to the desired width.  400
height number Pixel height. Use with the width parameter to control both dimensions e.g., to create a square image. If the resulting aspect ratio differs from the original image, it will be cropped using an intelligent algorithm that preserves features in the image.  400

 

GET Instagram media

The /instagram media resource returns Instagram content for the user, identified by a token. Callers must handle the OAuth flow to Instagram, and then pass along the user’s token with the request.

https://edge.curalate.com/v1/instagram/media

Parameters

accessToken is required. All other parameters are optional.

Name Type Description Example
accessToken string The user’s Instagram token
limit  number  The number of media items to return per page. Note that the underlying Instagram API allows a max limit of 20. limit=10
before string Bookmark used for paging in reverse. before=1234567894561231236_33215652
after  string Bookmark used for paging in conjunction with the limit parameter. Every request made to the API returns an after bookmark that can be used on the next request.  after=1234567894561231236_33215652

GET Facebook images

The /facebook media resource returns Facebook images for the user, identified by a token. Callers must handle the OAuth flow to Facebook, and then pass along the user’s token with the request.

https://edge.curalate.com/v1/facebook/media

Parameters

accessToken</span”> is required. All other parameters are optional.

Name Type Description Example
accessToken string The user’s Facebook token
limit  number  The number of media items to return per page. Note that the underlying Facebook API allows a max limit of 100. limit=10
before string Bookmark used for paging in reverse. before=10152364594836729
after  string Bookmark used for paging in conjunction with the limit parameter. Every request made to the API returns an after bookmark that can be used on the next request.  after=10152364594836729

GET Facebook albums

The /facebook  album resource returns Facebook albums for the user, identified by a token. Callers must handle the OAuth flow to Facebook, and then pass along the user’s token with the request.

https://edge.curalate.com/v1/facebook/albums

Parameters

accessToken is required. All other parameters are optional.

Name Type Description Example
accessToken string The user’s Facebook token
limit  number  The number of media items to return per page. Note that the underlying Facebook API allows a max limit of 100. limit=10
before string Bookmark used for paging in reverse. before=10152364594836729
after  string Bookmark used for paging in conjunction with the limit parameter. Every request made to the API returns an after bookmark that can be used on the next request.  after=10152364594836729

GET Facebook album images

The /facebook  album media resource returns Facebook images for the user and album, identified by a token and albumId. Callers must handle the OAuth flow to Facebook, and then pass along the user’s token with the request.

https://edge.curalate.com/v1/facebook/albums/:albumId/media

Parameters

accessToken is required. All other parameters are optional.

Name Type Description Example
accessToken string The user’s Facebook token
limit  number  The number of media items to return per page. Note that the underlying Facebook API allows a max limit of 100. limit=10
before string Bookmark used for paging in reverse. before=10152364594836729
after  string Bookmark used for paging in conjunction with the limit parameter. Every request made to the API returns an after bookmark that can be used on the next request.  after=10152364594836729

POST upload bytes

The /upload  bytes resource allows callers to upload images and videos with a  multipart/form-data content type. Each uploaded file must not exceed a size of 100 MB for images and 250 MB for videos. This endpoint supports partial success scenarios. That is, the request will return successful and failed upload context.

https://edge.curalate.com/v1/upload/:dataSourceId

Parameters

None

Sample Response

POST submit media

The /upload  submit resource allows callers to to submit media for moderation to a specific Fanreel.  This endpoint supports both content that has been uploaded through the  /upload bytes route, as well as direct URLs to the media content.

https://edge.curalate.com/v1/upload/:dataSourceId/submit

Parameters

None

Body

Name Type Description Example
mediaContainerType string The container type Fanreel, Like2Buy etc.
mediaContainerId string The container Identifier qTd2wLmh etc.
displayName string The content author’s name. Shippy Squirrel
emailAddress string The content author’s email shippy@curalate.com
emailOptIn boolean Unused. Set this to false. false
media list of JSON objects 1 or more media objects. See field details below. note: Use either URL or curalateMediaId, not both. 
media.caption string Caption associated with the image. “Shippy loves Social Commerce”
media.type string Set this to Image. Image
media.url string Publicly accessible URL of the image.
media.curalateMediaId string The id returned in the result of the POST Upload Media call.

Sample Request Body

POST report media

The /media report resource allows end-users to report media in the client’s specific gallery.

    https://edge.curalate.com/v1/media/report/:dataSourceId/items/:itemId

Body

Name Type Description Example
message string Why this media is reported This makes me uncomfortable
userEmail string Who is reporting this media xyz@abc.com
sourceUrl string Where is it located on the website https://www.example.com/path/to/media

Sample Request Body

 

Media Filter

Filters are composed of one or more key-value pairs combined with boolean operators and parenthetical groupings. At this time a NOT operator isn’t available.

Each key-value pair matches content that has at least one piece of metadata that satisfies the constraint. Values are case-insensitive so key:VaLuE works the same as key:value. The filter component of the request must be URI encoded.

Filter Keys Description Example
productId Matches on any product identifier from the feed: feed_id, item_grouping_id, sku, mpn, or gtin. productId:leather-jacket
productUrl Matches on product url from the feed. The API attempts to canonicalize the URL before searching for matches to avoid mismatches due to URL variance and extra query parameters. productUrl:https://habilimentclothing.myshopify.com/products/the-deep-v-t-shirt
label Matches on labels added in the Social Commerce platform. label:homepage

label:may_2016
username Matches on social network username of the author of the original content. username:brandusername
category Matches on any full category string, partial category string, or a single component of a multi-level category string (eg. Women’s > Footwear> Boots). category:”Women’s > Footwear > Boots”

category:”Women’s > Footwear”

category:Footwear
tag Matches on ingestion source hashtags, without the # symbol tag:myhashtag
Other standard product feed fields including:

brand, manufacturer, age, gender

 Matches each product metadata field from the product feed. brand:habiliment

manufacturer:acmeltd

age:adult

gender:female
Custom product feed fields Some product feeds have custom brand specific fields. To make these accessible from the API, submit a support request. gem_stone:diamond

 

Example Filters

Example Filter Logic Encoded Filter Component
Product Details Page (PDP) – show content matching a specific product productId:leather-jacket filter=productId%3Aleather-jacket
Category Page – show content matching any products in the specified categories category:womens and (category:shoes or category:boots) filter=category%3Awomens%20and%20(category%3Ashoes%20or%20category%3Aboots)
Home Page – feature specific content on the homepage for campaign specific to a month and gender label:homepage and label:may_2016 and category:womens  filter=label%3Ahomepage%20and%20label%3Amay_2016%20and%20category%3Awomens

Response Types

The API returns a JSON document made up of several JSON objects defined in the following tables. The Required column denotes which fields are always present and which fields are optional based on the data being returned. URLs, where used, always include the protocol (http or https).

Top level response

Field Description Required
data The actual data results. Either a Media Page Data object or a single Media Item object. Yes
metadata Object with trace identifiers and diagnostic info. Yes
error Object with any error info. No
paging Object with cursors and prev/next links if applicable. No

Media Page Data

Field Description Required
items List of 0 to N media item results. Yes
totalCount Number of total results available in the query. Use the “after” paging cursor to fetch more results. Yes

Media Item

Field Description Required
id Uniquely identifies a media item. These are stable across requests and can be used in the GET Media Item API. Yes
source Source object that describes where the content originated.  Yes
labels List of 0 or more strings that represent user-defined labels added in the Social Commerce App. Yes
media Media object that gives the type and links to the underlying media. No
products List of 0 or more Product objects. Yes

Media Item Source

Field Description Required
type The social network where the content was originally posted: pinterest, facebook, instagram, twitter, tumblr. If the content did not come from a social network, it will not have info like user, link, caption, etc. Yes
postedTimestamp Epoch timestamp (seconds) when the content was originally posted to the social network.  Yes
user User object describing details of the content post author. No
user.username User’s username. No
user.link User’s profile link. No
user.image User’s profile avatar with the original, small, medium, and square image variations. No
user.followerCount User’s follower count. No
user.followingCount User’s following count. No
link Link to the post on the social network. No
caption String caption. No
commentCount Approximate number of comments the original post received on the social network. No
likeCount Approximate number of likes the original post received on the social network. No

Media Item Media

Field Description Required
type String enumeration: photo, gif, video. Yes
original The original media contents. Yes
small, medium, large, extraLarge Various sizes of the image. Not provided for gif media types. No
smallSquare, mediumSquare, largeSquare, extraLargeSquare Various square smart cropped sizes of the image. Not provided for gif media types. Smart cropping looks at the features and spatially tagged products to produce an optimal crop. More info in this blog post. Yes

Media Item Product

Field Description Required
id Uniquely identifies a product in the Social Commerce platform. It does not have meaning within the brand’s product catalog. Yes
name Name or Title of the product Yes
images List of 1 or more images for the product. Each image has different size and square smart cropped variations. Yes
link Link to the product page or other destination url. Yes
price.display Display price (value and currency) of the product. This comes directly from the brand’s product feed. No
metadata JSON object (key/value pairs) of various product metadata (e.g. productId, category, brand, manufacturer, sale_price, color, etc.). No
spatialTag JSON object with x, y, and label fields describing the spatial tag. x and y are floating point numbers defining the percent location of the tag on the original (or resized) media from the top/left corner. No

Example Response

A sample response from a GET /media API request.

 

HTTP Status Codes

 

Code Definition Recommended Action
200 Ok The operation completed successfully and yielded results. Smile.
400 Bad Request The input parameters are not valid. Check the error message returned in the body, and check the request syntax for any reported problems.
404 Not Found A requested resource was not found. The dataSourceId or itemId provided in the request URL does not exist.
500 Internal Server Error An unhandled exception has occurred. Retry the request and if this issue persists, report the issue to Social Commerce.
503 Service Unavailable API is temporarily unavailable. Retry the request and if this issue persists, report the issue to Social Commerce.

Metrics and Tracking

For instructions on setting up engagement metrics for your API integration:
http://developers.curalate.com/guide/setup-engagement-metrics-for-api-solutions/