> For the complete documentation index, see [llms.txt](https://easyparser.gitbook.io/easyparser-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://easyparser.gitbook.io/easyparser-documentation/bulk-integration/bulk-service-request.md). # Bulk Service Request ### Overview The Bulk Service Request is the initial step in triggering large-scale data extraction jobs. By sending a single POST request, you can offload thousands of tasks to the Easyparser engine. This page details how to construct your request body, define your payload, and set up your delivery endpoint (webhook). When you call this endpoint, you are not waiting for the data; you are creating a "Job". The system validates your parameters and immediately returns a set of Result IDs. These IDs are your tracking tokens for the background process that follows. {% hint style="info" %} **Request Limits** * A single bulk request can contain up to **5,000 items**. * Each bulk request has a processing timeout of **5 minutes**, regardless of how many items it contains. * Items are also subject to your plan's Bulk per-minute limit. Items that exceed it are returned in `data.rate_limit_exceeded`, while the rest of the batch is still accepted. See [Bulk Service Response](/easyparser-documentation/bulk-integration/bulk-service-response.md) for details. {% endhint %} ### Endpoint ``` POST https://bulk.easyparser.com/v1/bulk ``` ### **Headers** | Header | Value | Description | | ------------ | ---------------- | ------------------------------- | | api-key | Your API Key | Required for authentication. | | Content-Type | application/json | Specifies the JSON data format. | ### Example Request {% tabs fullWidth="false" %} {% tab title="cURL" %} {% code overflow="wrap" %} ```javascript curl --location 'https://bulk.easyparser.com/v1/bulk' \ --header 'api-key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '[ { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "address_id" : 872 , "payload": { "urls": [ "https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1", "https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1" ], "exclude_sponsored":"true" , "sort_by":"price-asc-rank" }, "callback_url": "https://example.com/webhook" } ]' ``` {% endcode %} {% endtab %} {% tab title="Python" %} {% code overflow="wrap" %} ```python import requests import json url = "https://bulk.easyparser.com/v1/bulk" payload = json.dumps([ { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "address_id": 872, "payload": { "urls": [ "https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1", "https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1" ], "exclude_sponsored": "true", "sort_by": "price-asc-rank" }, "callback_url": "https://example.com/webhook" } ]) headers = { 'api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endcode %} {% endtab %} {% tab title="Node.js" %} {% code overflow="wrap" %} ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': 'https://bulk.easyparser.com/v1/bulk', 'headers': { 'api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify([ { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "address_id": 872, "payload": { "urls": [ "https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1", "https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1" ], "exclude_sponsored": "true", "sort_by": "price-asc-rank" }, "callback_url": "https://example.com/webhook" } ]) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endcode %} {% endtab %} {% tab title="HTTP" %} {% code overflow="wrap" %} ```http POST /v1/bulk HTTP/1.1 Host: bulk.easyparser.com api-key: YOUR_API_KEY Content-Type: application/json Content-Length: 631 [ { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "address_id" : 872 , "payload": { "urls": [ "https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1", "https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1" ], "exclude_sponsored":"true" , "sort_by":"price-asc-rank" }, "callback_url": "https://example.com/webhook" } ] ``` {% endcode %} {% endtab %} {% tab title="PHP" %} {% code overflow="wrap" %} ```php 'https://bulk.easyparser.com/v1/bulk', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'[ { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "address_id" : 872 , "payload": { "urls": [ "https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1", "https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1" ], "exclude_sponsored":"true" , "sort_by":"price-asc-rank" }, "callback_url": "https://example.com/webhook" } ]', CURLOPT_HTTPHEADER => array( 'api-key: YOUR_API_KEY', 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endcode %} {% endtab %} {% tab title="GO" %} {% code overflow="wrap" %} ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://bulk.easyparser.com/v1/bulk" method := "POST" payload := strings.NewReader(`[ { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "address_id" : 872 , "payload": { "urls": [ "https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1", "https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1" ], "exclude_sponsored":"true" , "sort_by":"price-asc-rank" }, "callback_url": "https://example.com/webhook" } ]`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("api-key", "YOUR_API_KEY") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := io.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endcode %} {% endtab %} {% tab title="C#" %} {% code overflow="wrap" %} ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Post, "https://bulk.easyparser.com/v1/bulk"); request.Headers.Add("api-key", "YOUR_API_KEY"); var json = """ [ { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "address_id": 872, "payload": { "urls": [ "https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1", "https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1" ], "exclude_sponsored": "true", "sort_by": "price-asc-rank" }, "callback_url": "https://example.com/webhook" } ] """; var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json"); request.Content = content; var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code overflow="wrap" %} ```java OkHttpClient client = new OkHttpClient().newBuilder().build(); MediaType mediaType = MediaType.parse("application/json"); String json = """ [ { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "address_id": 872, "payload": { "urls": [ "https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1", "https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1" ], "exclude_sponsored": "true", "sort_by": "price-asc-rank" }, "callback_url": "https://example.com/webhook" } ] """; RequestBody body = RequestBody.create(mediaType, json); Request request = new Request.Builder() .url("https://bulk.easyparser.com/v1/bulk") .post(body) .addHeader("api-key", "YOUR_API_KEY") .addHeader("Content-Type", "application/json") .build(); Response response = client.newCall(request).execute(); ``` {% endcode %} {% endtab %} {% endtabs %} ## **Bulk Request Structure** To ensure clarity and prevent integration errors, the Bulk Service Request parameters are divided into two distinct scopes. Understanding this hierarchy is essential: Root Level parameters define the global job configuration, while Payload Level parameters manage task-specific content and localization. ### 1. Root Level Parameters These parameters reside at the top level of your JSON request. They define the "infrastructure" of the bulk job, such as where the data is coming from and where the results should be delivered. | Parameter | Type | Required | Description | Example | | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | platform | String | Yes | The target e-commerce platform. | `AMZ` | | operation | String | Yes | The specific task to perform (e.g., SEARCH, DETAIL). | `PACKAGE_DIMENSION` | | domain | String | Yes | The marketplace domain extension. | `.com`, `.co.uk`, `.de` | | callback\_url | String | Yes | Your server endpoint that receives the completion webhook. The webhook notifies you that the result IDs are ready; it does not contain the parsed data. | `https://api.yoursite.com/webhook` | | address\_id | Integer | No | The unique ID for a specific delivery address (Optional). | 789 | ### 2. Payload Level Parameters The `payload` object is the "engine room" of your request. Unlike the Root Level, the parameters here change depending on the operation you have selected. > Developer Hint: In Bulk Integration, input keys are pluralized (e.g., `asins` instead of `asin`, `keywords` instead of `keyword`) to indicate that you are submitting an array of values for batch processing. #### 2.A Operation-Specific Input Requirements | Operation | Supported Payload Keys | Input Type | | ------------------------ | ------------------------------------------------------------- | ---------------- | | DETAIL | `asins` OR `urls` | Array of Strings | | OFFER | `asins` | Array of Strings | | SEARCH | `keywords` OR `urls` | Array of Strings | | PACKAGE\_DIMENSION | `asins` | Array of Strings | | PRODUCT\_LOOKUP | `identifiers` (Array of Strings) & `identifier_type` (String) | Array & String | | SALES\_ANALYSIS\_HISTORY | `asins` | Array of Strings | | BEST\_SELLERS\_RANK | `asins` | Array of Strings | | SELLER\_PROFILE | `seller_ids` OR `urls` | Array of Strings | | SELLER\_PRODUCTS | `seller_ids` OR `urls` | Array of Strings | | SELLER\_FEEDBACK | `seller_ids` OR `urls` | Array of Strings | #### Special Case: PRODUCT\_LOOKUP The PRODUCT\_LOOKUP operation requires two specific fields within the payload to map your codes correctly: * identifiers: An array of the codes you wish to look up (e.g., `["724382975021", "0724382975021"]`). * identifier\_type: A single string defining the type for the entire batch. Supported values: `ASIN`, `EAN`, `GTIN`, `ISBN`, `JAN`, `MINSAN`, `UPC`. #### 2.B Advanced Optional Parameters
ParameterTypeApplicable OperationsDescription / Accepted Values
languageStringALL OPERATIONSPreferred data language (e.g., en_US). Note: Incompatible with address_id.
currencyStringALL OPERATIONSISO Currency code for price data (e.g., USD, EUR, GBP).
parametersStringALL OPERATIONSCustom URL parameters to be appended to the Amazon request.
cookieStringALL OPERATIONSPass-through session cookies for localized or authenticated views.
associate_idStringDETAIL, OFFER, SEARCH, SELLER_PROFILE, SELLER_PRODUCTSYour Amazon Associate tracking ID for link generation.
sort_byStringSEARCH, SELLER_PRODUCTS

SEARCH: featured, price-asc-rank, price-desc-rank, review-rank, date-desc-rank, exact-aware-popularity-rank.


SELLER_PRODUCTS: featured-rank, exact-aware-popularity-rank.

pageIntegerSEARCH, SELLER_PRODUCTS, SELLER_FEEDBACKThe specific result page to extract (Default: 1).
exclude_sponsored BooleanSEARCHIf true, excludes sponsored (ad) products from the search results.
exclude_refinementsBooleanSEARCH, SELLER_PRODUCTSExcludes refinement options in search results.
Offer Filters(See keys in description)BooleanOFFER

Logistics: prime, free_shipping.


Condition: condition_new, condition_used_like_new, condition_used_very_good, condition_used_good, condition_used_acceptable.


Note: Multiple filters can be set to true simultaneously.

min_quantityIntegerOFFERFilters offers based on minimum order quantity.
a_plus_contentBooleanDETAILSet to true to retrieve enhanced marketing (A+) content.
history_rangeStringSALES_ANALYSIS_HISTORY , SELLER_FEEDBACKSpecifies the duration for analysis (e.g., "3").
min_ratingIntegerSELLER_FEEDBACKMinimum star rating to include in the feedback results (e.g. 1).
max_ratingIntegerSELLER_FEEDBACKMaximum star rating to include in the feedback results (e.g. 5).
{% hint style="info" %} Important Note on Parameter Scoping: To ensure your localized data is retrieved correctly, please distinguish between Root and Payload parameters: * Root Level: `platform`, `operation`, `domain`, `callback_url`, `address_id` * Payload Level: `asins`, `keywords`, `language`, `currency`, `page`, etc. *Localization settings must reside within the `payload` object to avoid default formatting.* {% endhint %} ## Operation Types and Payload Examples ### **DETAIL** The `Detail` operation is used to retrieve detailed information about a specific product on Amazon. This operation can be called using either the ASIN (Amazon Standard Identification Number) or a direct product URL. For more information, you can visit the [DETAIL](/easyparser-documentation/real-time-integration/detail.md) page. 1. **Payload** 1. **`urls`:** A list of direct Amazon product URLs. 2. `asins`: A list of Amazon ASINs to retrieve details for. {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "DETAIL", "domain": ".com", "payload": { "asins": [ "B0DQY6J9TL", "B0CF3VGQFL" ] }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} *or* {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "DETAIL", "domain": ".com", "payload": { "urls": [ "https://www.amazon.com/dp/B08CMTKNDC", "https://www.amazon.com/dp/B0C88YW1ZR" ] }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} ### **OFFER** The `Offer` operation is used to retrieve offer-level data for a specific product on Amazon. It provides a list of all available seller offers for a product, including pricing, condition, fulfillment method, and Buy Box information. For more information, you can visit the [OFFER](/easyparser-documentation/real-time-integration/offer.md) page. 1. **Payload** 1. `asins`: A list of Amazon ASINs to retrieve details for. ```json { "platform": "AMZ", "operation": "OFFER", "domain": ".de", "payload": { "asins": [ "B0CMGMCWYG", "B0CDGGFCM8" ] }, "callback_url": "https://example.com/webhook" } ``` ### SALES ANALYSIS & HISTORY The `Sales Analysis & History` operation is used to retrieve historical sales and pricing data for a product over a defined period, supporting demand forecasting and trend analysis. For more information, you can visit the [SALES ANALYSIS & HISTORY](/easyparser-documentation/real-time-integration/sales-analysis-and-history.md) page. **Payload**\ `asins`: A list of Amazon ASINs to analyze.\ `history_range`: The duration for the analysis (e.g. `"3"`). {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "SALES_ANALYSIS_HISTORY", "domain": ".com", "payload": { "asins": ["B0F25371FH", "B09QWZJDFS"], "history_range": "3" }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} ### BEST SELLERS RANK The `Best Sellers Rank` operation is used to retrieve a product's Best Sellers Rank (BSR) across its relevant Amazon categories. For more information, you can visit the [BEST SELLERS RANK](/easyparser-documentation/real-time-integration/best-sellers-rank.md) page. **Payload**\ `asins`: A list of Amazon ASINs to retrieve rank data for. {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "BEST_SELLERS_RANK", "domain": ".com", "payload": { "asins": ["B0F25371FH", "B09QWZJDFS"] }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} ### PACKAGE DIMENSION The `Package Dimension` operation is used to retrieve a product's verified shipping dimensions and weight, along with essential product metadata. It is commonly used for logistics planning and auditing Amazon fulfillment costs. For more information, you can visit the [PACKAGE DIMENSION](/easyparser-documentation/real-time-integration/package-dimension.md) page. **Payload**\ `asins`: A list of Amazon ASINs to retrieve dimension data for. {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "PACKAGE_DIMENSION", "domain": ".com", "payload": { "asins": ["B0F25371FH", "B09QWZJDFS"] }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} ### **SEARCH** The Search operation is used to perform a keyword or URL-based search on Amazon and retrieve a list of products that appear in the results. This mimics what a user would see when they type a query into Amazon's search bar or visit a search result page. For more information, you can visit the [SEARCH](/easyparser-documentation/real-time-integration/search.md) page. 1. **Payload** 1. **`urls`:** A list of Amazon search URLs. 2. `keywords`: A list of search terms to query on Amazon. Each keyword returns a list of matching products from the search results. {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "payload": { "urls": [ "https://www.amazon.ca/s?k=mouse&crid=O8PU9UY8P6WO&sprefix=mous%2Caps%2C268&ref=nb_sb_noss_2", "https://www.amazon.ca/s?k=table+tennis&crid=7QYJP4BMVUYZ&sprefix=table+tenni%2Caps%2C234&ref=nb_sb_noss_2" ] }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} *or* {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "SEARCH", "domain": ".ca", "payload": { "keywords": [ "portable charger", "winter gloves" ] }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} ### PRODUCT LOOKUP The `Product Lookup` operation is used to resolve external product codes to their matching Amazon products. You provide a batch of codes and a single identifier type that applies to the entire batch. For more information, you can visit the [PRODUCT LOOKUP](/easyparser-documentation/real-time-integration/product-lookup.md) page. **Payload**\ `identifiers`: A list of product codes to look up.\ `identifier_type`: A single string defining the code type for the whole batch (`ASIN`, `EAN`, `GTIN`, `ISBN`, `JAN`, `MINSAN`, `UPC`). {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "PRODUCT_LOOKUP", "domain": ".com", "payload": { "identifiers": ["724382975021", "0724382975021"], "identifier_type": "UPC" }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} ### SELLER PROFILE The `Seller Profile` operation is used to retrieve profile-level information about an Amazon seller, such as the legal business name, address, and feedback trends. This operation can be called using either a Seller ID or a storefront URL. For more information, you can visit the [SELLER PROFILE](/easyparser-documentation/real-time-integration/seller-profile.md) page. **Payload**\ `seller_ids`: A list of Amazon Seller IDs.\ \&#xNAN;*or*\ `urls`: A list of Amazon storefront URLs. {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "SELLER_PROFILE", "domain": ".com", "payload": { "seller_ids": ["A2L77EE7U53NWQ"] }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} ### SELLER PRODUCTS The `Seller Products` operation is used to retrieve the full product catalog of an Amazon seller, including pricing, Prime status, and rating data. This operation can be called using either a Seller ID or a storefront URL. For more information, you can visit the [SELLER PRODUCTS](/easyparser-documentation/real-time-integration/seller-products.md) page. **Payload**\ `seller_ids`: A list of Amazon Seller IDs.\ \&#xNAN;*or*\ `urls`: A list of Amazon storefront URLs. {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "SELLER_PRODUCTS", "domain": ".com", "payload": { "urls": ["https://www.amazon.com/s?me=A29DXXRE3BKYH7"] }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} ### SELLER FEEDBACK The `Seller Feedback` operation is used to retrieve a seller's feedback ratings and trends over a selected time range. This operation can be called using either a Seller ID or a storefront URL. For more information, you can visit the [SELLER FEEDBACK](/easyparser-documentation/real-time-integration/seller-feedback.md) page. **Payload**\ `seller_ids`: A list of Amazon Seller IDs.\ \&#xNAN;*or*\ `urls`: A list of Amazon storefront URLs. {% code overflow="wrap" %} ```json { "platform": "AMZ", "operation": "SELLER_FEEDBACK", "domain": ".in", "payload": { "seller_ids": ["A2L77EE7U53NWQ"], "history_range": "3", "min_rating": 1, "max_rating": 5 }, "callback_url": "https://example.com/webhook" } ``` {% endcode %} ### What Happens After You Send the Request? Once your bulk request is successfully submitted, the system will process your queries asynchronously.\ You will immediately receive a response containing metadata and a list of accepted queries with their unique IDs. {% hint style="info" %} The completion webhook sent to your `callback_url` only confirms that the result IDs are ready. It does not include the parsed data. Use each ID to retrieve the final result from the Data Service. {% endhint %} To understand the structure of this response and what each field means, proceed to the [**Bulk Service Response**](https://easyparser.gitbook.io/easyparser-documentation/~/revisions/83dvVwXnSzIuEKJPMzuI/bulk-integration/bulk-service-response) section.