API docs by Redocly

live API (1.6.1000-161)

Download OpenAPI specification:

HTTP interface of the live server.

Only the public section is released for integrations: sign in with an API key and create, read, list and change assignments. This part is stable – it is only ever extended; nothing goes away and nothing changes its meaning. Everything under internal serves the web app and the tools and may change without notice.

Conventions

  • All payloads are JSON (content-type: application/json).
  • Points in time are milliseconds since 1970 (UTC).
  • Errors come as JSON with a fixed code (e.g. policy.missing_right), category, status and message. Decide on code, never on message. 401: key missing or invalid. 403: the account lacks the right.
  • Responses may carry fields not described here; ignore unknown fields.

1. Sign in

Every request carries the API key in a header: x-api-key: live_api_…. An admin issues the key for an account; it is shown only once and acts with that account's rights.

2. Create an assignment

POST /api/dto/fsg3 with order, subject and creditor. The executing partner is assigned by postal code. The answer names the assignmentId and the reference number ref.

3. Read an assignment

GET /api/dto/fsg3/{ref} – complete, with status, dates and results (results.<service>.<field>).

4. List assignments

GET /api/dto/fsg3 with a filter (filter=status=pending), search (search=), order (sort=subjectDisplayName&dir=asc) and page size (limit=). While the answer carries nextCursor, the same request plus cursor=<nextCursor> returns the next page.

5. Change an assignment

PATCH /api/dto/fsg3/{ref} with the fields to change: fields not named stay, null clears a field, { "status": { "status": "cancelled" } } changes the status. There is no delete; cancelling is a status change.

The field names are English; each field names its column in the fsg3 format.

This page shows a complete example for each of these endpoints.

public

The released, stable interface: sign in with an API key and create, read, list and change assignments. It is only ever extended.

List assignments (FSG, fsg3)

Schritt 4 des Standardablaufs: Aufträge auflisten, jede Zeile in derselben Form wie beim Lesen.

Filter, Sortierung und Seiten lassen sich kombinieren. Die erste Seite liefert nextCursor; dieselbe Anfrage mit cursor=<nextCursor> liefert die Folgeseite, bis nextCursor fehlt.

Beispiel erste Seite: GET /api/dto/fsg3?filter=status%3Dto_confirm&sort=subjectDisplayName&limit=2 mit dem Kopf x-api-key.

Authorizations:
apiKeyAuth
query Parameters
filter
string
Example: filter=status=to_confirm

Filter, wiederholbar: status=<stand>, ref=<aktenzeichen> oder ein Datumsbereich wie modified>=<ms>.

search
string

Freitextsuche (Name, Aktenzeichen, Adresse).

sort
string
Example: sort=subjectDisplayName

Sortierfeld, z. B. ref, subjectDisplayName, status, editedAt, dueDate. Ohne Angabe nach Auftrags-ID.

dir
string
Enum: "asc" "desc"

asc (Vorgabe) oder desc.

limit
integer [ 1 .. 1000 ]
Example: limit=2

Seitengröße (Vorgabe 100, höchstens 1000).

cursor
string

nextCursor der vorigen Seite, unverändert.

offset
integer >= 0

Alternative zum Cursor: Position der Seite.

lifecycle
string

active (Vorgabe), inactive oder all.

Responses

Response samples

Content type
application/json
Example
{
  • "filter": [
    ],
  • "total": 3,
  • "offset": 0,
  • "limit": 2,
  • "returned": 2,
  • "nextCursor": "eyJrIjoiZXlKemIzSjBWbUZzZFdVaU9pSndaWFJ5WVNCaVpXbHpjR2xsYkNJc0ltRnpjMmxuYm0xbGJuUkpaQ0k2SWpObU5tUXlZekZsSW4wIiwibiI6Mn0",
  • "rows": [
    ]
}

Create an assignment (FSG, fsg3)

Schritt 2 des Standardablaufs: einen FSG-Auftrag anlegen. Der Ausführende wird wie beim Import über die PLZ des Schuldners zugeordnet. Die Antwort nennt das Aktenzeichen, unter dem der Auftrag gelesen und geändert wird.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
id
string

Eigene Auftrags-ID (optional). Ein zweites Anlegen mit derselben ID wird abgewiesen.

tenantId
string

Mandant; entfällt, wenn der Key genau einem Mandanten gehört.

clientId
string

Einspeisender; entfällt, wenn der Key zu einem Einspeisenden gehört.

required
object
required
object
object
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "3f6d2c1e-7b4a-4c1e-9a53-2b8e0c4d7f10",
  • "tenantId": "tenant-demo1",
  • "clientId": "a403fc5a-0213-485a-95f1-091a5daf51f7",
  • "order": {
    },
  • "subject": {
    },
  • "creditor": {
    }
}

Response samples

Content type
application/json
{
  • "assignmentId": "3f6d2c1e-7b4a-4c1e-9a53-2b8e0c4d7f10",
  • "ref": "100036",
  • "dataVersion": 1790222260000
}

Read an assignment with results (FSG, fsg3)

Schritt 3 des Standardablaufs: einen Auftrag vollständig lesen – Auftragsdaten, Schuldner, Gläubiger, Status mit Datumswerten und die Ergebnisse je Leistung. Es erscheint nur, was das Konto auch in der App sehen darf.

Authorizations:
apiKeyAuth
path Parameters
ref
required
string
Example: 100036

Aktenzeichen des Auftrags; die Auftrags-ID geht ebenso.

Responses

Response samples

Content type
application/json
{
  • "assignment": {
    }
}

Change an assignment (FSG, fsg3)

Schritt 5 des Standardablaufs: einen Auftrag ändern.

Nur die genannten Felder ändern sich, null leert ein Feld, status.status wechselt den Status – sofern das Konto das in der App darf. Der Aufruf gilt ganz oder gar nicht: ein unbekanntes, nicht änderbares oder nicht erlaubtes Feld weist ihn ab, bevor etwas geschrieben wird. Löschen gibt es nicht; storniert wird per Statuswechsel. Die Antwort ist der Auftrag nach der Änderung.

Authorizations:
apiKeyAuth
path Parameters
ref
required
string
Example: 100036

Aktenzeichen des Auftrags; die Auftrags-ID geht ebenso.

Request Body schema: application/json
required
object
object
object
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
Example
{
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "dataVersion": 1790222290000
}