VALIDOOO DEVELOPERS - API (v1

Quick start

Auth: X-API-Key Format: JSON PNG: image/png

All endpoints are located under /v1/… and require the header X-API-Key.

The API key consists of 64 characters. You can create and manage up to five active API keys via the account overview in your customer account.

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/kontostand"

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "kontostand": 100,
    "einheit": "VDS"
  }
}

Base URL

Production:
https://api.validooo.de/

Documentation:
https://www.validooo.de/developers/api_v1/

Notes

All responses are no-store (no caching).
Always set query parameters (e.g. ?pruefcode=).
Date fields must be in YYYY-MM-DD format.

Contents

Authentication Status codes & error format Endpoints (overview) Balance Color selection Validation Seal (creation) Validation Seal (get status) Validation Seal (change status) Validation Seal (get archiving status) Validation Seal (change archiving) Validation Seal (get content) Validation Seal (PNG output) FAQ

Authentication

The VALIDOOO API interface uses a static API key in the HTTP header:

X-API-Key: 64_char_lowercase_hex

If the header is missing, the API responds with 401 (UNAUTHORIZED).
If the format is invalid (not 64 characters lowercase hex), also 401.
If the key is invalid/blocked, also 401.

Status codes & error format

Standard success responses contain success: true. Error responses contain success: false and an error object.

Common HTTP status codes

Code	Meaning
200	OK (success)
201	Created (new seal created)
400	Bad Request (parameters/validation)
401	Unauthorized (missing/invalid API key)
403	Forbidden (e.g. insufficient balance / color not allowed)
404	Not Found (seal/record not found)
500	Server/Crypto/DB error

Error object (example)

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Parameter muss exakt ?pruefcode= heißen"
  }
}

Note: some responses include additional fields (e.g. vds_status).

Endpoints (overview)

Method	Path	Purpose
GET	/v1/kundenkonto/farbauswahl_aktuell	Display the current validation seal color selection
GET	/v1/kundenkonto/farbauswahl_liste	Display available colors for the customer account
POST	/v1/kundenkonto/farbauswahl_aendern	Change the validation seal color selection
GET	/v1/kundenkonto/kontostand	Display the current VDS balance of the customer account
POST	/v1/kundenkonto/siegelerstellung	Create a new validation seal
GET	/v1/kundenkonto/siegelinhalt	Display the validation seal content in plain text
GET	/v1/kundenkonto/siegelgenerator_png	Download the validation seal as a PNG image file
GET	/v1/kundenkonto/siegelstatus	Display the current validation seal status
POST	/v1/kundenkonto/siegelstatus_aendern	Change the validation seal status
GET	/v1/kundenkonto/siegelarchivierung	Display the current validation seal archiving status
POST	/v1/kundenkonto/siegelarchivierung_aendern	Change the validation seal archiving status

Root health check: Calling the domain root / (GET) returns a small status response (service/status/version/hint/docs).

Balance

GET /v1/kundenkonto/kontostand

Returns the current VDS balance of the customer account associated with the API key.

Request

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/kontostand"

Response (200)

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "kontostand": 100,
    "einheit": "VDS"
  }
}

Color selection

Colors are available as name_datenbank (technical key) and name_anzeige (UI name). A color can only be set if it is enabled for the customer account.

Request (current color selection)

GET /v1/kundenkonto/farbauswahl_aktuell

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/farbauswahl_aktuell"

Example response (200)

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "farbauswahl": {
      "name_datenbank": "schwarz_onyx",
      "name_anzeige": "Schwarz (ONYX)"
    }
  }
}

Request (available colors)

GET /v1/kundenkonto/farbauswahl_liste

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/farbauswahl_liste"

Example response (200)

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "farben":[
      {"name_anzeige":"Grau (SMOKYTONES)","name_datenbank":"grau_smokytones"},
      {"name_anzeige":"Grün (SMARAGD)","name_datenbank":"gruen_smaragd"},
      {"name_anzeige":"Rot (LAVA)","name_datenbank":"rot_lava"},
      {"name_anzeige":"Schwarz (ONYX)","name_datenbank":"schwarz_onyx"},
      {"name_anzeige":"Standard (VALIDOOO-BLAU)","name_datenbank":"standard_validoooblau"}
    ]
  }
}

