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

### Endpoint

```
POST https://bulk.easyparser.com/v1/bulk
```

### **Headers** <a href="#headerlar" id="headerlar"></a>

| Header       | Value            | Description                     |
| ------------ | ---------------- | ------------------------------- |
| api-key      | Your API Key     | Required for authentication.    |
| Content-Type | application/json | Specifies the JSON data format. |

### Example Request&#x20;

{% 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
<?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;

```

{% 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 content = new StringContent("[\n    {\n        \"platform\": \"AMZ\",\n        \"operation\": \"SEARCH\",\n        \"domain\": \".ca\",  \"address_id\": \872\"\n        \"payload\": {\n            \"urls\": [\n                \"https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1\",\n                \"https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1\"\n            ],\n    \"exclude_sponsored\": \"true\",\n            \"sort_by\": \"price-asc-rank\"\n        },\n        \"callback_url\": \"https://example.com/webhook\"\n    }\n]", null, "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");
RequestBody body = RequestBody.create(mediaType, "[\n    {\n        \"platform\": \"AMZ\",\n        \"operation\": \"SEARCH\",\n        \"domain\": \".ca\",\n  \"address_id\": \872       \"payload\": {\n            \"urls\": [\n                \"https://www.amazon.ca/s?k=electronics&crid=1CINN2KWI7D8L&sprefix=electronics%2Caps%2C120&ref=nb_sb_noss_1\",\n                \"https://www.amazon.ca/s?k=smartphone&crid=1IX1CAAXNGZHH&sprefix=smartphone%2Caps%2C237&ref=nb_sb_noss_1\"\n            ],\n            \"address_id\": 872,\n            \"exclude_sponsored\": \"true\",\n            \"sort_by\": \"price-asc-rank\"\n        },\n        \"callback_url\": \"https://example.com/webhook\"\n    }\n]");
Request request = new Request.Builder()
  .url("https://bulk.easyparser.com/v1/bulk")
  .method("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.

| 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 for receiving the completion webhook. | `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 |

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

<table><thead><tr><th width="183.666748046875">Parameter</th><th width="143.666748046875">Type</th><th width="168.7777099609375">Applicable Operations</th><th>Description / Accepted Values</th></tr></thead><tbody><tr><td>language</td><td>String</td><td><code>ALL OPERATIONS</code></td><td>Preferred data language (e.g., <code>en_US</code>). Note: Incompatible with <code>address_id</code>.</td></tr><tr><td>currency</td><td>String</td><td><code>ALL OPERATIONS</code></td><td>ISO Currency code for price data (e.g., <code>USD</code>, <code>EUR</code>, <code>GBP</code>).</td></tr><tr><td>parameters</td><td>String</td><td><code>ALL OPERATIONS</code></td><td>Custom URL parameters to be appended to the Amazon request.</td></tr><tr><td>cookie</td><td>String</td><td><code>ALL OPERATIONS</code></td><td>Pass-through session cookies for localized or authenticated views.</td></tr><tr><td>associate_id</td><td>String</td><td><code>DETAIL</code>, <code>OFFER</code>, <code>SEARCH</code>, <code>SELLER_PROFILE</code>, <code>SELLER_PRODUCTS</code></td><td>Your Amazon Associate tracking ID for link generation.</td></tr><tr><td>sort_by</td><td>String</td><td><code>SEARCH</code>, <code>SELLER_PRODUCTS</code></td><td><p>SEARCH: <code>featured</code>, <code>price-asc-rank</code>, <code>price-desc-rank</code>, <code>review-rank</code>, <code>date-desc-rank</code>, <code>exact-aware-popularity-rank</code>.</p><p><br></p><p>SELLER_PRODUCTS: <code>featured-rank</code>, <code>exact-aware-popularity-rank</code>.</p></td></tr><tr><td>page</td><td>Integer</td><td><code>SEARCH,</code> <code>SELLER_PRODUCTS</code></td><td>The specific result page to extract (Default: <code>1</code>).</td></tr><tr><td>exclude_sponsored </td><td>Boolean</td><td><code>SEARCH</code></td><td>If <code>true</code>, excludes sponsored (ad) products from the search results.</td></tr><tr><td>exclude_refinements</td><td>Boolean</td><td><code>SEARCH</code>, <code>SELLER_PRODUCTS</code></td><td>Excludes refinement options in search results.</td></tr><tr><td>Offer Filters(See keys in description)</td><td>Boolean</td><td><code>OFFER</code></td><td><p>Logistics: <code>prime</code>, <code>free_shipping</code>.</p><p><br></p><p>Condition: <code>condition_new</code>, <code>condition_used_like_new</code>, <code>condition_used_very_good</code>, <code>condition_used_good</code>, <code>condition_used_acceptable</code>.</p><p><br></p><p><em>Note: Multiple filters can be set to <code>true</code> simultaneously.</em></p></td></tr><tr><td>min_quantity</td><td>Integer</td><td><code>OFFER</code></td><td>Filters offers based on minimum order quantity.</td></tr><tr><td>a_plus_content</td><td>Boolean</td><td><code>DETAIL</code></td><td>Set to <code>true</code> to retrieve enhanced marketing (A+) content.</td></tr><tr><td>history_range</td><td>String</td><td><code>SALES_ANALYSIS_HISTORY</code></td><td>Specifies the duration for analysis (e.g., <code>"3"</code>).</td></tr></tbody></table>

{% 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

### **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.\
      \&#xNAN;*or*
   2. `keywords`: A list of Amazon ASINs to retrieve details for.

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

### **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 Amazon search URLs.\
      \&#xNAN;*or*
   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](https://easyparser.gitbook.io/easyparser-documentation/amazon/offer) 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"
}
```

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://easyparser.gitbook.io/easyparser-documentation/bulk-integration/bulk-service-request.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.