> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agribackup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Register Consolidated EUDR Batch Async | AgriBackup

> Create a new EUDR batch linked to verified polygon IDs. Returns 202 Accepted with a jobId. Triggers Copernicus satellite risk assessment automatically.

Creates a new consolidated EUDR batch and links it to an array of pre-verified polygon IDs. Registering a batch automatically triggers a Copernicus satellite risk assessment across all referenced polygons. Because this process is asynchronous, the endpoint returns `202 Accepted` immediately with a `jobId`. Poll `GET /api/v1/enterprise/eudr/jobs/{jobId}` or listen for the `batch.risk_assessed` webhook to retrieve the final `consolidatedRiskState`.

## Request Headers

| Header                  | Required | Description                                                                                                                    |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `X-API-Key`             | ✅        | Your live API key, e.g. `sk_live_...`.                                                                                         |
| `Idempotency-Key`       | ✅        | A UUID v4 string. Replaying the same key within 24 hours returns the original job response without creating a duplicate batch. |
| `X-Sub-Organization-ID` | ☐        | Optional subsidiary identifier to scope the batch to a specific business unit.                                                 |

## Request Body

| Field         | Type             | Required | Description                                                                                                            |
| ------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `commodity`   | string           | ✅        | EUDR commodity type, e.g. `COFFEE`, `COCOA`, `SOYA`.                                                                   |
| `countryCode` | string           | ✅        | ISO 3-letter country code of origin (e.g. `KEN` for Kenya, `BRA` for Brazil).                                          |
| `hsCode`      | string           | ✅        | 6-digit Harmonised System (HS) code for the commodity, e.g. `090111`.                                                  |
| `quantityKg`  | number           | ✅        | Total commodity quantity in kilograms.                                                                                 |
| `polygonIds`  | array of strings | ✅        | Array of verified polygon IDs to include in this batch (max 5,000). All polygon IDs must have `eudrStatus: COMPLIANT`. |
| `vendorIds`   | array of strings | ☐        | Optional list of ERP vendor IDs to link this batch to your Tier-1 supply chain mapping.                                |

```json theme={null}
{
  "commodity": "COFFEE",
  "countryCode": "KEN",
  "hsCode": "090111",
  "quantityKg": 5000.5,
  "polygonIds": [
    "uuid-polygon-1",
    "uuid-polygon-2"
  ],
  "vendorIds": ["ERP-VEND-991"]
}
```

## Response — 202 Accepted

| Field                  | Type              | Description                                                                    |
| ---------------------- | ----------------- | ------------------------------------------------------------------------------ |
| `jobId`                | string            | Use this ID to poll job status via `GET /api/v1/enterprise/eudr/jobs/{jobId}`. |
| `status`               | string            | Always `PENDING` on acceptance.                                                |
| `estimatedDurationSec` | integer           | Estimated seconds until risk assessment completes.                             |
| `createdAt`            | string (ISO-8601) | Timestamp when the job was accepted.                                           |

The response also includes a `Location` header pointing to the job status endpoint.

```json theme={null}
{
  "jobId": "job_998877",
  "status": "PENDING",
  "estimatedDurationSec": 3,
  "createdAt": "2026-06-15T12:00:00Z"
}
```

## Async Completion — `batch.risk_assessed` Webhook

When the Copernicus risk assessment finishes, AgriBackup fires a `batch.risk_assessed` event to your registered webhook URL. The event payload is signed with `X-AgriBackup-Signature` (HMAC-SHA256). Once the batch has a `consolidatedRiskState` of `COMPLIANT`, it is ready to be linked to a logistics shipment.

## Code Examples

