HilfezentrumIntegrationen

Für: Administratoren

Formulare senden und Antworten mit einem Hub-Schlüssel lesen

Erstellen Sie anhand einer Vorlage ein Formular zu einem Fall, veröffentlichen Sie es bei den Personen, die es ausfüllen sollen, und lesen Sie deren Antworten.

In diesem Artikel7 Abschnitte

Bevor Sie beginnen

Diese Seite beschreibt, wie man Formulare sendet und deren Antworten mit einem Hub-Key auswertet. Die Wege dazu befinden sich unter https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

Anrufe

AnrufWas es tut
GET /forms/templatesListe der Formvorlagen
POST /formsEs wird eine Formularseite erstellt – diese ist jedoch noch nicht veröffentlicht.
PUT /forms/<form_id>/publishEs wird veröffentlicht – und anschließend an die Empfänger gesendet.
GET /forms?filter=allListe der Formen des Falles
GET /forms/<form_id>Liest eine Formularzeile.
PUT /forms/<form_id>Es wird der Name, das Zahlungsdatum sowie die Benachrichtigungen oder Empfänger geändert.
DELETE /forms/<form_id>Löschen Sie es – zusammen mit den dazugehörigen Antworten.
GET /forms/<form_id>/responsesListet seine Antworten auf.
GET /forms/<form_id>/responses/<response_id>Liest eine Antwort
DELETE /forms/<form_id>/responses/<response_id>Löscht die Antwort einer Person, damit diese sie wieder ausfüllen kann.

Eine Form wird in zwei Schritten erstellt: Zuerst wird sie erstellt, anschließend wird sie veröffentlicht. Bis sie veröffentlicht ist, können die Empfänger die Form nicht sehen – und niemand erfährt davon.

Formular erstellen

GET /forms/templates listet die veröffentlichten Formulare von TemplatenVorlage Ein wiederverwendbarer Feed-Beitrag, ein Formular, eine elektronische Signatur, eine Notiz oder eine Aufgabe, die in der Bibliothek aufbewahrt und in Fälle kopiert wird. auf – sortiert nach Alter. Für jedes Template werden die Werte asset_id, title, description, due_mins angegeben (wie viele Minuten nach dem Versand ist das Template fällig). Zusätzlich werden noch die Werte rrule, notifications und instant_notify angegeben.

POST /forms akzeptiert Folgendes als Eingabe:

FeldWas es tutErforderlichStandard
nameDer Titel des Formulars: Buchstaben, Zahlen, Leerzeichen sowie & ' - _ ( ) . /. Keine Kommas oder Kolonnen.Ja.–
duration{"due_date": "2026-10-09T17:00:00-04:00", "rrule": "FREQ=MONTHLY"} Die Fälligkeitsdatum muss mit der jeweiligen Zeitzonenverschiebung versehen werden. rrule Eine Wiederholungsregel ist optional. zoneinfo Die Zeitzone, in der die Wiederholung stattfindet – beispielsweise America/New_York – ist ebenfalls optional. Ohne diese Zeitzone wird die Zeitzone des Zentrums der Wiederholung beibehalten, zu dem Zeitpunkt und an dem die Uhren umgestellt werden.Ja.–
participants_idsDie Personen, die diese Daten eingeben: Die Benutzeridentitäten der Personen, die an dem Fall beteiligt sind, aus dem Bereich GET /teamNein, aber es ist notwendig, die Informationen zu veröffentlichen.Niemand
template{"owner": "host", "template_id": "<asset_id>"} Um ein Dokument eines Templates zu verwenden.Nein.Keine.
descriptionEine Notiz, die zusammen mit dem Formular angezeigt wird.Nein.Das Template…
notificationsErinnerungen: {"names": ["days", "hours"], "values": [-1440, -60]} – jede Zahl gibt die Anzahl der Minuten vor dem Fälligkeitsdatum an.Nein.Das Template – oder gar nichts.
instant_notifyfalse Es werden keine Anfragen bei der Veröffentlichung gesendet – nur die Erinnerungen werden übermittelt.Nein.Das Template oder true

Ein Template bringt sein Dokument, seine Beschreibung, die Erinnerungen sowie instant_notify mit sich – aber nicht die Frist oder die Wiederholungsmöglichkeit. Berechnen Sie die due_date aus der due_mins-Zahl. Senden Sie anschließend die rrule-Zahl, falls vorhanden.

