Central de ajudaIntegrações

Para: Administradores

Envie formulários e leia respostas com uma chave central.

Crie um formulário sobre um caso a partir de um modelo, publique-o para as pessoas que devem preenchê-lo e leia as respostas delas.

Neste artigo7 seções

Antes de começar

Esta página aborda o envio de formulários e a leitura das respostas deles, utilizando uma chave de hub. Os caminhos estão indicados em https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

Chamadas

ChamarO que faz
GET /forms/templatesLista dos seus modelos de formulários
POST /formsCria um formulário para o caso, que ainda não foi publicado.
PUT /forms/<form_id>/publishPublica-o, e assim o envia aos destinatários.
GET /forms?filter=allLista as formas do caso.
GET /forms/<form_id>Lê um formulário
PUT /forms/<form_id>Modifica o nome, a data de vencimento, os lembretes ou os destinatários.
DELETE /forms/<form_id>Apague-o, junto com as respostas relacionadas a ele.
GET /forms/<form_id>/responsesLista de suas respostas
GET /forms/<form_id>/responses/<response_id>Lê uma das respostas.
DELETE /forms/<form_id>/responses/<response_id>Apaga a resposta de uma pessoa, para que ela possa preencher o espaço novamente.

O formulário é criado em dois passos: primeiro, ele é criado; depois, é publicado. Até que seja publicado, os destinatários não conseguem ver o formulário, e ninguém fica sabendo disso.

Criar um formulário

GET /forms/templates Lista do seu formato publicado Modelos/FormuláriosModelo Um formulário, postagem, assinatura eletrônica, nota ou tarefa reutilizável, armazenado na Biblioteca e copiado para as pastas., Os mais antigos primeiro, sendo cada um deles… asset_id, title, description, due_mins (Quantos minutos após o envio do documento, ele estará pronto para ser entregue?) rrule (Suas repetições) notifications E… instant_notify.

POST /forms aceita os seguintes valores:

CampoO que fazObrigatórioPadrão
nameO título do formulário. Letras, números, espaços e & ' - _ ( ) . /; sem vírgulas ou hífenes.Sim—
duration{"due_date": "2026-10-09T17:00:00-04:00", "rrule": "FREQ=MONTHLY"}. A data de vencimento precisa ter o deslocamento do fuso horário correspondente. rrule, uma regra de repetição, é opcional. zoneinfo, o fuso horário em que a repetição ocorre, como America/New_York, também é opcional. Sem essa informação, a repetição manterá o fuso horário do seu dispositivo, no mesmo horário e no dia em que ocorre a mudança de hora.Sim—
participants_idsAs pessoas que preenchem esses dados são os IDs de usuário das pessoas envolvidas no caso, com valor começando por GET /team.Não, mas era necessário publicá-lo.Ninguém
template{"owner": "host", "template_id": "<asset_id>"} Para usar o documento de um modelo.NãoNenhum
descriptionUma nota anexada ao formulárioNãoO modelo utilizado…
notificationsLembrâncias: {"names": ["days", "hours"], "values": [-1440, -60]}. Cada valor indica o número de minutos restantes até a data de vencimento.NãoO modelo, ou nada.
instant_notifyfalse Não enviar nenhum pedido durante o processo de publicação. Apenas os lembretes serão enviados.NãoO modelo, ou true

O modelo inclui o documento, a descrição, as lembranças e o parágrafo instant_notify. No entanto, não inclui a data de vencimento ou informações sobre repetição. É necessário calcular o valor de due_date a partir de due_mins. Se houver algum parágrafo rrule, então deve-se enviá-lo.

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"}}'

Isso responde a 201 com form_id. O documento do modelo é copiado em segundo plano: leia o formulário até que não haja mais copying, e então publique-o.

Para enviar o seu próprio documento, crie o formulário sem o elemento template. Carregue um PDF como o documento e aguarde até que este esteja pronto. Veja Carregar e anexar arquivos usando uma chave de hub.

Publicação

PUT /forms/<form_id>/publish não recebe nenhum corpo e responde a 200.

  • Cada destinatário recebe um e-mail com um pedido para preencher o formulário. Caso não tenha um endereço de e-mail confirmado, ele também recebe uma mensagem de texto imediatamente. instant_notify É false. Ele aparece nelas. O que precisa ser feitoFaçam A lista em uma maleta contém coisas que você precisa fazer, como formulários para preencher, documentos para assinar ou eventos para confirmar. E também nas notificações do seu portal.
  • Os lembretes são enviados a cada vez, em notifications, ainda antes do prazo estipulado. Nada é enviado no momento certo, e as respostas só são aceitas depois disso.
  • A forma de repetição avança para a sua próxima data de vencimento, em cada um dos casos. As respostas são claras, e todos os participantes são questionados novamente, a menos que instant_notify seja igual a false.
  • Alguém que está fora do caso é excluído da lista.

