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

# Introduction

> Integrate your ERP system with the Polygon One EUDR Compliance Platform

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

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

Include the key in the `Authorization` header of every request:

```bash theme={null}
Authorization: Bearer eudr_8f7d2a...
```

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

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

```json theme={null}
{
  "article": { "id": "...", "name": "..." }
}
```

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

```json theme={null}
{
  "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)](/en/api-reference/batch-import) 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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.