Send Your Data - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Send Your Data

After formatting your data, you must deliver it to Bloomreach using one of two methods: direct API payload or SFTP file. There are two modes available to update your catalog data: PUT (full) and PATCH (delta). 

Before you begin 

Before sending your content catalog data to Bloomreach via the Catalog Data Management API, ensure that you have the following:

  • Formatted catalog data - Create your content catalog data according to the Format your Data page.
  • Transfer Key - You need an API key for authentication that is unique to your merchant account. If you do not already have it, speak to your Bloomreach representative.
  • Catalog names - Catalog names used in the Catalog Data Management API endpoints. You should have received these during the content search setup.
  • Authentication key - Required header for Catalog Data Management API requests. You should have received this during the content search setup.

Catalog Data Management API Endpoints

Environment Endpoint
Staging api-staging.connect.bloomreach.com/dataconnect/api/v1/
Production api.connect.bloomreach.com/dataconnect/api/v1/

Authentication key 

Example Authentication Key merchantname-1066facc-94fb-450e-9f9c-b66d0b155fd2
Example request header 'Authorization: Bearer merchantname-1066facc-94fb-450e-9f9c-b66d0b155fd2'

Follow the steps given below to send your content catalog data to Bloomreach:

For full updates

  1. If sending data through SFTP, upload your catalog data to your Bloomreach SFTP location.
  2. Send the Catalog Data Management PUT API request.
  3. Run the index API.

For delta updates

  1. If sending data through SFTP, upload your catalog data to your Bloomreach SFTP location.
  2. Send the Catalog Data Management PATCH API request.
  3. If order of data is important, wait for PATCH job to finish.
  4. Run the index API.
No malformed items allowed in catalog data
if there are any malformed items in your catalog data, the whole operation will be invalid and no changes will be applied.

 

Send Data as API payload

To send your catalog data directly via an API payload, you must convert all of the operations into a single JSON Patch, which is an array of catalog records. In your Catalog Data Management API request body, include the catalog records.

The max size of a single API payload is 5MB.

 

Send Data as a File Through SFTP

To send your catalog data via a file on SFTP, you must convert all of the patch operations into a file of JSONLines. Each line should only contain one patch operation. In your Catalog Data Management API request body, include the relative path to the file location.

Feed files may be sent uncompressed, or be compressed using gzip. The max size of a single API payload is 5MB.

Example API payload for sending files through SFTP

In the request body, provide the paths to your catalog files as relative paths.

[ 
  "{catalog name}/{catalog1.jsonl}", 
  "{catalog name}/{catalog2.jsonl} 
]

Example SFTP file

{"op": "add", "path": "/items/item-123", "value": {...}} //First item record
{"op": "add", "path": "/items/item-456", "value": {...}} //Second item record
{"op": "add", "path": "/items/item-789", "value": {...}} //Third item record, etc.
…

SFTP Endpoints

Environment Endpoint
Staging sftp-staging.connect.bloomreach.com (54.211.108.247, port 22)
Production sftp.connect.bloomreach.com (3.82.164.133, port 22)

sftp -i ~/path/to/private_key <merchantname>@sftp-staging.connect.bloomreach.com

Provide Bloomreach with public keys that will need access to each environment. More than one can be provided for each environment, and we advise using different public keys for staging and production.

SFTP directory structure
Any catalog data files should be sent via the SFTP location provided in the SFTP Endpoints section. We suggest organizing catalogs into their own folders to help with debugging. For example, you could create a folder called <catalog_name> and then place files related to that catalog in this folder.

File Naming
We suggest naming your catalog data files to include the catalog name, the type of modification (put/full, patch/delta) and a datetime version identifier. This will help with debugging.

For example, if your catalog is named <catalog_name>, you could name your file 20200410-090909-<catalog_name>_full.jsonl

Storage length
Files sent to the Bloomreach SFTP are stored for 30 days. Files that are older than 30 days will be automatically deleted and cleared.

 

PUT

When you PUT content into a catalog, you replace the catalog’s data entirely. In PUT mode, the only operation allowed is ADD so that data loading can be parallelized and optimized for ingestion speed. We recommend sending your data through a SFTP file when using PUT mode.

 

PATCH

When you PATCH content into a catalog, you can make partial updates to the catalog’s data. If you need to send REMOVE patch operations, you should use PATCH mode.

Note: You can index multiple PATCH operations with a single Index API call.

Sample request 

PUT

or

PATCH

https://api.connect.bloomreach.com/dataconnect/api/v1/accounts/{account_id}/catalogs/{catalog_name}/items

Headers

Authorization

Bearer {API key}

Content-Type

application/json-patch+json (Direct API payload)

application/json (SFTP)

Body

Direct API payload

(JSON Patch format)

[{
   "op":"add",
   "path":"/items/awesome_omelette_pdf",
   "value":{
      "attributes":{
         "title":"Awesome Omelette",
         "url":"https://www.homeoasis.com/pdf/awesome-omelette.pdf",   
  "medium_image_url":"https://www.homeoasis.com/images/recipe/201851/img1.jpg",
         "rating":4.7,
         "category":[
            "PDF",
            "Breakfast"
         ],
      },
      "@import":{
         "path":"/pdfs/awesome_omelette.pdf"
      }
   }
},
{ 
   "op":"add", 
   "path":"/items/awesome_omelette_video", 
   "value":{ 
      "attributes":{ 
         "title":"How to Make Our Awesome Omelette", 
         "url":"https://www.homeoasis.com/video/awesome-omelette-video.html", 
         "description":"Follow along our Awesome Omelette recipe with this companion video.", 
         "medium_image_url":"https://www.homeoasis.com/images/recipe/201851/img1.jpg", 
         "rating":4.7, 
         "video_id":HDRS2748, 
         "video_duration":5, 
         "category":[ 
            "Videos", 
            "Breakfast" 
         ], 
      }, 
   } 
}]

SFTP File

(JSONLines format,

file path must be relative)

[   
  "{catalog name}/{catalog1.jsonl}", 
  "{catalog name}/{catalog2.jsonl}" 
]
Response
{"jobId":"713aa624-1d7c-4e4a-ac23-6463e48a5fdd"

 

Next Step

After content items have been added or modified in a catalog, you must perform a follow up POST request to build and publish the index to make them viewable in the search API. If you want to configure your attributes, you should do so before publishing the index.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?