<CodeGroup>
  ```python Python theme={null}
  import agribackup
  from agribackup.rest import ApiException
  import uuid

  configuration = agribackup.Configuration(host="https://live.agribackup.com/api/v1")
  configuration.api_key['ApiKeyAuth'] = 'sk_live_YOUR_API_KEY'

  with agribackup.ApiClient(configuration) as api_client:
      try:
          api_instance = agribackup.EnterpriseBatchesApi(api_client)

          request = agribackup.BatchRegistrationRequest(
              commodity='COFFEE',
              country_code='KEN',
              hs_code='090111',
              quantity_kg=5000.5,
              polygon_ids=['uuid-polygon-1', 'uuid-polygon-2'],
              vendor_ids=['ERP-VEND-991']
          )

          response = api_instance.register_batch(
              idempotency_key=str(uuid.uuid4()),
              batch_registration_request=request
          )
          print("Job accepted:", response.job_id)
      except ApiException as e:
          print("Error:", e)
  ```

  ```javascript Node.js theme={null}
  import { AgriBackupClient } from '@agribackup/sdk';
  import { v4 as uuidv4 } from 'uuid';

  const client = new AgriBackupClient({
    apiKey: 'sk_live_YOUR_API_KEY',
    baseUrl: 'https://live.agribackup.com/api/v1'
  });

  async function registerBatch() {
    try {
      const response = await client.batches.registerBatch({
        idempotencyKey: uuidv4(),
        commodity: 'COFFEE',
        countryCode: 'KEN',
        hsCode: '090111',
        quantityKg: 5000.5,
        polygonIds: ['uuid-polygon-1', 'uuid-polygon-2'],
        vendorIds: ['ERP-VEND-991']
      });
      console.log('Job accepted:', response.jobId);
    } catch (error) {
      console.error('Error:', error.message);
    }
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://live.agribackup.com/api/v1/enterprise/eudr/batches \
    -H "X-API-Key: sk_live_YOUR_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "commodity": "COFFEE",
      "countryCode": "KEN",
      "hsCode": "090111",
      "quantityKg": 5000.5,
      "polygonIds": ["uuid-polygon-1", "uuid-polygon-2"],
      "vendorIds": ["ERP-VEND-991"]
    }'
  ```
</CodeGroup>


## OpenAPI

````yaml post /api/v1/enterprise/eudr/batches
openapi: 3.0.1
info:
  title: AgriBackup Enterprise EUDR API
  description: >-
    # Introduction


    AgriBackup is the cryptographic compliance engine for EU-bound commodity
    imports. Built on Deterministic Logic, Immutable Evidence, and
    High-Throughput Ingestion, our API provides Tier-1 enterprise routing for EU
    Deforestation Regulation (EUDR).


    ## The Integration Vector

    To integrate this Digital Trust Layer into your ERP, you must execute the
    following sequence:

    1. **Authentication:** Generate your `X-API-Key` from the client dashboard.

    2. **Telemetry:** Register your webhook URLs via `POST /webhooks`.

    3. **Ingestion:** Push your GeoJSON polygons via `POST /polygons`.

    4. **Logistics:** Lock the batch to a shipment via `POST /shipments/link`.


    ## Asynchronous Architecture

    Because satellite deforestation screening and Hedera DLT anchoring take
    time, ingestion endpoints return a `202 Accepted`. You must listen for the
    corresponding Webhook to confirm cryptographic execution.


    ## Base URLs

    * **Production:** `https://live.agribackup.com`

    * **Sandbox:** `https://sandbox.agribackup.com`
  contact:
    name: AgriBackup Architecture Team
    url: https://agribackup.com
    email: contact@agribackup.com
  license:
    name: Proprietary
    url: https://agribackup.com/terms
  version: v1.0
servers:
  - url: https://live.agribackup.com
    description: Production (Mainnet)
  - url: https://sandbox.agribackup.com
    description: Sandbox (Testnet)
security: []
tags:
  - name: Enterprise Risk Management
  - name: Enterprise Clearance Webhooks
    description: Asynchronous status receivers for TRACES NT
  - name: Enterprise Jobs
    description: Query status and metrics of asynchronous compliance jobs
  - name: Enterprise Suppliers
  - name: Enterprise Diagnostics
    description: Monitor API health, consensus ledger, and satellite systems availability
  - name: Enterprise Suppliers
    description: Map internal ERP vendor IDs to EU Operator UUIDs
  - name: Enterprise Webhooks
    description: Register endpoints for asynchronous compliance events
  - name: Enterprise Archival
    description: Endpoints for bulk compliance archiving and auditor extensibility
  - name: Enterprise Logistics
    description: Smart contract linking of batches to logistics shipments
  - name: Enterprise Declarations
    description: DDS generation with legal land tenure proofs
  - name: Enterprise Batches
  - name: Enterprise API Keys
  - name: Enterprise Diagnostics
  - name: Enterprise Logistics
  - name: Enterprise Jobs
  - name: Enterprise Evidence
    description: Cryptographic evidence ledger anchored on Hedera Hashgraph
  - name: Enterprise Declarations
  - name: Enterprise Credentials
  - name: Enterprise Evidence
  - name: Enterprise Risk Management
    description: Pre-assessment of country risk and satellite deforestation probabilities
  - name: Enterprise Batches
    description: Programmatic batch ingestion and management
  - name: Enterprise Polygons
  - name: Introduction
  - name: Enterprise Polygons
    description: Programmatic polygon ingestion and verification
  - name: Enterprise Archival
  - name: Enterprise Credentials
    description: Programmatic ingestion of vault-secured enterprise secrets
  - name: Enterprise API Keys
    description: Endpoints for managing B2B API Keys (Requires standard JWT login)
  - name: Enterprise Webhooks
