Contact

Kontakte durchsuchen und abrufen. Neben der Volltextsuche über die eigenen Kontakte (search, getjustiz) steht eine erweiterte Suche über das aktive Unternehmenszertifikat zur Verfügung (extendsearch, asynchrones Ergebnis).

Kontakt suchen

POST KUNDEN-HMAC /contact/search

Volltextsuche über die eigenen Kontakte. Durchsucht werden u. a. Name, Justiz-ID, Adresse, E-Mail, Telefon und Rolle. Pro Seite werden bis zu 100 Treffer geliefert.

Request-Body (form-data)

Feld	Beschreibung	Beispiel
search	Suchbegriff (Pflicht, 3–100 Zeichen)	DE.Justiz.f8d8388f-1a64-

Response

Paginiertes Suchergebnis: search enthält die Paginierung (found, per_page, current_page, total_pages), data die Trefferliste (bis zu 100 Dokumente pro Seite):

{
  "search": {
    "found": 12,
    "per_page": 100,
    "current_page": 1,
    "total_pages": 1
  },
  "data": [
    {
      "contact_ID": "<uuid>",
      "contact_justiz_ID": "<safe-id>",
      "...": "..."
    }
  ]
}

Feld	Typ	Beschreibung
data[].contact_ID	string	Interne Kontakt-ID
data[].contact_justiz_ID	string	Justiz-ID / Safe-ID des Kontakts
data[].contact_full_name	string	Vollständiger Name
data[].contact_first_name / contact_last_name	string	Vor- und Nachname
data[].contact_street_name / contact_house_number	string	Straße und Hausnummer
data[].contact_postal_code / contact_city / contact_country	string	PLZ, Ort, Land
data[].contact_email / contact_phone / contact_fax	string	Kontaktdaten
data[].contact_role_name / contact_egvp_role	string	Rolle des Kontakts

Mögliche Fehler

Code	Meldung	Bedingung
406	validationinvalid	search fehlt, ist kürzer als 3 oder länger als 100 Zeichen; page nicht numerisch
403	access denied	HMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)

Kontakt per Justiz-ID abrufen

POST KUNDEN-HMAC /contact/getjustiz

Liefert den Kontakt, der zur angegebenen Justiz-ID (Safe-ID) gehört.

Request-Body (form-data)

Feld	Beschreibung	Beispiel
contact_justiz_ID	Justiz-ID des gesuchten Kontakts (Pflicht, 10–100 Zeichen)	DE.Justiz.f8d8388f-1a64-4d23-bfe9-38d58f4c4ee4.973d

Response

Kontakt-Objekt mit allen hinterlegten Feldern (Adresse, Kommunikationsdaten, Rolle).

Mögliche Fehler

Code	Meldung	Bedingung
404	contact could not be found	Kein Kontakt mit dieser Justiz-ID vorhanden
406	validationinvalid	contact_justiz_ID fehlt oder Länge außerhalb 10–100
403	access denied	HMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)

Erweiterte Kontaktsuche (asynchron)

POST KUNDEN-HMAC /contact/extendsearch

Startet eine erweiterte Kontaktsuche über das aktive Unternehmenszertifikat (z. B. externes Verzeichnis). Das Ergebnis wird nicht synchron geliefert – die Response enthält eine datahandler_ID, über die das Ergebnis anschließend per POST /datahandler/get/{id} abgerufen wird.

Request-Body (form-data)

Feld	Beschreibung	Beispiel
contact_organisation	Organisation des Kontakts (max. 300)	–
contact_alternative_organization	Alternative Organisation (max. 200)	–
contact_form_address	Anschriftform (max. 200)	–
contact_title	Titel (max. 50)	–
contact_first_name	Vorname (max. 100)	–
contact_last_name	Nachname (max. 100)	–
contact_profession_property	Berufsmerkmal (max. 200)	–
contact_role_name	Rolle (max. 100)	–
contact_state	Bundesland (max. 50)	–
contact_justiz_ID	Justiz-ID (max. 100)	–
contact_street_name	Straße (max. 200)	–
contact_house_number	Hausnummer (max. 50)	–
contact_city	Ort (max. 200)	–
contact_postal_code	PLZ (max. 20)	–

Weitere Request-Felder (form-data/JSON)

Feld	Beschreibung	Beispiel
cert_ID	Optional: UUID v4 des zu verwendenden Zertifikats	–

Response

Die datahandler_ID zum Abruf des asynchronen Ergebnisses über datahandler/get/{datahandler_ID}:

{
  "datahandler_ID": "<uuid>"
}

Mögliche Fehler

Code	Meldung	Bedingung
404	cert could not be found	Es sind keine Zertifikate hinterlegt
404	no active cert found	Kein aktives Zertifikat vorhanden
409	more than one active cert found	Mehrere aktive Zertifikate – cert_ID zur Auswahl mitsenden
406	validationinvalid	Feld-Constraints verletzt oder cert_ID keine UUID v4
403	access denied	HMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)