getFormsDataByMarker
Obter os envios de um formulário pelo seu marcador.
Descrição
Busca os envios do formulário identificado por marker. Resolve para um IFormsByMarkerDataEntity, não para um array: os registros ficam em items, e a contagem, em total.
Apenas formulários que um administrador marcou como públicos podem ser lidos dessa forma. Os formulários são privados por padrão, e ler um formulário privado retorna 403 ("This form's submissions are not publicly readable"). Um marcador desconhecido retorna { items: [], total: 0 }.
.getFormsDataByMarker(
,
,
,
,
,
,
);
Esquema de parâmetros
Esquema
marker(obrigatório): string
Marcador do formulário.
exemplo: "contact_form"
formModuleConfigId(obrigatório): number
ID da configuração do módulo de formulário.
exemplo: 4
body: IFormsDataFilter
Filtro dos registros a retornar. Todos os campos são opcionais; um campo omitido ou vazio não é aplicado.
exemplo:
{
"entityIdentifier": "blog",
"parentId": 10,
"userIdentifier": "",
"status": [
"moderation",
"approved"
],
"dateFrom": "2025-01-01",
"dateTo": ""
}
body.entityIdentifier: string | number
Identificador da entidade à qual os registros pertencem; uma string vazia significa sem filtro. Um marcador para entidades de conteúdo (blog), o ID numérico para produtos (2954), o login para usuários e administradores.
exemplo: "blog"
body.parentId: number
Identificador do registro pai — a forma de buscar as respostas a um comentário.
exemplo: 10
body.userIdentifier: string
Identificador textual do remetente; uma string vazia significa "sem filtro".
exemplo: "admin"
body.status: FormDataStatus[]
Status de moderação a manter. Deve ser um array — uma string simples é rejeitada com 400. Um array vazio significa "sem filtro".
exemplo: ["approved"]
body.dateFrom: string
Limite inferior da data de envio, YYYY-MM-DD; uma string vazia significa "sem limite" — getFormsDataByMarker a remove do corpo, pois o endpoint rejeita uma data vazia com 400. Um valor não vazio que a API não consegue interpretar ainda faz a solicitação falhar.
exemplo: "2025-01-01"
body.dateTo: string
Limite superior da data de envio, YYYY-MM-DD; uma string vazia significa "sem limite", tratada como em dateFrom.
exemplo: "2025-12-31"
isExtended: number
Passe 1 para retornar também parentId, depth, status, userIdentifier e isUserAdmin de cada registro. Padrão: 0.
exemplo: 1
langCode: string
Código do idioma. Padrão: o langCode passado para defineOneEntry ("en_US" se nenhum for passado).
exemplo: "en_US"
offset: number
Número de registros a pular. Padrão: 0. offset + limit não pode ultrapassar 200; uma janela maior é rejeitada com 400.
exemplo: 0
limit: number
Número máximo de registros a retornar. Padrão: 30.
exemplo: 30
Limite de registros. Se a permissão do grupo de usuários para este método permitir apenas leitura restrita, a API retorna no máximo o número de registros definido nas configurações do projeto (10 por padrão), seja qual for o limit informado. Com acesso total de leitura, limit funciona normalmente. Veja Module permissions (abre em uma nova aba).
Exemplos
Exemplo mínimo
const response = await FormData.getFormsDataByMarker('test-form', 2);
Exemplo com filtro
const response = await FormData.getFormsDataByMarker(
'test-form',
2,
{ entityIdentifier: 'blog', status: ['approved'] },
0,
'en_US',
0,
30,
);
A API retorna os campos de cada registro agrupados por idioma ("formData": { "en_US": [ … ] }), e o SDK os extrai para o langCode solicitado. Leia record.formData como um array: record.formData[langCode] é undefined e silenciosamente não retorna nada. Isso vale para os dois valores de isExtended.
Exemplo de resposta
{
"items": [
{
"id": 9239,
"formIdentifier": "test-form",
"time": "2026-10-26T16:25:38.689Z",
"formData": [
{
"marker": "name",
"type": "string",
"value": "Test"
}
],
"attributeSetIdentifier": "form",
"moduleIdentifier": "content",
"entityIdentifier": "blog",
"entityId": 8,
"formModuleConfigId": 2
},
{
"id": 9221,
"formIdentifier": "test-form",
"time": "2026-10-26T13:48:20.498Z",
"formData": [
{
"marker": "name",
"type": "string",
"value": "Test"
}
],
"attributeSetIdentifier": "form",
"moduleIdentifier": "content",
"entityIdentifier": "blog",
"entityId": 8,
"formModuleConfigId": 2
},
{
"id": 9203,
"formIdentifier": "test-form",
"time": "2026-10-26T13:47:49.055Z",
"formData": [
{
"marker": "name",
"type": "string",
"value": "Test"
}
],
"attributeSetIdentifier": "form",
"moduleIdentifier": "content",
"entityIdentifier": "blog",
"entityId": 8,
"formModuleConfigId": 2
}
],
"total": 907
}
Esquema de resposta
Esquema: IFormsByMarkerDataEntity
items: IFormByMarkerDataEntity[]
Registros de dados de formulário.
exemplo:
[
{
"id": 42,
"parentId": null,
"formIdentifier": "test-form",
"depth": 0,
"ip": null,
"status": null,
"userIdentifier": null,
"formData": [
{
"marker": "name",
"type": "string",
"value": "Test"
}
],
"attributeSetIdentifier": "form",
"time": "2025-03-03T15:51:17.458Z",
"entityIdentifier": "blog",
"isUserAdmin": false,
"formModuleConfigId": 2
}
]
items.id: number
ID do registro de dados do formulário.
exemplo: 12345
items.parentId: null | number
ID do registro de dados de formulário pai; null para um registro de nível superior.
exemplo: 123
items.formIdentifier: string
Marcador do formulário.
exemplo: "contact_form"
items.depth: number
**
exemplo: 1
items.ip: string | null
Não retornado pela Content API; disponível apenas na API de administração.
exemplo: '127.0.0.1'
items.fingerprint: string | null
Não retornado pela Content API; disponível apenas na API de administração.
exemplo: 'fingerprint'
items.status: string | null
Status de moderação do registro: "sent", "moderation", "approved", "banned" ou "deleted"; null quando o formulário não tem moderação.
exemplo: 'approved'
items.userIdentifier: string | null
Identificador textual (marcador) do usuário.
exemplo: "admin"
items.formData: FormDataType[]
Campos enviados, já extraídos da localidade: a API retorna { "en_US": [ … ] } e o SDK entrega o array do langCode solicitado. Leia formData diretamente — formData[langCode] é undefined.
exemplo:
[
{
"marker": "name",
"type": "string",
"value": "Test"
}
]
items.attributeSetIdentifier: string | null
Marcador do conjunto de atributos usado pelo formulário.
exemplo: "product_attributes"
items.time: Date | string
Data e hora da última alteração dos dados do formulário.
exemplo: "2023-10-01T12:00:00Z"
items.entityIdentifier: string
Marcador da entidade à qual o registro pertence.
exemplo: "test"
items.isUserAdmin: boolean
Se o registro foi enviado por um administrador.
exemplo: true
items.formModuleConfigId: number
ID da configuração do módulo de formulário.
exemplo: 2
items.moduleIdentifier: string
Marcador do módulo.
exemplo: "blog"
items.entityId: number
ID da entidade à qual o registro pertence.
exemplo: 2
total: number
Número total de registros encontrados.
exemplo: 100