Participantes

Cadastro, busca e atualização das pessoas que enviam documentos numa competência, incluindo seus dependentes.

Rotas

método e rota	o que faz
`POST /v1/api/competencies/participants/search`	`Search participants in a competency`
`POST /v1/api/competencies/{competencyId}/participant`	`Create participant using API`
`POST /v1/api/competencies/{competencyId}/participants/search`	`Search participants using API`
`POST /v1/api/participants/search`	`Search participations by CPF using API`
`PATCH /v1/api/competencies/{competencyId}/participants/{competencyParticipantId}/status`	`Update participant status`
`POST /v1/api/competencies/{competencyId}/participants/{participantId}/authenticated-link`	`Gerar link autenticado para envio de documentação do participante`
`POST /v1/api/competencies/{competencyId}/participants/{participantId}/input-documents`	`Answer an input field for a participant using API`
`GET /v1/api/participants/{participantId}`	`Fetch competency participant`
`GET /v1/api/participants/{participantId}/document-requests`	`Consultar grupos e documentos solicitados ao participante`
`PATCH /v1/api/participants/{participantId}`	`Update participant using API`
`GET /v1/api/participants/{participantId}/custom-fields`	`Buscar campos customizados de um participante com base no id do participante`
`PATCH /v1/api/participants/{participantId}/custom-fields`	`Atualizar campos customizados de um participante com base no id do participante`
`POST /v1/api/participants/{participantId}/dependents`	`Add dependents to participant using API`
`DELETE /v1/api/competencies/{competencyId}/participants/{participantId}`	`Remove a participant using API`

Concluir o envio, justificar documento, pedir revisão e excluir um dependente em nome do participante estão em Ações em nome do participante.

Buscar um participante

curl 'https://api.dynadok.com/v1/api/participants/6500a1b2c3d4e5f600000002' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": {
    "_id": "6500a1b2c3d4e5f600000002",
    "name": "João Silva",
    "cpf": "12345678909",
    "cnpj": null,
    "dateOfBirth": "1990-04-17",
    "gender": "MALE",
    "customFields": [{ "name": "matricula", "value": "A-1024" }],
    "status": "PENDING",
    "dependents": []
  }
}

dependents traz a mesma forma resumida — _id, name, cpf, cnpj, type, dateOfBirth, gender, customFields e documentGroup. Cadastro de dependentes é feito por POST .../participants/{participantId}/dependents, com type valendo CHILD, GRANDPARENT, PARTNER, SPOUSE, STEPCHILD, SIBLING, STEPMOTHER, MOTHER, STEPFATHER, FATHER, OTHER ou NOT_REQUIRED. gender, aqui e em PATCH /v1/api/participants/{participantId}, aceita MALE ou FEMALE.

Em customFields, value é texto, ou lista de textos quando o campo personalizado é de multisseleção ({ "name": "idiomas", "value": ["Inglês", "Espanhol"] }). O mesmo vale em GET .../custom-fields e nos dependentes.

Criar participante (POST /v1/api/competencies/{competencyId}/participant) exige name, email e type (PF ou PJ); os demais campos do cadastro completo estão na Referência.

Listar os participantes de uma competência

POST /v1/api/competencies/{competencyId}/participants/search pagina os participantes de uma competência. Os filtros vão no corpo da requisição, nunca na URL: CPF, CNPJ e o texto de busca são dado pessoal, e a URL fica gravada por inteiro em logs de acesso.

curl --request POST 'https://api.dynadok.com/v1/api/competencies/6500a1b2c3d4e5f600000004/participants/search' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --data '{ "cpf": "12345678909", "page": 1, "perPage": 20 }'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": [
    {
      "_id": "6500a1b2c3d4e5f600000002",
      "name": "João Silva",
      "email": "joao.silva@example.com",
      "cpf": "12345678909",
      "cnpj": null,
      "gender": "MALE",
      "dateOfBirth": "1990-04-17",
      "type": "PF",
      "phone": null,
      "customFields": { "matricula": "A-1024" },
      "status": "PENDING"
    }
  ],
  "meta": { "page": 1, "perPage": 20, "total": 1, "lastPage": 1 }
}

Nenhum campo do corpo é obrigatório — sem filtro, a rota lista todos os participantes da competência. cpf e cnpj filtram pelo documento, com ou sem máscara (valor inválido responde 400); query faz busca livre por nome, e-mail e CPF do participante e por nome e CPF dos dependentes; e orderByColumn/orderByDirection ordenam o resultado.