O documento não pode ser alterado uma vez que o formulário é publicado. O nome do documento, a data de vencimento, os lembretes, os destinatários e a descrição do documento podem ser modificados. Com PUT /forms/<form_id>, um envio repetido sem zoneinfo mantém o fuso horário atual do documento. Ao alterar a data de vencimento, os lembretes são enviados novamente para todos aqueles que ainda não responderam. As pessoas que você adiciona também recebem o documento imediatamente. Com instant_notify e false, nenhum dos elementos é enviado até que os lembretes sejam ativados.

Respostas de leitura

GET /forms/<form_id>/responses lista a resposta de cada pessoa, com as mais antigas em primeiro lugar. Um formulário repetitivo listará apenas as respostas da data atual; as respostas de datas anteriores continuarão sendo exibidas pelo seu response_id.

{
  "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 armazena cada campo que a pessoa preencheu, de acordo com os valores definidos no campo correspondente name. Uma assinatura ou desenho está incluído nos campos annotations e attachments.
  • A leitura feita pelo próprio formulário indica quem foi o responsável pela resposta: responses associa o ID do usuário de cada pessoa ao seu response_id.
  • Quando alguém envia o documento, os funcionários responsáveis pelo caso são informados, da mesma forma que se tivessem enviado o documento por conta própria.

Apagar a resposta de uma pessoa, utilizando o {"user_id": "<their ID>"} como corpo da mensagem, faz com que o formulário volte para a lista de tarefas daquela pessoa. Ninguém é informado sobre isso. Uma chave não pode preencher um formulário por conta própria.

Formulários de listagem

GET /forms precisa de filter.

filterO que está listado
allTodas as formas apresentadas no caso, incluindo aquelas que ainda não foram publicadas, são listadas, com as mais recentes em primeiro lugar.
selfO assistente virtual é enviado por qualquer um dos seus dispositivos, ou por meio de automações.
completed, uncompletedOs formulários que o chamante foi solicitado a preencher estão sempre vazios.

Cada formulário contém seus valores form_id, name, participants_ids, due_date, published (e 1, uma vez publicado), responses, responses_ct, além do documento associado a cada formulário, que está localizado em media.

DELETE /forms/<form_id> pode excluir um formulário a qualquer momento, juntamente com as respostas dele. Além disso, o formulário é removido da lista de tarefas de todos. Ninguém é informado sobre isso.

Se uma chamada for recusada

StatusmessagePor que
400SchemaFieldsExceptionO campo está ausente ou inválido. Por exemplo, pode haver uma vírgula em name, ou a data de vencimento não possui um deslocamento, ou ainda, pode haver alguém que não está relacionado ao caso em questão. errors indica o nome do campo.
400SchemaFieldsException, com ItemCopyNotAllowedException em templateO modelo não foi publicado, não está disponível para o papel dos bots, ou seus arquivos ainda estão sendo processados.
403PublishAlreadyPublishedExceptionJá foi publicado.
403PublishAlreadyAnsweredExceptionAlguém já respondeu a essa pergunta.
403PublishMediaMissingExceptionAinda não tem nenhum documento relacionado a isso.
403PublishMediaNotReadyExceptionSeu documento ainda está sendo copiado ou convertido.
403PublishMediaFailedExceptionSeu documento não conseguiu ser convertido.
403PublishDueTimePassedExceptionA data de vencimento já passou.
403PublishRecipientsMissingExceptionNão tem ninguém para quem possa enviá-lo.
403BotNotAllowedExceptionUma chave tentou preencher o espaço vazio.
403CaseClosedExceptionO caso foi encerrado.
404ItemNotFoundExceptionO formulário ou a resposta em questão não existe.

Para informações sobre o corpo do erro e os demais códigos de erro, consulte Como lidar com erros da API e códigos de status.

Artigos relacionados

Entenda o que a API pode fazer.Saiba o que uma chave de gerenciamento e uma chave central podem fazer, por que cada chave funciona como um Assistente Virtual e onde encontrar a lista completa de especificações técnicas.IntegraçõesEnvie assinaturas eletrônicas e leia assinaturas com uma chave central.Crie uma solicitação de assinatura eletrônica para um caso a partir de um modelo, escolha quem assina cada campo, publique-a para assinatura e baixe a cópia bloqueada assim que todos tiverem assinado.IntegraçõesFaça upload e anexe arquivos com uma chave de hub.Obtenha um endereço de upload, carregue um arquivo, anexe-o a uma publicação, nota, tarefa, formulário ou assinatura eletrônica e baixe os arquivos de um caso.IntegraçõesLidar com erros e códigos de status da APILeia o corpo da mensagem de erro, o que significam os códigos 400, 401, 403, 404, 500 e 503 e por que um item que sua chave não consegue ver responde ao erro 404.Integrações