API de Equipes

Gerencie equipes, membros, papéis e convites para a criação colaborativa de formulários.

A API de Equipes permite criar e gerenciar equipes para a criação colaborativa de formulários. As equipes permitem que vários usuários compartilhem formulários, com controle de acesso baseado em papéis definindo quem pode visualizar, editar e excluir formulários e respostas.

Todos os corpos de requisição e resposta usam nomes de campos em snake_case.

Papéis da Equipe

ownerrole

Acesso completo. Pode gerenciar membros, cobrança e excluir a equipe.

adminrole

Pode criar, editar e excluir formulários, gerenciar membros e visualizar respostas.

editorrole

Pode criar e editar formulários e visualizar respostas. Não pode gerenciar membros.

viewerrole

Pode visualizar formulários e respostas. Não pode criar nem editar.

Endpoints

Listar Equipes

GET/api/v1/teams

Retorna todas as equipes das quais o usuário autenticado é membro.

Resposta

json

{
  "teams": [
    {
      "id": "665b2c3d4e5f6a7b8c9d0e1f",
      "name": "Marketing",
      "slug": "marketing",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-01-10T09:00:00.000Z",
      "updated_at": "2026-02-15T11:30:00.000Z",
      "member_count": 5,
      "your_role": "admin"
    },
    {
      "id": "665c3d4e5f6a7b8c9d0e1f20",
      "name": "Product",
      "slug": "product",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-02-01T14:00:00.000Z",
      "updated_at": "2026-02-20T16:45:00.000Z",
      "member_count": 3,
      "your_role": "owner"
    }
  ]
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

Criar Equipe

POST/api/v1/teams

Cria uma nova equipe. O usuário autenticado se torna o proprietário da equipe.

Corpo da Requisição

namestring

Nome da equipe

Exemplo de Requisição

json

{
  "name": "Marketing"
}

Resposta

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z"
}

Exemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing" }'

Obter Equipe

GET/api/v1/teams/:teamId

Recupera uma única equipe pelo ID.

Qualquer membro da equipe pode chamá-lo. A resposta nunca inclui os segredos da equipe (a string de conexão do banco de dados de residência de dados, o ID da conexão SSO ou IDs internos de domínio), e sso_domain_verify_token (o valor DNS que comprova o domínio SSO) só é retornado para quem chama com o papel owner ou admin.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-02-15T11:30:00.000Z",
  "member_count": 5
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

Atualizar Equipe

PUT/api/v1/teams/:teamId

Atualiza as propriedades da equipe. Requer o papel owner ou admin.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Corpo da Requisição

namestring

Novo nome da equipe

Exemplo de Requisição

json

{
  "name": "Marketing & Growth"
}

Resposta

Retorna o objeto da equipe atualizado.

Exemplos de Código

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing & Growth" }'

Excluir Equipe

DELETE/api/v1/teams/:teamId

Exclui uma equipe permanentemente. Apenas o proprietário da equipe pode excluir uma equipe.

Excluir uma equipe remove todas as associações e convites da equipe. Os formulários pertencentes à equipe não são excluídos automaticamente, mas ficarão inacessíveis para os ex-membros da equipe.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "success": true
}

Exemplos de Código

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

Listar Membros

GET/api/v1/teams/:teamId/members

Retorna todos os membros de uma equipe.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "members": [
    {
      "id": "66d1e2f3a4b5c6d7e8f9a0b1",
      "user_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Johnson",
      "role": "owner",
      "joined_at": "2026-01-10T09:00:00.000Z"
    },
    {
      "id": "66d2e3f4a5b6c7d8e9f0a1b2",
      "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "email": "bob@example.com",
      "first_name": "Bob",
      "last_name": "Smith",
      "role": "editor",
      "joined_at": "2026-01-15T14:30:00.000Z"
    }
  ]
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

Adicionar Membro

POST/api/v1/teams/:teamId/members

