Quickstart

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.

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.

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

Open Settings > API Keys and click Create API Key.
For this quickstart, grant articles:write and suppliers:write. Write permissions include read permissions.
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.

2. Make your first call

Read one article:

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`

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:

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:

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.

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.

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" }
    ]
  }'

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

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

curl "https://app.polygon-one.com/api/v1/import-jobs/6f7a..." \
  -H "Authorization: Bearer eudr_8f7d2a..."

{
  "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).

5. Next steps

Recommended integration flows

Order sync, plots and PPWR as end-to-end sequences — which call when.

Batch Import (async)

Articles, suppliers and orders in bulk, job results, error keys, delta sync.

PPWR

Packaging master data, quantities and volume reports.

Geo analysis

Send a plot geometry, read the deforestation analysis, download the report.

Errors & limits

Status codes, rate limit, retries, size limits.

API Documentation

Articles

Suppliers

Plots

Evidence

Orders

Import Jobs

DDS Statements

PPWR – Packaging Data

PPWR – Documents

PPWR – Declarations of Conformity

PPWR – Quantities & Volume Reports

1. Create an API key

2. Make your first call

3. Create a supplier and an article

4. Send a batch and poll the job

5. Next steps

Recommended integration flows

Batch Import (async)

PPWR

Geo analysis

Errors & limits

​1. Create an API key

​2. Make your first call

​3. Create a supplier and an article

​4. Send a batch and poll the job

​5. Next steps

Recommended integration flows

Batch Import (async)

PPWR

Geo analysis

Errors & limits

1. Create an API key

2. Make your first call

3. Create a supplier and an article

4. Send a batch and poll the job

5. Next steps