Request (change color selection)

POST /v1/kundenkonto/farbauswahl_aendern

Changes the validation seal color selection. The request body must be JSON and contain exactly the key farbe.

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "farbe": "standard_validoooblau"
  }' \
  "https://api.validooo.de/v1/kundenkonto/farbauswahl_aendern"

Example response (200)

{
  "success": true,
  "data": {
    "kundennummer": "VD-0123456789",
    "farbauswahl": {
      "name_datenbank": "standard_validoooblau",
      "name_anzeige": "Standard (VALIDOOO-BLAU)"
    }
  }
}

Validation Seal (Creation)

POST /v1/kundenkonto/siegelerstellung

Creates a new validation seal (Attention: This process costs 1 VDS when creating a new one) and returns the unique validation code "pruefcode" (consisting of 4 blocks with 4 characters each, e.g. X4yB-x3XT-zx2Y-XZY1) and the new account balance. If a record already exists for the same pruefcode, it will be updated (especially additional/further information, document version) and the balance will not be reduced again.

Content-Type

application/json (recommended)
alternatively: application/x-www-form-urlencoded

Body Parameters

Field	Required	Description
dokument_version	YES	Available versions: modern or klassisch
dokument_art	YES	Available document types: Zertifikat Zeugnis Urkunde (Teilnahme) Gutachten / Prüfdokument Bestätigung / Nachweis Vertrag Protokoll / Bericht Zahlungen / Finanzen Gutschein / Nachlass Kündigung / Rückabwicklung Ausweis / Ticket
text-A	YES	Content VALIdot-A / First name (content specifications according to handbook)
text-B	YES	Content VALIdot-B / Last name (content specifications according to handbook)
text-C	YES	Content VALIdot-C / Date of birth (content specifications according to handbook)
text-D	YES	Content VALIdot-D / Place of birth (content specifications according to handbook)
text-E	YES	Content VALIdot-E / Issue date (content specifications according to handbook)
text-zusatzinfos	NO	Maximum 500 characters, no line breaks, content rules like VALIdots

Request (JSON, example “modern”)

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dokument_version": "modern",
    "dokument_art": "Zertifikat",
    "text-A": "Example content A (100 characters)",
    "text-B": "Example content B (30 characters)",
    "text-C": "Example content C (30 characters)",
    "text-D": "Example content D (30 characters)",
    "text-E": "Example content E (30 characters)",
    "text-zusatzinfos": "Optional additional text (500 characters)"
  }' \
  "https://api.validooo.de/v1/kundenkonto/siegelerstellung"

Request (JSON, example “klassisch”)

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dokument_version": "klassisch",
    "dokument_art": "Zeugnis",
    "text-A": "First name (50 characters)",
    "text-B": "Last name (50 characters)",
    "text-C": "1999-01-01",
    "text-D": "Place of birth (50 characters)",
    "text-E": "2025-12-31",
    "text-zusatzinfos": "Optional additional text (500 characters)"
  }' \
  "https://api.validooo.de/v1/kundenkonto/siegelerstellung"

Response (201 – created)

{
  "success": true,
  "pruefcode": "XXXX-XXXX-XXXX-XXXX",
  "dokument_version": "modern",
  "dokument_art": "Zertifikat",
  "kontostand": 99
}

Response (200 – already existed, updated)

{
  "success": true,
  "hinweis": "Siegel war bereits vorhanden und wurde aktualisiert",
  "pruefcode": "XXXX-XXXX-XXXX-XXXX",
  "dokument_version": "modern",
  "dokument_art": "Zertifikat",
  "kontostand": 100
}

Important: Only certain characters are accepted. For version klassisch, text-C and text-E must be valid calendar dates in YYYY-MM-DD format.

Validation Seal (Get status)

GET /v1/kundenkonto/siegelstatus?pruefcode=XXXX-XXXX-XXXX-XXXX

Checks the activation status of a seal using the pruefcode string. The pruefcode string is case-sensitive (uppercase/lowercase is respected).

Request

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/siegelstatus?pruefcode=XXXX-XXXX-XXXX-XXXX"

Response (200)

{
  "success": true,
  "vds_status": "aktiviert"
}

Possible values: aktiviert or deaktiviert.

Validation Seal (Change status)