page e perPage precisam ser inteiros a partir de 1; sem eles, vem a primeira página com 10 itens. 0, negativo, fracionário ou texto respondem 400 como erro de validação — a API não corrige o valor em silêncio.

Encontrar as participações de um CPF

POST /v1/api/participants/search procura um CPF em todos os projetos da empresa e devolve cada participação (o participante numa competência). O CPF vai no corpo, nunca na URL, com ou sem máscara.

curl --request POST 'https://api.dynadok.com/v1/api/participants/search' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --data '{ "cpf": "123.456.789-09" }'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": [
    {
      "_id": "6500a1b2c3d4e5f600000002",
      "name": "João Silva",
      "cpf": "123.456.789-09",
      "status": "PENDING",
      "createdAt": "2026-09-23T12:00:00.000Z",
      "project": { "_id": "6500a1b2c3d4e5f600000003", "status": "PUBLISHED" },
      "competency": { "_id": "6500a1b2c3d4e5f600000004", "publicTitle": "Admissão 2026.2" }
    }
  ]
}

O _id de cada item é o participantId usado em document-requests e em input-documents.
A lista vem da participação mais recente para a mais antiga, sem paginação.
CPF inválido responde 400; CPF sem participação responde lista vazia.
Esta rota só aceita chave legada: chave escopada recebe 403.

Consultar os documentos solicitados ao participante

participantId é o id do participante na competência, devolvido ao cadastrá-lo — o mesmo usado em GET /v1/api/participants/{participantId}/documents e GET /v1/api/participants/{participantId}/documents-data.

curl 'https://api.dynadok.com/v1/api/participants/6500a1b2c3d4e5f600000002/document-requests' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

A resposta usa o envelope padrão, com data como array de grupos de documentos. Exemplo parcial, mostrando um slot de RG que aceita CNH como substituto:

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": [
    {
      "_id": "6500a1b2c3d4e5f600000007",
      "documentRequests": [
        {
          "competencyDocumentId": "6500a1b2c3d4e5f60000000a",
          "type": "RG",
          "acceptedDocuments": [
            {
              "role": "MAIN",
              "type": "RG",
              "title": "RG",
              "declarationId": null,
              "customDocumentTypeId": null
            },
            {
              "role": "SUBSTITUTE",
              "type": "DECLARACAO_DO_CLIENTE",
              "title": "Declaração de residência",
              "declarationId": "6500a1b2c3d4e5f60000000b",
              "customDocumentTypeId": null
            }
          ]
        }
      ]
    }
  ]
}

Cada grupo traz _id, title, instructions, type (OWNER ou THIRD_PARTY), juridicNature (PF ou PJ), order, requiresRelationship, cpfRequiredCondition (ALL, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL ou NOT_REQUIRED), cpfRequiredForAge, isAgeRequired, isGenderRequired, documentRequests e dependents.

Cada item de documentRequests é um slot e traz competencyDocumentId, name, alternativeName, type, category (DOCUMENT ou INPUT), order, isRequired, description, descriptionLink, allowMultipleUploads, minMultipleUploads, maxMultipleUploads, acceptJustification, autoEmission e os arrays allowedFileExtensions, substituteDocumentTitles, acceptedDocuments, rules e uploadedDocuments. O padrão de allowedFileExtensions é ["pdf","png","jpg","jpeg","jfif","webp","heic","heif"].

acceptedDocuments informa os documentos aceitos no conteúdo do arquivo. Cada item tem role, type, title, declarationId e customDocumentTypeId.

role responde só uma pergunta: qual o papel do item neste slot.

`role`	significado
`MAIN`	é o documento pedido pelo slot
`SUBSTITUTE`	é aceito no lugar dele

A natureza do item — documento comum, declaração ou tipo customizado — não vem de role. Vem do type, que é sempre o tipo do documento no catálogo e nunca null:

`type`	natureza
`DECLARACAO_DO_CLIENTE`	declaração
`TIPO_DOCUMENTO_CUSTOMIZADO`	tipo customizado
qualquer outro	documento comum

Esses dois tipos são compartilhados por todos os itens da sua categoria, então eles dizem que é uma declaração, mas não qual. Para isso existem os ids, que chegam sempre, com null quando não se aplicam:

id	o que diz
`declarationId` preenchido	qual declaração cadastrada
`customDocumentTypeId` preenchido	qual tipo customizado

type especializado com id null é um caso válido

Um item pode vir com type: "DECLARACAO_DO_CLIENTE" e declarationId: null. Isso não significa documento comum: significa uma declaração que a empresa pediu sem amarrar a uma declaração cadastrada. O envio é idêntico ao de qualquer outro item — pelo competencyDocumentId do slot.

Leia a natureza pelo type, e use os ids só para saber qual.

A regra é a mesma em qualquer role e a mesma do Catálogo.

Esses dois ids aparecem com os mesmos nomes no Catálogo, que lista todas as declarações e todos os tipos customizados da empresa — é por ali que você descobre o universo disponível, não só o que caiu num slot.

O id daqui pode não estar no catálogo

O catálogo lista o que a empresa pode pedir hoje; este slot guarda o que foi configurado quando foi configurado. Se a declaração foi arquivada ou removida depois, ou o tipo customizado voltou a rascunho, o id continua aparecendo aqui e não aparece no catálogo.

Nada disso invalida o slot: ele continua sendo listado, aceitando envio, e os arquivos já enviados continuam sendo lidos e baixados. Use o competencyDocumentId para enviar, como sempre.

O envio é identificado pelo competencyDocumentId

Use o competencyDocumentId de cada item desta consulta no envio:

{
  "competencyDocumentId": "6500a1b2c3d4e5f60000000a"
}

É o campo que identifica o documento solicitado. Para documento de dependente, envie também o dependentId.

Os campos do envio de arquivo são exatamente files, competencyDocumentId, dependentId, rules e extraData — a lista completa está em Enviar o documento de um participante. Slots de campo de formulário (type terminado em _INPUT) não recebem arquivo: são respondidos por input-documents.

Cada item de uploadedDocuments traz _id, documentStatus (PENDING, PROCESSING, SENT, REJECTED ou IN_REVIEW), infoPreview, createdAt, value, valueJSON, uploadGroupId e aiDocumentSplitId. Em slot de campo de formulário, value é a resposta em texto ("Não") e valueJSON é o mesmo valor serializado em JSON ("\"Não\""); em slot de arquivo, value é null.

Cada item de dependents traz _id, name, cpf, cnpj, dateOfBirth (YYYY-MM-DD), type (CHILD, GRANDPARENT, PARTNER ou SPOUSE), gender (MALE ou FEMALE), competencyDocumentGroupId, cpfRequired e documentRequests, no mesmo formato dos slots descritos acima.

Responder um campo de formulário

Alguns slots de document-requests não pedem arquivo, e sim uma resposta: têm type igual a TEXT_INPUT, LONG_TEXT_INPUT, SELECTION_OPTION_INPUT, NUMBER_INPUT, MONETARY_VALUE_INPUT ou DATE_INPUT. Identifique-os pelo type: category é INPUT nos slots mais novos, mas pode vir null em configurações antigas. Eles são respondidos com POST /v1/api/competencies/{competencyId}/participants/{participantId}/input-documents.

curl --request POST 'https://api.dynadok.com/v1/api/competencies/6500a1b2c3d4e5f600000004/participants/6500a1b2c3d4e5f600000002/input-documents' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --data '{
    "competencyDocumentId": "6500a1b2c3d4e5f60000000c",
    "value": "Não",
    "dependentId": null
  }'

Para responder um campo de um dependente, envie o dependentId dele no lugar de null (ou omita o campo, no caso do participante):

{
  "competencyDocumentId": "6500a1b2c3d4e5f60000000d",
  "value": "2026-03-15",
  "dependentId": "6500a1b2c3d4e5f600000008"
}

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": {
    "_id": "6500a1b2c3d4e5f60000000e",
    "type": "SELECTION_OPTION_INPUT",
    "documentStatus": "SENT"
  }
}

