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

# Quickstart

> Your first successful API call in five minutes — create a key, read, create, send a batch

This page takes you from zero to a working integration in five steps. You need `curl` (or any HTTP
client) and access to **Settings > API Keys** in Polygon One.

> [!WARNING]
>
> **There is no sandbox.** Every call acts on your live workspace. The records you create below are
> real — delete them afterwards in the app, or use test names you will recognise.

> [!NOTE]
>
> **Prefer Postman or Insomnia?** Import the OpenAPI 3.1 spec from
> `https://help.polygon-one.com/api-reference/openapi.json`. The same file works with OpenAPI client
> generators.

## 1. Create an API key

1. Open **Settings > API Keys** and click **Create API Key**.
2. For this quickstart, grant `articles:write` and `suppliers:write`. Write permissions include read
   permissions.
3. Copy the key. It starts with `eudr_` — this is historical; the same key works for EUDR and PPWR,
   provided it has the permissions and the user it acts as has the module enabled.

Store the key in an environment variable or a secret store, never in client-side code. Details:
[Authentication](https://help.polygon-one.com/en/api-reference/introduction.md#authentication).

## 2. Make your first call

Read one article:

```bash theme={null}
curl "https://app.polygon-one.com/api/v1/articles?limit=1" \
  -H "Authorization: Bearer eudr_8f7d2a..."
```

**Success:** `200` with a JSON array. In a new workspace the array is empty (`[]`).

The two most common failures on a first call:

| What you see | Cause | Fix |
| :- | :- | :- |
| `401` with `{"error":"Invalid or expired API key"}` | The key is wrong, revoked or expired | Copy the key again, or create a new one |
| `429` with an **HTML page** | The `Authorization` header is missing or malformed. Requests without a valid `Bearer` header are stopped by bot protection before they reach the API | Send `Authorization: Bearer <key>` — the value must start with `Bearer ` |

More on status codes: [Errors & limits](https://help.polygon-one.com/en/api-reference/errors-and-limits.md).

## 3. Create a supplier and an article

A `POST` with **one object** creates one record and answers synchronously with `201`.

**Supplier** — `name`, `email`, `country` and `address` are required. `country` is the English country
name (e.g. `Germany`, not `DE`); `address` needs `street`, `postalCode` and `city`:

```bash theme={null}
curl -X POST "https://app.polygon-one.com/api/v1/suppliers" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sawmill Example GmbH",
    "email": "eudr@sawmill-example.com",
    "country": "Germany",
    "externalSupplierId": "LIEF-4711",
    "address": { "street": "Waldweg 1", "postalCode": "79100", "city": "Freiburg" }
  }'
```

The response is `201` with `{ "supplier": { "id": "…", … } }`. Keep `supplier.id`.

**Article** — `name`, `internalArticleNr` and `hsCode` are required. A purchase article (the default)
also needs a supplier, via `supplierId` or `supplierName`:

```bash theme={null}
curl -X POST "https://app.polygon-one.com/api/v1/articles" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pine plank 20 mm",
    "internalArticleNr": "ART-1001",
    "hsCode": "4407.11",
    "supplierId": "<SUPPLIER_ID>"
  }'
```

The response is `201` with `{ "article": { "id": "…", … } }`. EUDR relevance is derived from the HS
code. Sending the same `internalArticleNr` again returns `409` — the article already exists. A `409`
with a `warnings` array means a possible duplicate (same name or EAN); see
[Duplicate warnings](https://help.polygon-one.com/en/api-reference/introduction.md#duplicate-warnings).

## 4. Send a batch and poll the job

An **array** (or `{"rows": [...]}`) is a batch. It runs asynchronously: the API answers `202` with a
`jobId`, and nothing is imported yet.

```bash theme={null}
curl -X POST "https://app.polygon-one.com/api/v1/articles" \
  -H "Authorization: Bearer eudr_8f7d2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "name": "Pine plank 25 mm", "internalArticleNr": "ART-1002", "hsCode": "4407.11", "supplierName": "Sawmill Example GmbH" },
      { "name": "Pine plank 30 mm", "internalArticleNr": "ART-1003", "hsCode": "4407.11", "supplierName": "Sawmill Example GmbH" }
    ]
  }'
```

```json theme={null}
{ "jobId": "6f7a...", "status": "queued", "statusUrl": "/api/import-jobs/6f7a..." }
```

Poll the job about every 2 seconds until `status` is `completed` or `failed`:

```bash theme={null}
curl "https://app.polygon-one.com/api/v1/import-jobs/6f7a..." \
  -H "Authorization: Bearer eudr_8f7d2a..."
```

```json theme={null}
{
  "jobId": "6f7a...",
  "kind": "articles",
  "source": "erp",
  "runId": null,
  "status": "completed",
  "progress": { "total": 2, "processed": 2, "failed": 0 },
  "result": { "…": "…" },
  "error": null,
  "createdAt": "2026-10-05T08:00:00.000Z",
  "finishedAt": "2026-10-05T08:00:03.000Z"
}
```

`result` lists imported, updated, skipped and failed rows. Sending the same batch again is safe: rows
that already exist come back as skipped or updated, no duplicates are created. Details:
[Batch Import (async)](https://help.polygon-one.com/en/api-reference/batch-import.md).

## 5. Next steps

> **[Recommended integration flows](https://help.polygon-one.com/en/api-reference/integration-flows.md)**
>
> Order sync, plots and PPWR as end-to-end sequences — which call when.

> **[Batch Import (async)](https://help.polygon-one.com/en/api-reference/batch-import.md)**
>
> Articles, suppliers and orders in bulk, job results, error keys, delta sync.

> **[PPWR](https://help.polygon-one.com/en/api-reference/ppwr.md)**
>
> Packaging master data, quantities and volume reports.

> **[Geo analysis](https://help.polygon-one.com/en/api-reference/geo-analysis.md)**
>
> Send a plot geometry, read the deforestation analysis, download the report.

> **[Errors & limits](https://help.polygon-one.com/en/api-reference/errors-and-limits.md)**
>
> Status codes, rate limit, retries, size limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.