curl -X POST https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Case intake form", "duration": {"due_date": "2026-10-09T17:00:00-04:00"}, "participants_ids": ["cu-4f1c2a9e8b7d60"], "template": {"owner": "host", "template_id": "form::20260915101500_3c2b1a0f9e8d70"}}'

Es beantwortet die Frage. 201 Mit dem… form_id. Das Dokument des Templates wird im Hintergrund kopiert. Lesen Sie das Formular bis es keine weiteren Informationen mehr enthält. copying, Dann veröffentlichen Sie es.

Um Ihr eigenes Dokument zu senden, erstellen Sie zunächst die Anfrageformular ohne den template-Tag. Laden Sie anschließend ein PDF-Dokument als Anfrage hoch. Warten Sie bis das Dokument fertig ist. Weitere Informationen finden Sie in „Hochladen und Anhängen von Dateien mit einem Hub-Schlüssel“.

Veröffentlichung

PUT /forms/<form_id>/publish nimmt keinen Wert an und gibt stattdessen 200 zurück.

  • Jeder Empfänger erhält eine E-Mail mit der Anweisung, das Formular auszufüllen. Falls der Empfänger keine E-Mail erhalten hat, wird ihm auch eine SMS geschickt. Das geschieht sofort, es sei denn… instant_notify ist false. Es erscheint auf ihren… Was zu tun ist:Machen Die Liste auf einem Koffer mit Dingen, die auf Sie warten, wie zum Beispiel auszufüllende Formulare, zu unterschreibende Dokumente oder zu bestätigende Termine. Und auch in den Benachrichtigungen auf ihrem Portal.
  • Die Erinnerungen werden jedes Mal verschickt. notifications Noch immer liegt der Vorsprung weiterhin vor. Nichts wird rechtzeitig gesendet, und Antworten werden erst nach der entsprechenden Zeit angenommen.
  • Eine wiederkehrende Formel geht zu ihrer nächsten Fälligkeitsdatum. Die Antworten sind klar definiert, und alle Personen, die an dieser Formel beteiligt sind, werden gleichzeitig erneut befragt – es sei denn, instant_notify ist gleich false.
  • Jemand, der aus dem Fall ausgeschlossen wurde, wird aus der Liste der betroffenen Personen entfernt.

Der Dokumenteneintrag kann erst dann geändert werden, wenn das Formular veröffentlicht wurde. Der Name des Dokumentes, der Frist, die Benachrichtigungen, die Empfänger sowie die Beschreibung des Dokuments können nicht mehr geändert werden. PUT /forms/<form_id>; Eine erneute Anfrage ohne weitere Informationen. zoneinfo Es wird die bereits vorhandene Zeitzone beibehalten. Wenn die Fälligkeitsdatum ändert, werden die Anfragen erneut an alle gesendet, die noch nicht geantwortet haben. Die Personen, die man hinzufügt, erhalten die Anfragen ebenfalls sofort zugesandt. instant_notify false, Niemand geht weiter, bis die Erinnerungen kommen.

Antworten lesen

GET /forms/<form_id>/responses listet die Antworten jedes Einzelnen auf, wobei die ältesten Antworten zuerst angezeigt werden. Eine wiederkehrende Formel zeigt nur die Antworten für den aktuellen Tag an. Die Antworten von früheren Tagen werden jedoch weiterhin durch ihre response_id-Attribute identifiziert.