value é sempre texto. Em DATE_INPUT, use exatamente YYYY-MM-DD com uma data que existe (2026-03-15); 31/12/2020, data com horário ou 2026-02-30 respondem 400.
Em SELECTION_OPTION_INPUT, value precisa ser exatamente uma das opções do slot, listadas em rules[].inputValue (regra do tipo SELECTION_OPTION_INPUT) na consulta de document-requests.
Se o slot é obrigatório, value vazio ou só com espaços responde 400 (O valor do campo é obrigatório). Em campo não obrigatório, inclusive SELECTION_OPTION_INPUT e DATE_INPUT, value: "" é aceito e deixa a resposta em branco.
documentStatus volta SENT. Se a fórmula de validação da empresa depende desse campo, volta PROCESSING até a fórmula rodar.
Responder de novo substitui a resposta anterior na consulta: uploadedDocuments do slot passa a trazer só a nova, e os itens condicionais são avaliados pela resposta mais recente.
Em slots antigos (category null), valueJSON pode vir null mesmo com resposta gravada; leia sempre value.
Itens condicionais que dependem da resposta passam a aparecer na próxima consulta de document-requests. Nenhum webhook avisa que itens foram liberados: consulte novamente após responder.
Não é possível responder enquanto o participante estiver aprovado ou reprovado.

Gerar um link autenticado para o participante

Gera um link que abre a tela de envio de documentos já com o participante autenticado, sem pedir login.

curl --request POST 'https://api.dynadok.com/v1/api/competencies/6500a1b2c3d4e5f600000004/participants/6500a1b2c3d4e5f600000002/authenticated-link' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": {
    "participantId": "6500a1b2c3d4e5f600000002",
    "competencyId": "6500a1b2c3d4e5f600000004",
    "authenticatedLink": "https://app.dynadok.com/auth/sso/callback?sessionId=3f9a..."
  }
}

Validade de 5 minutos e uso único

O link vale por 5 minutos a partir da geração e só pode ser aberto uma vez. Depois de expirado ou já usado, ele mostra um erro de autenticação e não dá mais acesso. Gere o link na hora em que o participante for abrir, por exemplo quando ele clica no botão do seu sistema. Não o envie por e-mail nem o guarde para usar depois.

Cada chamada gera um link novo. Gerar outro não invalida um link anterior que ainda não foi usado.
Depois que o participante abre o link, a sessão dele no portal segue normalmente. Os 5 minutos valem só para abrir o link.
O domínio do link é o do portal configurado para a empresa.
400 se a competência não é da empresa, ou se o participante não está nessa competência.

Remover um participante

Exclusão em cascata

O participante sai da competência junto com os dependentes e todos os documentos enviados para eles.

curl --request DELETE 'https://api.dynadok.com/v1/api/competencies/6500a1b2c3d4e5f600000004/participants/6500a1b2c3d4e5f600000002' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": {
    "participantId": "6500a1b2c3d4e5f600000002",
    "deletedDocumentsCount": 5
  }
}

deletedDocumentsCount é quantos documentos foram excluídos, somando os do participante e os dos dependentes.
Repetir a chamada para um participante já removido responde 200 com deletedDocumentsCount: 0.
Participante inexistente, de outra competência ou de outra empresa responde 404.
Para cadastrar a mesma pessoa de novo, chame POST /v1/api/competencies/{competencyId}/participant depois da remoção.
Com chave escopada, exige perm:participant:delete (Excluir participantes).

Erros típicos

Ver Envelope e erros para o formato geral. Na listagem de participantes, page ou perPage fora de inteiro ≥ 1 responde 400 como erro de validação, assim como um cpf ou cnpj inválido. Em PATCH .../participants/{competencyParticipantId}/status, um status fora de PENDING, STARTED, APPROVED_BY_AI, IN_ANALYSIS, APPROVED ou DISAPPROVED responde 400 como erro de validação.

Em GET /v1/api/participants/{participantId}/document-requests, participante inexistente responde 404.

Em POST .../input-documents:

400 se o competencyDocumentId é um slot de arquivo (a mensagem indica a rota de envio de documentos), ou se não pertence à competência.
400 com opção inválida em SELECTION_OPTION_INPUT; a mensagem lista as opções aceitas.
400 com data fora do formato YYYY-MM-DD em DATE_INPUT.
400 se o dependentId não bate com o grupo do slot (dependente ausente, inválido, ou slot que não é de dependentes).
400 se o participante não pertence à competência informada.
400 se o participante já está aprovado ou reprovado (mensagem O status do participante não permite o envio de documentos: APPROVED).
404 para competência ou participante inexistente.

Participantes

Rotas​

Buscar um participante​

Listar os participantes de uma competência​

Encontrar as participações de um CPF​

Consultar os documentos solicitados ao participante​

Responder um campo de formulário​

Gerar um link autenticado para o participante​

Remover um participante​

Erros típicos​