paths:
  /api/v1/enterprise/eudr/batches:
    post:
      tags:
        - Enterprise Batches
      summary: Register a consolidated EUDR batch (Async)
      description: >-
        Programmatically create a new EUDR batch linked to an array of
        pre-verified Polygon IDs. Automatically registers sourcing events and
        triggers a Copernicus risk assessment check. Returns 202 instantly.
      operationId: registerBatch
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/IdempotencyKey'
          name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/SubOrganizationId'
          name: X-Sub-Organization-ID
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRegistrationRequest'
        required: true
      responses:
        '202':
          description: Batch registered and risk assessment queued
          headers:
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets in UTC
                epoch seconds.
              schema:
                type: integer
                format: int32
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests you're permitted to make per
                hour.
              schema:
                type: integer
                format: int32
            X-Trace-Id:
              description: Unique request trace identifier
              style: simple
              schema:
                type: string
            Location:
              description: URL to track the job status
              style: simple
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAcceptedResponse'
        '400':
          description: Bad Request
          headers:
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests you're permitted to make per
                hour.
              schema:
                type: integer
                format: int32
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets in UTC
                epoch seconds.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          headers:
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests you're permitted to make per
                hour.
              schema:
                type: integer
                format: int32
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets in UTC
                epoch seconds.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          headers:
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests you're permitted to make per
                hour.
              schema:
                type: integer
                format: int32
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets in UTC
                epoch seconds.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '413':
          description: 'Payload Too Large: Maximum allowed array size is 5000.'
          headers:
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests you're permitted to make per
                hour.
              schema:
                type: integer
                format: int32
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets in UTC
                epoch seconds.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '423':
          description: >-
            Locked: Execution thread is currently processing the resource. Wait
            and retry.
          headers:
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests you're permitted to make per
                hour.
              schema:
                type: integer
                format: int32
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets in UTC
                epoch seconds.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          headers:
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests you're permitted to make per
                hour.
              schema:
                type: integer
                format: int32
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets in UTC
                epoch seconds.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: Python
          source: >-
            import agribackup

            from agribackup.rest import ApiException


            # Initialize Client

            configuration =
            agribackup.Configuration(host="https://live.agribackup.com/api/v1")

            configuration.api_key['ApiKeyAuth'] = 'sk_live_YOUR_API_KEY'


            with agribackup.ApiClient(configuration) as api_client:
                try:
                    api_instance = agribackup.EnterpriseBatchesApi(api_client)
                    response = api_instance.register_batch()
                    print(response)
                except ApiException as e:
                    print("Exception when calling API: %s\n" % e)
        - lang: Node.js
          source: |-
            import { AgriBackupClient } from '@agribackup/sdk';

            // Initialize Client
            const client = new AgriBackupClient({
              apiKey: 'sk_live_YOUR_API_KEY',
              baseUrl: 'https://live.agribackup.com/api/v1'
            });

            async function execute() {
              try {
                const response = await client.batches.registerBatch();
                console.log(response);
              } catch (error) {
                console.error(error);
              }
            }
        - lang: Java
          source: |-
            import com.agribackup.client.*;
            import com.agribackup.client.api.*;
            import com.agribackup.client.model.*;

            public class Example {
                public static void main(String[] args) {
                    ApiClient defaultClient = Configuration.getDefaultApiClient();
                    defaultClient.setBasePath("https://live.agribackup.com/api/v1");
                    defaultClient.setApiKey("sk_live_YOUR_API_KEY");

                    EnterpriseBatchesApi apiInstance = new EnterpriseBatchesApi(defaultClient);
                    try {
                        Object result = apiInstance.registerBatch();
                        System.out.println(result);
                    } catch (ApiException e) {
                        System.err.println("Exception when calling API: " + e.getResponseBody());
                    }
                }
            }
        - lang: C#
          source: |-
            using System;
            using System.Threading.Tasks;
            using AgriBackup.SDK.Api;
            using AgriBackup.SDK.Client;
            using AgriBackup.SDK.Model;

            class Program {
                static async Task Main() {
                    Configuration config = new Configuration();
                    config.BasePath = "https://live.agribackup.com/api/v1";
                    config.AddApiKey("ApiKeyAuth", "sk_live_YOUR_API_KEY");

                    var apiInstance = new EnterpriseBatchesApi(config);
                    try {
                        var result = await apiInstance.RegisterBatchAsync();
                        Console.WriteLine(result);
                    } catch (ApiException e) {
                        Console.WriteLine("Exception when calling API: " + e.Message);
                    }
                }
            }
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Unique idempotency key (UUID) to prevent duplicate operations. Safely
        stored in Redis with a strict 24-hour TTL to prevent memory bloat during
        saturation attacks.
      required: true
      schema:
        type: string
        format: uuid
    SubOrganizationId:
      name: X-Sub-Organization-ID
      in: header
      description: >-
        Optional identifier to partition compliance data (polygons, batches,
        declarations) for a specific subsidiary or regional business unit within
        the conglomerate.
      required: false
      schema:
        type: string
  schemas:
    BatchRegistrationRequest:
      required:
        - commodity
        - countryCode
        - hsCode
        - polygonIds
        - quantityKg
      type: object
      properties:
        commodity:
          type: string
          description: EUDR Commodity type or name
          example: COFFEE
        countryCode:
          type: string
          description: >-
            ISO 3-letter country code of origin (e.g., KEN for Kenya, BRA for
            Brazil)
          example: KEN
        hsCode:
          type: string
          description: HS Code (mandatory for dynamic validation)
          example: '090111'
        quantityKg:
          type: number
          description: Total quantity in kilograms
          example: 5000.5
        polygonIds:
          maxItems: 5000
          minItems: 0
          type: array
          description: Array of verified Polygon IDs forming this batch
          items:
            type: string
            description: Array of verified Polygon IDs forming this batch
        vendorIds:
          type: array
          description: >-
            Optional list of ERP Vendor IDs to explicitly map this batch to the
            Tier-1 Enterprise Supply Chain
          items:
            type: string
            description: >-
              Optional list of ERP Vendor IDs to explicitly map this batch to
              the Tier-1 Enterprise Supply Chain
      description: Payload for registering a new consolidated batch
    JobAcceptedResponse:
      required:
        - createdAt
        - estimatedDurationSec
        - jobId
        - status
      type: object
      properties:
        jobId:
          type: string
          description: The unique asynchronous tracking job ID
          example: job_998877
        status:
          type: string
          description: Current execution status invariant
          example: PENDING
          enum:
            - PENDING
        estimatedDurationSec:
          type: integer
          description: >-
            Estimated duration in seconds before consensus or processing lock
            release
          format: int32
          example: 3
        createdAt:
          type: string
          description: Timestamp when the job was accepted
          format: date-time
          example: '2026-06-15T12:00:00Z'
      description: Response payload for asynchronously accepted jobs
    ApiError:
      required:
        - code
        - details
        - message
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: VALIDATION_FAILED
        message:
          type: string
          description: Human-readable error message
          example: Invalid polygon coordinates
        details:
          type: array
          description: Detailed list of validation errors, if applicable
          items:
            $ref: '#/components/schemas/ApiErrorDetail'
      description: Standard error format for all Enterprise API failures
    ApiErrorDetail:
      required:
        - code
        - field
        - issue
      type: object
      properties:
        code:
          type: string
          description: Programmatic error code for automated branch logic
          example: INVALID_COORDINATE_CLOSURE
        field:
          type: string
          description: The field or property that caused the error
          example: features[0].properties.area
        issue:
          type: string
          description: A description of the issue with the field
          example: Area must be specified in hectares and cannot be negative
      description: Detailed error information for a specific field
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Enterprise API Key provided via the AgriBackup developer console.
      name: X-API-Key
      in: header

````