{
  "data": {
    "items": [
      {
        "response_id": "response::20261003153012_9f8e7d6c5b4a30",
        "parent_id": "form::20261002150000_1a2b3c4d5e6f70",
        "user_id": "cu-4f1c2a9e8b7d60",
        "created_on": "2026-10-03T15:30:12+00:00",
        "response": {
          "format": "https://pspdfkit.com/instant-json/v1",
          "formFieldValues": [
            {"v": 1, "type": "pspdfkit/form-field-value", "name": "client_name", "value": "Jane Sample"},
            {"v": 1, "type": "pspdfkit/form-field-value", "name": "accident_date", "value": "2026-09-14"}
          ]
        }
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/forms/form::20261002150000_1a2b3c4d5e6f70/responses"
  }
}
  • formFieldValues enthält die Informationen, die von der Person im Feld name eingetragen wurden. Eine Unterschrift oder ein Bild gehören zu den Elementen unter annotations und attachments.
  • Die eigene Lesung des Formulars zeigt an, wer die Antwort abgegeben hat: responses weist jedem Benutzer eine ID zu, die mit seinem response_id übereinstimmt.
  • Wenn jemand die Unterlagen einreicht, wird dem Personal, das mit dem Fall betraut ist, dasselbe mitgeteilt, wie wenn er die Unterlagen selbst eingereicht hätte.

Das Löschen der Antwort einer Person, wobei {"user_id": "<their ID>"} als Inhalt verwendet wird, führt dazu, dass die Form wieder auf der Liste der Aufgaben angezeigt wird. Niemand wird darüber informiert. Eine Schlüsselkarte kann eine Form selbst nicht ausfüllen.

Angebotsformulare

GET /forms benötigt filter.

filterWas es auflistet
allJede Form der Darstellung – einschließlich der noch nicht veröffentlichten Formen – wird in der Reihenfolge des Alters angezeigt.
selfDie virtuelle Assistentin wird über eine der Ihrer Schlüssel verwendeten Methoden gesendet – oder durch Automatismen.
completed, uncompletedDie Formulare, die der Anrufer ausfüllen musste, sind immer leer – für eine Schlüsselkarte gilt das ebenfalls.

Jeder Form enthält ihre form_id-, name-, participants_ids-, due_date- und published-werte (einmal veröffentlicht: 1). Zudem enthält jede Form auch die Werte von responses und responses_ct sowie das Dokument, das unter media angezeigt wird.

DELETE /forms/<form_id> kann ein Formular jederzeit mit allen dazugehörigen Antworten löschen und es somit von der Liste der zu erledigenden Aufgaben entfernen. Niemand wird davon informiert.

Wenn ein Anruf abgelehnt wird

StatusmessageWarum
400SchemaFieldsExceptionEs fehlt ein Feld oder es ist das Feld ungültig. Beispielsweise kann es zu einem Fehler kommen, wenn in name eine Komma verwendet wird. Es kann auch vorkommen, dass die Fälligkeit ohne eine entsprechende Versetzung angegeben wird. Oder es kann sein, dass jemand nicht im Fall enthalten ist. errors gibt den Namen des Feldes an.
400SchemaFieldsException, wobei ItemCopyNotAllowedException bei template liegt.Das Template ist nicht veröffentlicht, steht der Rolle der Bots nicht offen – oder seine Dateien werden noch bearbeitet.
403PublishAlreadyPublishedExceptionEs ist bereits veröffentlicht worden.
403PublishAlreadyAnsweredExceptionJemand hat das bereits beantwortet.
403PublishMediaMissingExceptionEs gibt bisher noch keine entsprechenden Dokumente.
403PublishMediaNotReadyExceptionSein Dokument wird immer noch kopiert oder konvertiert.
403PublishMediaFailedExceptionSein Dokument konnte nicht konvertiert werden.
403PublishDueTimePassedExceptionDie Fälligkeitstermin ist bereits verstrichen.
403PublishRecipientsMissingExceptionEs hat niemanden, dem man es übergeben könnte.
403BotNotAllowedExceptionEine Schlüsselkarte versuchte, das Loch zu füllen.
403CaseClosedExceptionDer Fall ist abgeschlossen.
404ItemNotFoundExceptionDie entsprechende Formulierung oder Antwort existiert nicht.

Für den Fehlermeldungsinhalt sowie die übrigen Codewerte siehe Verarbeitung von API-Fehlern und Statuscodes.

Verwandte Artikel

Verstehen Sie, was die API leisten kann.Erfahren Sie, welche Funktionen eine Verwaltungstaste und eine Hub-Taste jeweils haben, warum jede Taste als virtueller Assistent fungiert und wo Sie die vollständige technische Auflistung finden.IntegrationenMit einem Hub-Schlüssel können Sie elektronische Signaturen senden und lesen.Erstellen Sie eine elektronische Signatur für einen Fall anhand einer Vorlage, wählen Sie aus, wer welches Feld unterschreibt, veröffentlichen Sie ihn zur Unterzeichnung und laden Sie die gesperrte Kopie herunter, sobald alle unterschrieben haben.IntegrationenDateien mit einem Hub-Schlüssel hochladen und anhängenEine Upload-Adresse abrufen, eine Datei hochladen, diese an einen Beitrag, eine Notiz, eine Aufgabe, ein Formular oder eine elektronische Signatur anhängen und die Akten eines Falls herunterladen.IntegrationenAPI-Fehler und Statuscodes behandelnLesen Sie den Fehlertext, was 400, 401, 403, 404, 500 und 503 bedeuten und warum ein Element, dessen Schlüssel nicht angezeigt werden kann, 404.Integrationen