Convida alguém para a equipe por e-mail, exatamente como Criar Convite: o NueForm envia o convite por e-mail, ele expira após 7 dias e a pessoa entra na equipe ao aceitá-lo. Não adiciona diretamente um usuário existente. Requer o papel owner ou admin. Retorna o convite (201); responde 409 se o endereço já pertence a um membro ou já tem um convite pendente que ainda não expirou (um convite expirado não impede um novo), e 400 se o plano do proprietário da equipe não tem vagas disponíveis — um convite pendente ocupa uma vaga até expirar.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Corpo da Requisição

emailstring

Endereço de e-mail a convidar (armazenado em minúsculas)

rolestring

Papel que a pessoa recebe ao aceitar: "admin", "editor" ou "viewer"

Exemplo de Requisição

json

{
  "email": "carol@example.com",
  "role": "editor"
}

Resposta

json

{
  "id": "66e1f2a3b4c5d6e7f8a9b0c1",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "email": "carol@example.com",
  "role": "editor",
  "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
  "token": "2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f",
  "status": "pending",
  "language": "en",
  "expires_at": "2026-03-07T12:00:00.000Z",
  "created_at": "2026-02-28T12:00:00.000Z",
  "invite_url": "/teams/invite/2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f"
}

Exemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carol@example.com",
    "role": "editor"
  }'

Atualizar Papel do Membro

PUT/api/v1/teams/:teamId/members/:memberId

Atualiza o papel de um membro da equipe. Requer o papel owner ou admin. Você não pode alterar o papel do proprietário.

Parâmetros de Caminho

teamIdstring

O ID da equipe

memberIdstring

O ID do membro da equipe

Corpo da Requisição

rolestring

Novo papel: "admin", "editor", "viewer"

Exemplo de Requisição

json

{
  "role": "admin"
}

Resposta

json

{
  "id": "66d2e3f4a5b6c7d8e9f0a1b2",
  "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "role": "admin",
  "joined_at": "2026-01-15T14:30:00.000Z"
}

Exemplos de Código

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

Remover Membro

DELETE/api/v1/teams/:teamId/members/:memberId

Remove um membro de uma equipe. Requer o papel owner ou admin. O proprietário da equipe não pode ser removido. Os convites pendentes desta equipe para essa pessoa também são cancelados, para que ela não possa voltar a entrar com eles.

Parâmetros de Caminho

teamIdstring

O ID da equipe

memberIdstring

O ID do membro da equipe

Resposta

json

{
  "success": true,
  "message": "Member removed from team"
}

Exemplos de Código

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Listar Convites

GET/api/v1/teams/:teamId/invitations

Retorna os convites pendentes da equipe que ainda não expiraram, dos mais recentes para os mais antigos. Qualquer membro da equipe pode chamá-lo; o campo token (o segredo do link do convite) só é incluído para quem chama com o papel owner ou admin.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "invitations": [
    {
      "id": "66e1f2a3b4c5d6e7f8a9b0c1",
      "email": "carol@example.com",
      "role": "editor",
      "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "status": "pending",
      "expires_at": "2026-03-07T12:00:00.000Z",
      "created_at": "2026-02-28T12:00:00.000Z"
    }
  ]
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY"

Criar Convite

POST/api/v1/teams/:teamId/invitations

Envia um convite por e-mail para entrar em uma equipe. O convite inclui um token único e expira após 7 dias. Requer o papel owner ou admin. Responde 409 se o endereço já pertence a um membro ou já tem um convite pendente que ainda não expirou (um convite expirado não impede um novo), e 400 se o plano do proprietário da equipe não tem vagas disponíveis — um convite pendente ocupa uma vaga até expirar.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Corpo da Requisição

emailstring

Endereço de e-mail a convidar

rolestring

Papel que a pessoa recebe ao aceitar: "admin", "editor" ou "viewer"

Exemplo de Requisição

