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.

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 for details.

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

cURL

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"
    }
]'

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)

Node.js

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);
});

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"
    }
]

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '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;

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))
}

C#

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());

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();

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

Parameter	Type	Applicable Operations	Description / Accepted Values
language	String	ALL OPERATIONS	Preferred data language (e.g., en_US).
currency	String	ALL OPERATIONS	ISO Currency code for price data (e.g., USD, EUR, GBP).
parameters	String	ALL OPERATIONS	Custom URL parameters to be appended to the Amazon request.
cookie	String	ALL OPERATIONS	Pass-through session cookies for localized or authenticated views.
associate_id	String	DETAIL, OFFER, SEARCH, SELLER_PROFILE, SELLER_PRODUCTS	Your Amazon Associate tracking ID for link generation.
sort_by	String	SEARCH, 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.
page	Integer	SEARCH, SELLER_PRODUCTS, SELLER_FEEDBACK	The specific result page to extract (Default: 1).
exclude_sponsored	Boolean	SEARCH	If true, excludes sponsored (ad) products from the search results.
exclude_refinements	Boolean	SEARCH, SELLER_PRODUCTS	Excludes refinement options in search results.
Offer Filters(See keys in description)	Boolean	OFFER	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_quantity	Integer	OFFER	Filters offers based on minimum order quantity.
a_plus_content	Boolean	DETAIL	Set to true to retrieve enhanced marketing (A+) content.
history_range	String	SALES_ANALYSIS_HISTORY , SELLER_FEEDBACK	Specifies the duration for analysis (e.g., "3").
min_rating	Integer	SELLER_FEEDBACK	Minimum star rating to include in the feedback results (e.g. 1).
max_rating	Integer	SELLER_FEEDBACK	Maximum star rating to include in the feedback results (e.g. 5).

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.

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 page.

1. Payload

   1. urls: A list of direct Amazon product URLs.

   2. asins: A list of Amazon ASINs to retrieve details for.

{
  "platform": "AMZ",
  "operation": "DETAIL",
  "domain": ".com",
  "payload": {
    "asins": [
      "B0DQY6J9TL",
      "B0CF3VGQFL"
    ]
  },
  "callback_url": "https://example.com/webhook"
}

or

{
  "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"
}

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 page.

1. Payload

   1. asins: A list of Amazon ASINs to retrieve details for.

{
  "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 page.

Payload asins: A list of Amazon ASINs to analyze. history_range: The duration for the analysis (e.g. "3").

{
  "platform": "AMZ",
  "operation": "SALES_ANALYSIS_HISTORY",
  "domain": ".com",
  "payload": {
    "asins": ["B0F25371FH", "B09QWZJDFS"],
    "history_range": "3"
  },
  "callback_url": "https://example.com/webhook"
}

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 page.

Payload asins: A list of Amazon ASINs to retrieve rank data for.

{
  "platform": "AMZ",
  "operation": "BEST_SELLERS_RANK",
  "domain": ".com",
  "payload": {
    "asins": ["B0F25371FH", "B09QWZJDFS"]
  },
  "callback_url": "https://example.com/webhook"
}

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 page.

Payload asins: A list of Amazon ASINs to retrieve dimension data for.

{
  "platform": "AMZ",
  "operation": "PACKAGE_DIMENSION",
  "domain": ".com",
  "payload": {
    "asins": ["B0F25371FH", "B09QWZJDFS"]
  },
  "callback_url": "https://example.com/webhook"
}

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 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.

{
  "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"
}

or

{
  "platform": "AMZ",
  "operation": "SEARCH",
  "domain": ".ca",
  "payload": {
    "keywords": [
      "portable charger",
      "winter gloves"
    ]
  },
  "callback_url": "https://example.com/webhook"
}

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 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).

{
  "platform": "AMZ",
  "operation": "PRODUCT_LOOKUP",
  "domain": ".com",
  "payload": {
    "identifiers": ["724382975021", "0724382975021"],
    "identifier_type": "UPC"
  },
  "callback_url": "https://example.com/webhook"
}

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 page.

Payload seller_ids: A list of Amazon Seller IDs. or urls: A list of Amazon storefront URLs.

{
  "platform": "AMZ",
  "operation": "SELLER_PROFILE",
  "domain": ".com",
  "payload": {
    "seller_ids": ["A2L77EE7U53NWQ"]
  },
  "callback_url": "https://example.com/webhook"
}

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 page.

Payload seller_ids: A list of Amazon Seller IDs. or urls: A list of Amazon storefront URLs.

{
  "platform": "AMZ",
  "operation": "SELLER_PRODUCTS",
  "domain": ".com",
  "payload": {
    "urls": ["https://www.amazon.com/s?me=A29DXXRE3BKYH7"]
  },
  "callback_url": "https://example.com/webhook"
}

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 page.

Payload seller_ids: A list of Amazon Seller IDs. or urls: A list of Amazon storefront URLs.

{
  "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"
}

SIMILAR PRODUCTS

Retrieves the products similar to each ASIN in the list. For the full parameter and response reference, see the Similar Products real-time documentation.

Payload:

asins: An array of ASINs to retrieve similar products for. similar_limit (optional): The number of similar products to return per ASIN. Valid values are 10 (default), 50 and 100. Each ASIN is charged 1, 6 or 11 credits respectively (1 base credit, +5 for 50, +10 for 100).

Inline address parameters are not supported for this operation. Do not add zip_code, city, district or country_code to the payload of SIMILAR_PRODUCTS requests.

[
  {
    "platform": "AMZ",
    "operation": "SIMILAR_PRODUCTS",
    "domain": ".com",
    "payload": {
      "asins": ["B0G2V8898X"],
      "similar_limit": 50
    },
    "callback_url": "https://example.com/webhook"
  }
]

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.

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.

To understand the structure of this response and what each field means, proceed to the Bulk Service Response section.