Skip to main content

API Getting Started

This page shows the shortest useful Integration API flow: create a token, test it with a quick VAT ID lookup, then start a retry-safe VAT validation run.

1. Use The Production Base URL​

The Optimus Integration API is available at:

https://app.optimussoftware.de

The examples below use this production system.

2. Create A Token​

Create a Personal Access Token in the Optimus web app under Settings > API Interface > API Tokens.

Copy the token immediately. The full secret is shown only once.

3. Resolve One VAT ID​

Use the quick lookup endpoint to verify that authentication, networking, and the selected environment are working:

curl -X GET "https://app.optimussoftware.de/api/v1/integration/vat/resolve?vatId=DE329194932" \
  -H "Authorization: Bearer <token>"

A successful response returns the VAT ID status and, when available, normalized company data:

{
  "vatId": "DE329194932",
  "status": "Valid",
  "resolvedData": {
    "companyName": "TL Digital Solutions GmbH",
    "street": "Leopoldstr. 8",
    "city": "München",
    "zip": "80802"
  },
  "checkedAt": "2026-04-19T10:17:26.4359867Z"
}

When you need the resolved street split into street name and house number, request those fields with include:

curl -X GET "https://app.optimussoftware.de/api/v1/integration/vat/resolve?vatId=DE329194932&include=addressStreetName,addressHouseNumber" \
  -H "Authorization: Bearer <token>"

The additional fields are returned in included only when the data can be resolved:

{
  "vatId": "DE329194932",
  "status": "Valid",
  "resolvedData": {
    "companyName": "TL Digital Solutions GmbH",
    "street": "Leopoldstr. 8",
    "city": "München",
    "zip": "80802"
  },
  "included": {
    "addressStreetName": "Leopoldstr.",
    "addressHouseNumber": "8"
  },
  "checkedAt": "2026-04-19T10:17:26.4359867Z"
}

4. Start An Asynchronous Validation​

Use asynchronous validation for imports, larger batches, retry-safe jobs, and PDF-producing workflows.

Create validation-request.json:

{
  "records": [
    {
      "vatId": "DE329194932",
      "companyName": "TL Digital Solutions GmbH",
      "street": "Leopoldstr. 8",
      "zip": "80802",
      "city": "München",
      "customerNumber": "C-1001"
    }
  ],
  "options": {
    "checkType": "Standard",
    "retryDuration": "None"
  }
}

Send the request with an idempotency key from your own system, such as an import job ID:

curl -X POST "https://app.optimussoftware.de/api/v1/integration/vat/validations/async" \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: customer-import-2026-05-13-001" \
  -H "Content-Type: application/json" \
  -d @validation-request.json

The response contains an operationId. If the status is Running, wait for the Retry-After value before polling.

5. Poll The Result​

curl -X GET "https://app.optimussoftware.de/api/v1/integration/vat/validations/{operationId}" \
  -H "Authorization: Bearer <token>"

When the run completes, the response includes per-record statuses and field comparison results.