json

{
  "email": "carol@example.com",
  "role": "editor"
}

Resposta

json

{
  "id": "66e1f2a3b4c5d6e7f8a9b0c1",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "email": "carol@example.com",
  "role": "editor",
  "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
  "token": "2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f",
  "status": "pending",
  "language": "en",
  "expires_at": "2026-03-07T12:00:00.000Z",
  "created_at": "2026-02-28T12:00:00.000Z",
  "invite_url": "/teams/invite/2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f"
}

Exemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carol@example.com",
    "role": "editor"
  }'

Cancelar Convite

DELETE/api/v1/teams/:teamId/invitations/:invId

Cancela um convite pendente. Requer o papel owner ou admin. O token do convite deixará de ser válido.

Parâmetros de Caminho

teamIdstring

O ID da equipe

invIdstring

O ID do convite

Resposta

json

{
  "success": true,
  "message": "Invitation cancelled"
}

Exemplos de Código

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations/66e1f2a3b4c5d6e7f8a9b0c1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Logs de Auditoria

GET/api/v1/teams/:teamId/audit-logs

Retorna uma lista paginada de eventos de log de auditoria da equipe. Requer o papel owner ou admin. Disponível apenas no plano Enterprise.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Parâmetros de Consulta

actionstring

Filtre por tipo de ação (por exemplo, "form.published", "member.removed")

user_idstring

Filtre pelo usuário que realizou a ação

sincestring

Data ISO 8601 — apenas eventos a partir desta data

untilstring

Data ISO 8601 — apenas eventos até esta data

pageinteger

Número da página (padrão: 1)

per_pageinteger

Resultados por página (padrão: 50, máx.: 100)

Resposta

json

