Introduction

Overview

The Polygon One API enables you to manage your EUDR compliance data programmatically. It is designed for server-to-server integration with your ERP system (SAP, Oracle, Microsoft Dynamics, etc.). What you can do with the API:

Articles — Create, update, and query articles. EUDR relevance is determined automatically based on the HS code.
Suppliers — Manage supplier data and link suppliers to articles.
Orders — Import purchase and sale orders (individually or in batches). Orders can be assigned to DDS statements automatically.
DDS Statements — Create and manage due diligence statements for TRACES submission.

Authentication

All API endpoints require a bearer token. Generate your API key in the Polygon One dashboard:

Navigate to Settings > API Keys
Click Create API Key
Select the required permissions (e.g. articles:read, orders:write)
Copy the generated key

Include the key in the Authorization header of every request:

Authorization: Bearer eudr_8f7d2a...

API keys are confidential credentials for server-to-server communication. Store them in environment variables and never expose them in client-side code.

Base URL

All API requests are directed to the following URL:

https://app.polygon-one.com

Permissions

Each API key is assigned specific permissions that govern access:

Permission	Description
`articles:read`	Read articles
`articles:write`	Create, update, and delete articles
`suppliers:read`	Read suppliers
`suppliers:write`	Create, update, and delete suppliers
`orders:read`	Read orders
`orders:write`	Create, update, and delete orders
`dds:read`	Read DDS statements
`dds:write`	Create, update, and delete DDS statements

Write permissions include the corresponding read permission. A key with articles:write may therefore perform both write operations and GET requests for articles.

Response Format

Successful responses return JSON data directly. List endpoints return arrays, while single-resource endpoints return objects. Creating a single resource returns HTTP 201:

{
  "article": { "id": "...", "name": "..." }
}

Batch imports (array or {"rows": [...]}) run asynchronously and return HTTP 202 with a job reference:

{
  "jobId": "6f7a...",
  "status": "queued",
  "statusUrl": "/api/import-jobs/6f7a..."
}

Progress and the final result (imported, updated, skipped and failed rows) are available via GET /api/import-jobs/{jobId} — see the Batch Import (async) guide.

Error Handling

The API uses standard HTTP status codes:

Code	Description
`200`	OK — Request successful
`201`	Created — Resource created successfully
`400`	Bad Request — Invalid input data or validation error
`401`	Unauthorized — Invalid or missing API key
`403`	Forbidden — API key lacks the required permissions, or account setup is incomplete
`404`	Not Found — Resource does not exist or does not belong to your company
`409`	Conflict — The resource conflicts with existing data (e.g. a duplicate `internalArticleNr`), or it triggered overridable soft warnings (see below)
`500`	Internal Server Error — An error occurred on our side

Error responses include an error field and optionally details:

{
  "error": "Validation failed",
  "details": [{ "path": ["hsCode"], "message": "Commodity is required." }]
}

Duplicate and plausibility warnings

When creating an article, the API runs advisory checks that can return 409 instead of creating the article:

Hard conflict (cannot be overridden): an article with the same internalArticleNr already exists. The response is 409 with an error message.
Soft warnings (overridable): a duplicate article name (duplicateName), a duplicate ean (duplicateEan), or an HS-code that does not plausibly match the description (hsMismatch). The response is 409 with a machine-readable warnings array:

{
  "error": "Article has unresolved warnings. Resubmit with acknowledgeWarnings=true to override.",
  "warnings": [
    { "type": "duplicateName", "existingInternalArticleNr": "ART-001" },
    { "type": "duplicateEan", "existingArticleName": "Oak plank 20mm" },
    { "type": "hsMismatch" }
  ]
}

To proceed anyway from a non-interactive integration, resend the request with acknowledgeWarnings: true. Hard conflicts are never overridden by this flag.

API Documentation

Articles

Suppliers

Orders

Import Jobs

DDS Statements

Overview

Authentication

Base URL

Permissions

Response Format

Error Handling

Duplicate and plausibility warnings

​Overview

​Authentication

​Base URL

​Permissions

​Response Format

​Error Handling

​Duplicate and plausibility warnings

Overview

Authentication

Base URL

Permissions

Response Format

Error Handling

Duplicate and plausibility warnings