POST /v1/kundenkonto/siegelstatus_aendern

Activates or deactivates a seal. The request body must be JSON and contain exactly the keys pruefcode and status. status accepts only aktiviert or deaktiviert.

Content-Type

application/json

Request (JSON)

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pruefcode": "XXXX-XXXX-XXXX-XXXX",
    "status": "deaktiviert"
  }' \
  "https://api.validooo.de/v1/kundenkonto/siegelstatus_aendern"

Response (200)

{
  "success": true,
  "vds_status": "deaktiviert"
}

Validation Seal (Get archiving status)

GET /v1/kundenkonto/siegelarchivierung?pruefcode=XXXX-XXXX-XXXX-XXXX

Checks the archiving status of a seal using the pruefcode string. The pruefcode string is case-sensitive (uppercase/lowercase is respected).

Request

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/siegelarchivierung?pruefcode=XXXX-XXXX-XXXX-XXXX"

Response (200)

{
  "success": true,
  "vds_archiv": "archiviert"
}

Possible values: archiviert or bereitgestellt.

Validation Seal (Change archiving)

POST /v1/kundenkonto/siegelarchivierung_aendern

Archives or re-provides a seal. The request body must be JSON and contain exactly the keys pruefcode and archiv. archiv accepts only archivierung or bereitstellung.

Request (JSON)

curl -s -X POST \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pruefcode": "XXXX-XXXX-XXXX-XXXX",
    "archiv": "bereitstellung"
  }' \
  "https://api.validooo.de/v1/kundenkonto/siegelarchivierung_aendern"

Response (200)

{
  "success": true,
  "vds_archiv": "bereitgestellt"
}

Validation Seal (Get content)

GET /v1/kundenkonto/siegelinhalt?pruefcode=XXXX-XXXX-XXXX-XXXX

Returns the content stored in the seal as well as the optional additional text. The key names differ depending on dokument_version.

Request

curl -s \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/siegelinhalt?pruefcode=XXXX-XXXX-XXXX-XXXX"

Response (200 – example modern)

{
  "success": true,
  "dokument_art": "Zertifikat",
  "dokument_version": "modern",
  "daten": {
    "VALIdot-A": "Example content A (100 characters)",
    "VALIdot-B": "Example content B (30 characters)",
    "VALIdot-C": "Example content C (30 characters)",
    "VALIdot-D": "Example content D (30 characters)",
    "VALIdot-E": "Example content E (30 characters)"
  },
  "dokument_zusatztext": "Optional additional text (500 characters)"
}

Response (200 – example klassisch)

{
  "success": true,
  "dokument_art": "Zeugnis",
  "dokument_version": "klassisch",
  "daten": {
    "Vorname": "First name (50 characters)",
    "Nachname": "Last name (50 characters)",
    "Geburtsdatum": "1999-01-01",
    "Geburtsort": "Place of birth (50 characters)",
    "Ausstellungsdatum": "2025-12-31"
  },
  "dokument_zusatztext": "Optional additional text (500 characters)"
}

Validation Seal (PNG output)

GET /v1/kundenkonto/siegelgenerator_png?pruefcode=XXXX-XXXX-XXXX-XXXX

Returns the validation seal as a PNG file (Content-Type: image/png) and sets Content-Disposition: attachment (browser download).

Request (download to file)

curl -L \
  -H "X-API-Key: YOUR_64_CHAR_API_KEY" \
  "https://api.validooo.de/v1/kundenkonto/siegelgenerator_png?pruefcode=XXXX-XXXX-XXXX-XXXX" \
  --output YOUR_CUSTOM_FILENAME.png

Note: This endpoint does not return JSON output, but a binary file (PNG image file).

Rate limits

How are rate limits configured?

Rate limits are configured so that a maximum of 80 requests per minute are allowed per API key, while up to 200 requests per minute are processed per IP address.

How do I know if a rate limit has been triggered?

A triggered rate limit can be identified by the API responding with the corresponding HTTP status code (e.g. 429 Too Many Requests) or by the response containing clear indications that a limit has been exceeded.

How are invalid or unauthorized requests handled?

All 401, 403, and 404 errors are strictly monitored and automatically blocked in case of suspicious behavior. Unblocking is also automated according to internal policies and cannot be lifted early.