{
  "events": [
    {
      "id": "670a1b2c3d4e5f6a7b8c9d0e",
      "action": "form.published",
      "user_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "user_email": "alice@example.com",
      "details": {
        "form_id": "665f1a2b3c4d5e6f7a8b9c0d",
        "form_title": "Customer Survey"
      },
      "ip_address": "203.0.113.42",
      "timestamp": "2026-03-20T14:30:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/audit-logs?action=form.published&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Obter Branding da Equipe

GET/api/v1/teams/:teamId/branding

Retorna a configuração de branding da equipe. Requer associação à equipe.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "logo_url": "https://cdn.nueform.io/teams/665b2c/logo.png",
  "primary_color": "#6366f1",
  "background_color": "#ffffff",
  "text_color": "#1a1a1a",
  "font_family": "Inter",
  "footer_text": "Powered by Acme Corp"
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/branding" \
  -H "Authorization: Bearer YOUR_API_KEY"

Atualizar Branding da Equipe

PUT/api/v1/teams/:teamId/branding

Atualiza a configuração de branding da equipe. Requer o papel owner ou admin.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Corpo da Requisição

logo_urlstring

URL do logo da equipe

primary_colorstring

Cor hexadecimal primária (por exemplo, "#6366f1")

background_colorstring

Cor hexadecimal de fundo

text_colorstring

Cor hexadecimal do texto

font_familystring

Nome da família de fontes do Google Fonts

footer_textstring

Texto personalizado do rodapé

Exemplo de Requisição

json

{
  "primary_color": "#8b5cf6",
  "font_family": "Poppins",
  "footer_text": "2026 Acme Corp. All rights reserved."
}

Resposta

Retorna o objeto de branding atualizado.

Exemplos de Código

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/branding" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "primary_color": "#8b5cf6", "font_family": "Poppins" }'

Limpar Branding da Equipe

DELETE/api/v1/teams/:teamId/branding

Remove todas as configurações de branding da equipe, revertendo os formulários para os padrões do proprietário ou do sistema. Requer o papel owner ou admin.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "success": true
}

Exemplos de Código

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/branding" \
  -H "Authorization: Bearer YOUR_API_KEY"

Obter Subdomínio

GET/api/v1/teams/:teamId/subdomain

Retorna a configuração de subdomínio da equipe. Requer associação à equipe.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "subdomain": "acme-marketing",
  "full_url": "https://acme-marketing.nueform.io"
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/subdomain" \
  -H "Authorization: Bearer YOUR_API_KEY"

Definir Subdomínio

PUT/api/v1/teams/:teamId/subdomain

Define ou atualiza o subdomínio da equipe. Requer o papel owner ou admin. Requer o plano Pro ou Enterprise.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Corpo da Requisição

subdomainstring

Subdomínio desejado (apenas letras minúsculas, números e hifens)

Exemplo de Requisição

json

{
  "subdomain": "acme-marketing"
}

Resposta

json

{
  "subdomain": "acme-marketing",
  "full_url": "https://acme-marketing.nueform.io"
}

Exemplos de Código

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/subdomain" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subdomain": "acme-marketing" }'

Obter Domínio Personalizado

GET/api/v1/teams/:teamId/custom-domain

Retorna a configuração de domínio personalizado da equipe. Requer associação à equipe. Disponível apenas no plano Enterprise.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "domain": "forms.acmecorp.com",
  "status": "verified",
  "ssl_status": "active",
  "cname_target": "custom.nueform.io",
  "verified_at": "2026-03-15T10:00:00.000Z"
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/custom-domain" \
  -H "Authorization: Bearer YOUR_API_KEY"

Adicionar Domínio Personalizado

POST/api/v1/teams/:teamId/custom-domain

Adiciona um domínio personalizado à equipe. Requer o papel owner ou admin. Disponível apenas no plano Enterprise. Após adicionar, use o endpoint Verificar Domínio para confirmar a configuração de DNS.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Corpo da Requisição

domainstring

O domínio personalizado (por exemplo, "forms.acmecorp.com")

Exemplo de Requisição

json

{
  "domain": "forms.acmecorp.com"
}

Resposta

json

{
  "domain": "forms.acmecorp.com",
  "status": "pending_verification",
  "cname_target": "custom.nueform.io",
  "instructions": "Add a CNAME record pointing forms.acmecorp.com to custom.nueform.io"
}

Exemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/custom-domain" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "forms.acmecorp.com" }'

Remover Domínio Personalizado

DELETE/api/v1/teams/:teamId/custom-domain

Remove o domínio personalizado da equipe. Os formulários voltarão para a URL padrão do NueForm. Requer o papel owner ou admin.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "success": true
}

Exemplos de Código

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/custom-domain" \
  -H "Authorization: Bearer YOUR_API_KEY"

Verificar Domínio Personalizado

POST/api/v1/teams/:teamId/custom-domain/verify

Verifica se os registros DNS estão configurados corretamente para o domínio personalizado. O SSL é provisionado automaticamente após a verificação bem-sucedida. Requer o papel owner ou admin.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta (Sucesso)

json

{
  "domain": "forms.acmecorp.com",
  "status": "verified",
  "ssl_status": "provisioning",
  "verified_at": "2026-03-20T15:00:00.000Z"
}

Resposta (Falha)

json

{
  "domain": "forms.acmecorp.com",
  "status": "pending_verification",
  "error": "CNAME record not found. Expected: forms.acmecorp.com -> custom.nueform.io"
}

Exemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/custom-domain/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"

Obter Cobrança

GET/api/v1/teams/:teamId/billing

Retorna o resumo de cobrança da equipe, incluindo detalhes do plano, uso de assentos e informações da próxima fatura. Requer o papel owner ou admin.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Resposta

json

