XML API

the klevu indexing api is organized around rest http //en wikipedia org/wiki/representational state transfer our api has predictable resource oriented urls, accepts xml request bodies, returns xml encoded responses, and uses standard http response codes, authentication, and verbs every record (e g a product, category, cms page etc ) sent to klevu is maintained in a dedicated index for the respective store the indexing api is used for adding, updating or deleting records from this index the indexing api requires that you first authenticate yourself to the klevu servers as a result of this authentication, you are provided with a session id which you can use for subsequent requests to the klevu servers api key & endpoint you must have a klevu search account to use the klevu api please access the shop info section of your klevu merchant centre to retrieve the following credentials rest api key (private key) for submitting data to be indexed, eg abcdefoobar== product synchronization url for submitting data to be indexed, eg rest klevu com what is a record? with klevu a record can be a product , a category page or a cms page that you want to index and make available in search results it can also be a custom record type such as a store or recipe or something like that when you submit a record for addition or update, you must submit the record with all of its details provided a list of mandatory and optional fields is provided below when you submit a record for deletion, however, you only need to submit its unique id attributes id string string | | required this is the unique identifier of a record klevu will use this id for indexing, analytics and merchandising itemgroupid string string | | optional if your data contains a shirt in 2 different colours and 3 different sizes, you must submit 6 product variants to indicate which group each variant belongs to, specify a common value in this itemgroupid element name string string | | required this is the name or title of your record sku string string | | required this is the unique sku of the record, or stock keeping unit url string string | | required this is the url where shoppers will be taken to when the record is clicked in the klevu search results this must be a fully qualified url, beginning http // or https // note that you may receive a 400 bad request if you submit a base url that has not been configured in your klevu merchant centre currency string string | | required the currency code of the prices specified below, e g eur, usd, gbp price double double | | required the original price of your product, before any discounts this can be used as was price when used in conjunction with saleprice in the case of a non product record, 0 0 must be provided as the value permitted characters in this field are 0 to 9 (digits) and (dot) for adding a decimal point for example, 12999 00 is a valid value, however $12999 or 12,999 00 are not please specify the currency information in the separate currency element saleprice double double | | required this is the final price of your product, after all applicable discounts this can be used as 'now price' when used in conjunction with price the format of this field is the same as price startprice double double | | optional if your record has multiple variants, this field can be used to show the lowest price across all variants, for displaying "as low as £100" toprice double double | optional if your record has multiple variants, this field can be used to show the highest price across all variants, for use in conjunction with startprice to display "from £100 to £200" groupprices string string | optional this field is mostly commonly used in magento integrations for the customer group prices to be rendered on the frontend the format of this field is 1\ general 100 00 there are three colon separated values in each price grouping the first value represents the id of the group, the second is the label, and the third is the price for that group please see the xml to the right for a full example otherprices string string | optional this is an improvement over groupprices , in that the values specified here can also be used in conjunction with pricefieldsuffix to retrieve dynamic prices based on currencies and customer groups the format of this field is price usd group 1 100 00 there are two colon separated values in each price grouping the first value represents the id of the group and the second is the price for that group the id is made up of the following format price type currency code group id , with the group id being optional if you are not using currencies please see the xml to the right for a full example of the possible variations instock string string | optional this attribute indicates if your record is in stock or not provide a value of yes if in stock, and no otherwise in case if you are not submitting stock status, klevu will consider product as out of stock please configure klevu stock setting https //help klevu com/support/solutions/articles/5000871482 hide out of stock products to show out of stock products category string string | required this attribute indicates the most specific category of the record being submitted for example, if your product belongs to the following categories mobiles & accessories tablets promotions new in it is only tablets and new in that should be specified here, separated by a semicolon ;, for example tablets;new in listcategory string string | required this field contains up to three pieces of data, depending on your use case each section of the field must be separated by a double semicolon ;; record type the first part is always required, a record type you must provide one of the following values, whichever is most appropriate for your record klevu product for product records klevu category for category records klevu cms for cms pages or blog articles your type for your own custom entity, eg acme recipe category hierarchy the second part is made up of the entire hierarchies of applicable categories the record belongs to, with each category within the hierarchy separated by a single semicolon ; using the same example as in category above, the following would be submitted for this section mobiles & accessories;tablets;;promotions;new in group id the third part is optional, and only needed if you plan to use the visibilitygroupid feature in api requests to control which customer groups can see which records this is made up of a double semicolon ;; separated list of all applicable customer groups for this record, eg customer group 1;;wholesale group see the xml to the right for a full example image string string | optional this is the url of an associated image for your record this must be a fully qualified url, beginning http // or https // imagehover string string | optional this field can be used to specify an additional image for your record to be used on mouse hover the format is the same as for image shortdesc string string | optional the short description for your record this field can be used to display a smaller description of a record in the search results desc string string | optional the long description for your record this can also be configured to be considered in search results, in which case both this value and shortdesc will become searchable other string string | optional use this field to specify filterable attributes for your product, to be used as facets the value is made up of three values separated by colon , then each attribute is separated by a semicolon ; attribute code caption or label value(s) for example occassion\ occassion\ christmas,evening wear the attribute code here is a unique identifier of your attribute the attribute caption is used as the heading of your filter when displaying search results if the attribute code, caption or values contain a comma, colon or semi colon, they must be replaced with a space otherattributetoindex string string | optional the format of this element is the same as the format of the other element above the difference between the two is that other is used for displaying facets whereas otherattributetoindex is used for indexing and searching only populate this field with any attributes you want to be searchable, but not used as a facet boostingattribute string string | optional the score provided here is multiplied with the relevancy score to boost records at search time any decimal value between the range of 0 1 to 999 can be provided here provide a value greater than 1 to boost a record up the rankings to de boost or demote a record, provide a number that is greater than 0 and less than 1 rating string string | optional a score between 0 and 5 this can be used for displaying a star rating with each record, and can also be used to apply a sort order of the highest rated items rating count string string | optional use this field to specify the number of ratings given by customers for your product tags string string | optional use this field to specify any important keywords applicable for your records swatches string string | optional if your record has many variants, you can specify swatch data to be used across them you must specify the same swatch data for all variants, and the format is made up of four elements, which is repeated with a suffix of 1, 2, 3, etc for each variant variantid1 the klevu id of the variant, eg 123 abc variantcolor1 the colour of the variant base css color name or hex value variantswatchimage1 (optional) the url of the image to be displayed as the swatch itself variantimage1 the product image that this swatch represents see the xml below full example additionaldatatoreturn string string | optional if you have some data that you would like to be returned with the search response, populate that data in this field the structure can be anything you like, but we recommend json if you do not see this in your response data, please contact klevu support by submittng a support ticket requesting a session id use this call to authenticate yourself to the klevu indexing servers in the response, you will be provided with a session id which you should use for all subsequent requests to the klevu servers you will need your rest api key and product synchronization url please refer to the prerequisites https //docs klevu com/apis/data indexing#muovk section for more information tab examples url https productsynchronizationurl rest service startsession name session id method post request pathparameters queryparameters headerparameters kind required name authorization type string description your klevu rest api key eg abcdefoobar bodydataparameters formdataparameters results languages id es3bxlf4dy 6t59tiqium code ?xml version 1 0 encoding utf 8 ? n message n status success status n sessionid some session id sessionid n message language 200 customlabel selectedlanguageid es3bxlf4dy 6t59tiqium examples languages id 9xe3u 6kfgsqdg vz0fva code curl location request post http rest2 ksearchnet com rest service startsession n header authorization abcdefoobar language curl customlabel selectedlanguageid 9xe3u 6kfgsqdg vz0fva description the end point is used for obtaining session id currentnewparameter label header parameter value headerparameters adding new records you must provide each record in full, including all mandatory parameters for every record you submit prerequisites you will also need a session id , please see the section above on requesting a session id tab examples url https productsynchronizationurl rest service addrecords name add new records method post request pathparameters queryparameters headerparameters kind required name content type type string description the content type for the request please set this to application xml bodydataparameters kind required name data raw type string description the xml string for submitting record data formdataparameters results languages id gh1drpgg88hpmpjqcpg6d code ?xml version 1 0 encoding utf 8 ? n message n status success status n msg 3 records are marked for addition msg n message language 200 customlabel selectedlanguageid gh1drpgg88hpmpjqcpg6d examples languages id tqeg tazlx1uewf czpem code curl location request post https productsynchronizationurl rest service addrecords n header content type application xml n data raw ?xml version 1 0 encoding utf 8 ? n request n sessionid your session id sessionid n records n record n pairs n ! ids n pair n key id key n value 123 abc value n pair n pair n key itemgroupid key n value 123 value n pair n n ! product information n pair n key sku key n value sku 123 abc value n pair n pair n key name key n value my product name value n pair n pair n key instock key n value yes value n pair n pair n key url key n value https your website com products 123 html value n pair n pair n key image key n value https your website com images products 123 abc jpg value n pair n pair n key imagehover key n value https your website com images products hover 123 abc jpg value n pair n n ! product descriptions n pair n key shortdesc key n value my short description value n pair n pair n key desc key n value my longer description value n pair n n ! prices n pair n key currency key n value gbp value n pair n pair n key price key n value 150 00 value n pair n pair n key saleprice key n value 100 00 value n pair n pair n key startprice key n value 50 00 value n pair n pair n key toprice key n value 200 00 value n pair n pair n key otherprices key n value price gbp 150 00;price usd 200 00;saleprice gbp 100 00;saleprice usd 150 00;startprice gbp 50 00;startprice usd 100 00;toprice gbp 200 00;toprice usd 300 00;price gbp test group 1 100 00;price usd test group 1 150 00;saleprice gbp test group 1 80 00;saleprice usd test group 1 100 00;startprice gbp test group 1 30 00;startprice usd test group 1 50 00;toprice gbp test group 1 180 00;toprice usd test group 1 200 00;price gbp test group 2 90 00;price usd test group 2 140 00;saleprice gbp test group 2 70 00;saleprice usd test group 2 90 00;startprice gbp test group 2 20 00;startprice usd test group 2 40 00;toprice gbp test group 2 170 00;toprice usd test group 2 190 00 value n pair n pair n key groupprices key n value test group 1 test group 1 80 00;test group 2 test group 2 70 00 value n pair n n ! categorisation n pair n key category key n value sub category a 2;sub category b 2 value n pair n pair n key listcategory key n value klevu product;;category a;sub category a 1;sub category a 2;;category b;sub category b 1;sub category b 2;;test group 1;;test group 2 value n pair n n ! attributes n pair n key other key n value color colour red;occasion occasion christmas evening wear value n pair n pair n key otherattributetoindex key n value brand brand name nike adidas;gtin gtin 123456789 value n pair n pair n key rating key n value 3 5 value n pair n pair n key rating count key n value 10 value n pair n pair n key tags key n value keyword 1 keyword 2 value n pair n n ! swatches n pair n key variantid1 key n value 123 abc value n pair n pair n key variantcolor1 key n value red value n pair n pair n key variantswatchimage1 key n value https your website com images swatches red jpg value n pair n pair n key variantimage1 key n value https your website com images products 456 abc jpg value n pair n n pair n key variantid2 key n value 123 bcd value n pair n pair n key variantcolor2 key n value white value n pair n pair n key variantswatchimage2 key n value https your website com images swatches white jpg value n pair n pair n key variantimage2 key n value https your website com images products 123 def jpg value n pair n n ! miscellaneous n pair n key boostingattribute key n value 5 value n pair n pair n key additionaldatatoreturn key n value some arbitrary data to return value n pair n pairs n record n records n request language curl customlabel selectedlanguageid tqeg tazlx1uewf czpem description the end point is used for adding new records to index currentnewparameter label body parameter value bodydataparameters updating existing records you must provide each record in full, including all mandatory parameters for every record you submit prerequisites you will also need a session id , please see the section above on requesting a session id tab examples url https productsynchronizationurl rest service updaterecords name update existing records method post request pathparameters queryparameters headerparameters kind required name content type type string description the content type for the request please set this to application xml bodydataparameters kind required name data raw type string description the xml string for submitting record data formdataparameters results languages id gh1drpgg88hpmpjqcpg6d code ?xml version 1 0 encoding utf 8 ? n message n status success status n msg 3 records are marked for updating msg n message language 200 customlabel selectedlanguageid gh1drpgg88hpmpjqcpg6d examples languages id tqeg tazlx1uewf czpem code curl location request post https productsynchronizationurl rest service updaterecords n header content type application xml n data raw ?xml version 1 0 encoding utf 8 ? n request n sessionid your session id sessionid n records n record n pairs n ! ids n pair n key id key n value 123 abc value n pair n pair n key itemgroupid key n value 123 value n pair n n ! product information n pair n key sku key n value sku 123 abc value n pair n pair n key name key n value my product name value n pair n pair n key instock key n value yes value n pair n pair n key url key n value https your website com products 123 html value n pair n pair n key image key n value https your website com images products 123 abc jpg value n pair n pair n key imagehover key n value https your website com images products hover 123 abc jpg value n pair n n ! product descriptions n pair n key shortdesc key n value my short description value n pair n pair n key desc key n value my longer description value n pair n n ! prices n pair n key currency key n value gbp value n pair n pair n key price key n value 150 00 value n pair n pair n key saleprice key n value 100 00 value n pair n pair n key startprice key n value 50 00 value n pair n pair n key toprice key n value 200 00 value n pair n pair n key otherprices key n value price gbp 150 00;price usd 200 00;saleprice gbp 100 00;saleprice usd 150 00;startprice gbp 50 00;startprice usd 100 00;toprice gbp 200 00;toprice usd 300 00;price gbp test group 1 100 00;price usd test group 1 150 00;saleprice gbp test group 1 80 00;saleprice usd test group 1 100 00;startprice gbp test group 1 30 00;startprice usd test group 1 50 00;toprice gbp test group 1 180 00;toprice usd test group 1 200 00;price gbp test group 2 90 00;price usd test group 2 140 00;saleprice gbp test group 2 70 00;saleprice usd test group 2 90 00;startprice gbp test group 2 20 00;startprice usd test group 2 40 00;toprice gbp test group 2 170 00;toprice usd test group 2 190 00 value n pair n pair n key groupprices key n value test group 1 test group 1 80 00;test group 2 test group 2 70 00 value n pair n n ! categorisation n pair n key category key n value sub category a 2;sub category b 2 value n pair n pair n key listcategory key n value klevu product;;category a;sub category a 1;sub category a 2;;category b;sub category b 1;sub category b 2;;test group 1;;test group 2 value n pair n n ! attributes n pair n key other key n value color colour red;occasion occasion christmas evening wear value n pair n pair n key otherattributetoindex key n value brand brand name nike adidas;gtin gtin 123456789 value n pair n pair n key rating key n value 3 5 value n pair n pair n key rating count key n value 10 value n pair n pair n key tags key n value keyword 1 keyword 2 value n pair n n ! swatches n pair n key variantid1 key n value 123 abc value n pair n pair n key variantcolor1 key n value blue value n pair n pair n key variantswatchimage1 key n value https your website com images swatches blue jpg value n pair n pair n key variantimage1 key n value https your website com images products 123 abc jpg value n pair n n pair n key variantid2 key n value 123 bcd value n pair n pair n key variantcolor2 key n value white value n pair n pair n key variantswatchimage2 key n value https your website com images swatches white jpg value n pair n pair n key variantimage2 key n value https your website com images products 123 def jpg value n pair n n ! miscellaneous n pair n key boostingattribute key n value 5 value n pair n pair n key additionaldatatoreturn key n value some arbitrary data to return value n pair n pairs n record n records n request language curl customlabel selectedlanguageid tqeg tazlx1uewf czpem description the end point is used for updating existing records to index currentnewparameter label body parameter value bodydataparameters deleting existing records you must provide the unique ids of the records you wish to delete prerequisites you will also need a session id , please see the section above on requesting a session id tab examples url https productsynchronizationurl rest service deleterecords name delete existing records method post request pathparameters queryparameters headerparameters kind required name content type type string description the content type for the request please set this to application xml bodydataparameters kind required name data raw type string description the xml string for submitting record data formdataparameters results languages id gh1drpgg88hpmpjqcpg6d code ?xml version 1 0 encoding utf 8 ? n message n status success status n msg 1 record is marked for deletion msg n message language 200 customlabel selectedlanguageid gh1drpgg88hpmpjqcpg6d examples languages id tqeg tazlx1uewf czpem code curl location request post https productsynchronizationurl rest service deleterecords n header content type application xml n data raw ?xml version 1 0 encoding utf 8 ? n request n sessionid your session id sessionid n records n record n pairs n ! ids n pair n key id key n value 123 abc value n pair n pairs n record n records n request language curl customlabel selectedlanguageid tqeg tazlx1uewf czpem description the end point is used for adding new records to index currentnewparameter label body parameter value bodydataparameters