{
  "plan": "enterprise",
  "billing_cycle": "monthly",
  "price_per_month": 99,
  "included_seats": 5,
  "used_seats": 14,
  "extra_seats": 0,
  "extra_seat_cost": 1.00,
  "viewer_seats": 38,
  "next_invoice_date": "2026-04-01T00:00:00.000Z",
  "next_invoice_amount": 99.00
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/billing" \
  -H "Authorization: Bearer YOUR_API_KEY"

Obter Análises da Equipe

GET/api/v1/teams/:teamId/analytics

Retorna análises agregadas de todos os formulários da equipe. Requer associação à equipe.

Parâmetros de Caminho

teamIdstring

O ID da equipe

Parâmetros de Consulta

sincestring

Data ISO 8601 — apenas dados a partir desta data

untilstring

Data ISO 8601 — apenas dados até esta data

Resposta

json

{
  "total_forms": 24,
  "total_responses": 12580,
  "avg_completion_rate": 0.73,
  "responses_by_day": [
    { "date": "2026-03-19", "count": 142 },
    { "date": "2026-03-20", "count": 167 }
  ],
  "top_forms": [
    {
      "form_id": "665f1a2b3c4d5e6f7a8b9c0d",
      "title": "Customer Survey",
      "responses": 4230,
      "completion_rate": 0.82
    }
  ]
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/analytics?since=2026-03-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

Listar Convidados do Formulário

GET/api/v1/forms/:id/guests

Retorna todos os convidados de um formulário específico. Requer o papel owner ou admin na equipe do formulário.

Parâmetros de Caminho

idstring

O ID do formulário

Resposta

json

{
  "guests": [
    {
      "id": "671a2b3c4d5e6f7a8b9c0d1e",
      "email": "contractor@external.com",
      "first_name": "Dana",
      "last_name": "Lee",
      "permission": "edit",
      "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "accepted_at": "2026-03-18T10:00:00.000Z"
    }
  ]
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665f1a2b3c4d5e6f7a8b9c0d/guests" \
  -H "Authorization: Bearer YOUR_API_KEY"

Convidar Convidado

POST/api/v1/forms/:id/guests

Convida um colaborador externo para um formulário específico. Requer o papel owner ou admin na equipe do formulário. O convidado recebe um convite por e-mail.

Parâmetros de Caminho

idstring

O ID do formulário

Corpo da Requisição

emailstring

Endereço de e-mail do convidado

permissionstring

Nível de permissão: "view" ou "edit" (padrão: "view")

Exemplo de Requisição

json

{
  "email": "contractor@external.com",
  "permission": "edit"
}

Resposta

json

{
  "id": "671a2b3c4d5e6f7a8b9c0d1e",
  "email": "contractor@external.com",
  "permission": "edit",
  "status": "pending",
  "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-03-20T12:00:00.000Z"
}

Exemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665f1a2b3c4d5e6f7a8b9c0d/guests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contractor@external.com",
    "permission": "edit"
  }'

Remover Convidado

DELETE/api/v1/forms/:id/guests

Remove o acesso de um convidado a um formulário específico. Requer o papel owner ou admin na equipe do formulário.

Parâmetros de Caminho

idstring

O ID do formulário

Corpo da Requisição

guest_idstring

O ID do convidado a remover

Exemplo de Requisição

json

{
  "guest_id": "671a2b3c4d5e6f7a8b9c0d1e"
}

Resposta

json

{
  "success": true
}

Exemplos de Código

bash

curl -X DELETE "https://api.nueform.io/api/v1/forms/665f1a2b3c4d5e6f7a8b9c0d/guests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "guest_id": "671a2b3c4d5e6f7a8b9c0d1e" }'

Aceitar Convite de Convidado

POST/api/v1/forms/guests/accept

Aceita um convite de convidado usando o token do e-mail de convite. O usuário autenticado ganha acesso ao formulário com o nível de permissão especificado.

Corpo da Requisição

tokenstring

O token do convite do link do e-mail

Exemplo de Requisição

json

{
  "token": "gt_abc123def456ghi789"
}

Resposta

json

{
  "form_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "form_title": "Customer Survey",
  "permission": "edit",
  "team_name": "Marketing"
}

Exemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/forms/guests/accept" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "token": "gt_abc123def456ghi789" }'

Respostas de Erro

Respostas de erro padrão retornadas pelos endpoints da API de Equipes.

Códigos de Erro

400Bad Request

Campos obrigatórios ausentes, e-mail ou papel inválido, ou nenhuma vaga disponível no plano do proprietário da equipe

401Unauthorized

Chave de API ausente ou inválida

403Forbidden

Não é membro da equipe, ou papel insuficiente para a ação

404Not Found

Equipe, membro ou convite não encontrado

409Conflict

Usuário já é membro, convite duplicado

500Server Error

Erro interno do servidor

Exemplo de Erro

json

{
  "error": {
    "code": "CONFLICT",
    "message": "A pending invitation already exists for this email",
    "status": 409
  }
}

Atualizar Acesso de Telefonia

PUT/api/v1/teams/:teamId/members/:memberId/telephony

Atualize o nível de acesso de telefonia de um membro. Requer o papel admin ou owner. O acesso de telefonia controla quais ações relacionadas a telefone um membro pode realizar, independentemente do seu papel na equipe.

Níveis de Acesso de Telefonia

Nível	Permissões
`none`	Sem acesso de telefonia
`observer`	Visualizar logs de chamadas, gravações, números de telefone e vozes da equipe
`operator`	Fazer chamadas de saída, vincular números a formulários, iniciar campanhas
`manager`	Provisionar/liberar números, gerenciar campanhas, pausar/retomar números
`full`	Controle completo, incluindo criar/excluir vozes da equipe

Corpo da Requisição

telephony_accessstringobrigatório

O nível de acesso de telefonia a definir. Um de: none, observer, operator, manager, full.

Requisição

json

{
  "telephony_access": "operator"
}

Resposta

json

{
  "message": "Telephony access updated",
  "telephony_access": "operator"
}

Listar Vozes da Equipe

GET/api/voices?teamId=:teamId

Liste todas as vozes disponíveis para o usuário, incluindo as vozes de equipe da equipe especificada. As vozes de equipe são compartilhadas com todos os membros da equipe que têm acesso de telefonia de nível Observer ou superior.

A resposta inclui os campos source e teamName para distinguir entre vozes pessoais e de equipe.

Resposta

json

{
  "voices": [
    {
      "id": "qwen:preset:Ryan",
      "name": "Ryan",
      "category": "preset",
      "source": "system"
    },
    {
      "id": "qwen:clone:abc123",
      "name": "My Voice",
      "category": "custom",
      "type": "clone",
      "source": "personal"
    },
    {
      "id": "qwen:clone:def456",
      "name": "Team Voice",
      "category": "custom",
      "type": "design",
      "source": "team",
      "teamName": "Marketing Team",
      "teamId": "team123"
    }
  ]
}

Criar Voz da Equipe

POST/api/voices/create

Crie uma voz personalizada e atribua-a a uma equipe. Requer a permissão de telefonia Full Access na equipe de destino. A conta do criador da voz é cobrada pela taxa de US$ 5 de criação de voz.

Corpo da Requisição

namestringobrigatório

Nome de exibição da voz.

typestringobrigatório

Tipo de voz: clone ou design.

teamIdstringobrigatório

O ID da equipe à qual atribuir a voz.

sampleBlobUrlstring

URL da amostra de áudio para vozes clonadas.

Requisição

json

{
  "name": "Team Support Voice",
  "type": "design",
  "teamId": "team123",
  "designGender": "female",
  "designTone": "professional"
}

Resposta

json

{
  "voice": {
    "id": "qwen:clone:new123",
    "dbId": "new123",
    "name": "Team Support Voice",
    "type": "design",
    "category": "custom",
    "createdAt": "2026-03-25T00:00:00.000Z"
  }
}

Última atualização: 30 de outubro de 2026