API da VoxScreen

Apenas quatro passos até um candidato avaliado chegando no seu endpoint.

1. 1

   Crie uma chave de API

   Na VoxScreen, abra Configurações e depois Integrações. A chave aparece uma única vez, então copie antes de fechar a janela. Todos os planos têm acesso à API, inclusive o gratuito.

2. 2

   Confirme que funciona

   Se isto retornar o nome da sua conta, você está conectado.

   curlCopiar

   curl https://voxscreen.com/api/integrations/v1/me \
     -H "Authorization: Bearer vs_live_YOUR_KEY"

3. 3

   Convide um candidato

   Use um id de entrevista vindo de GET /interviews. O candidato recebe o e-mail de convite na hora.

   curlCopiar

   curl -X POST https://voxscreen.com/api/integrations/v1/candidates/invite \
     -H "Authorization: Bearer vs_live_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "interview_id": "YOUR_INTERVIEW_ID",
           "email": "alex.silva@example.com",
           "full_name": "Alex Silva"
         }'

4. 4

   Receba o resultado

   Assine submission.scored e enviamos um POST para o seu endpoint assim que as respostas forem transcritas e avaliadas. Guarde o secret da resposta: você precisa dele para verificar as entregas.

   curlCopiar

   curl -X POST https://voxscreen.com/api/integrations/v1/hooks \
     -H "Authorization: Bearer vs_live_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "event": "submission.scored",
           "target_url": "https://example.com/webhooks/voxscreen"
         }'

Toda requisição precisa de uma chave de API, enviada em qualquer um dos dois cabeçalhos. As chaves começam com vs_live_ seguido de 43 caracteres aleatórios.

curl https://voxscreen.com/api/integrations/v1/me \
  -H "Authorization: Bearer vs_live_YOUR_KEY"

# X-API-Key works too, if that suits your client better
curl https://voxscreen.com/api/integrations/v1/me \
  -H "X-API-Key: vs_live_YOUR_KEY"

A chave pertence à conta, não a uma pessoa, então remover o login de alguém que saiu da empresa não quebra as automações que essa pessoa criou.

O acesso à API está incluído em todos os planos. Um 402 significa que a assinatura está inativa, não que o plano é pequeno demais.

Todos os caminhos são relativos à URL base acima. As respostas são JSON.

{
  "account_id": "3f2b8c14-0000-4000-8000-000000000001",
  "account_name": "Acme Inc.",
  "plan": "starter"
}

[
  {
    "id": "9c1a0f10-0000-4000-8000-000000000001",
    "title": "Backend Tech Lead",
    "description": "Screening for a backend tech lead role.",
    "status": "active",
    "language": "en",
    "time_limit_seconds": 1800,
    "expires_at": "2026-09-01T23:59:00Z",
    "created_at": "2026-08-01T12:00:00Z"
  }
]

{
  "interview_id": "9c1a0f10-0000-4000-8000-000000000001",
  "email": "alex.silva@example.com",
  "full_name": "Alex Silva"
}

{
  "invitation_id": "44be0000-0000-4000-8000-000000000001",
  "candidate_id": "7d900000-0000-4000-8000-000000000001",
  "interview_id": "9c1a0f10-0000-4000-8000-000000000001",
  "status": "sent"
}

[
  {
    "id": "d46e6040-0000-4000-8000-000000000001",
    "interview_id": "9c1a0f10-0000-4000-8000-000000000001",
    "candidate_id": "7d900000-0000-4000-8000-000000000001",
    "status": "scored",
    "results_url": "https://voxscreen.com/submissions/d46e6040-0000-4000-8000-000000000001",
    "started_at": "2026-08-07T16:01:15Z",
    "completed_at": "2026-08-07T16:08:40Z",
    "overall_score": 4.2,
    "percentile": 78.0,
    "language_proficiency": "B2",
    "language_proficiency_reasoning": "Fluent, occasional hesitation.",
    "ai_summary": "Strong communication and relevant backend experience.",
    "created_at": "2026-08-07T16:00:02Z",
    "interview_title": "Backend Tech Lead",
    "candidate_name": "Alex Silva",
    "candidate_email": "alex.silva@example.com"
  }
]

{
  "id": "d46e6040-0000-4000-8000-000000000001",
  "status": "scored",
  "results_url": "https://voxscreen.com/submissions/d46e6040-0000-4000-8000-000000000001",
  "overall_score": 4.2,
  "language_proficiency": "B2",
  "ai_summary": "Strong communication and relevant backend experience.",
  "candidate_name": "Alex Silva",
  "candidate_email": "alex.silva@example.com"
}

{
  "event": "submission.scored",
  "target_url": "https://example.com/webhooks/voxscreen"
}

{
  "id": "b17c0000-0000-4000-8000-000000000001",
  "event": "submission.scored",
  "target_url": "https://example.com/webhooks/voxscreen",
  "is_active": true,
  "api_key_id": "a1110000-0000-4000-8000-000000000001",
  "created_at": "2026-08-08T02:00:00Z",
  "secret": "o6aZJTxJsC9fj18nzONu8K964MRVdAfQ"
}

[
  {
    "id": "b17c0000-0000-4000-8000-000000000001",
    "event": "submission.scored",
    "target_url": "https://example.com/webhooks/voxscreen",
    "is_active": true,
    "api_key_id": "a1110000-0000-4000-8000-000000000001",
    "created_at": "2026-08-08T02:00:00Z"
  }
]

204 No Content

Em vez de ficar consultando, assine um evento e enviamos um POST para a sua URL no momento em que ele acontece. É o padrão que o Zapier chama de REST Hook.

Eventos

submission.scored

As respostas foram transcritas e avaliadas. Traz a nota geral, o nível de idioma no padrão CEFR e o resumo da IA. É o evento que a maioria das integrações quer.

submission.completed

O candidato terminou de gravar, antes da avaliação rodar. Útil para confirmações, onde esperar a IA só atrasaria a resposta.

candidate.invited

Um candidato foi convidado para uma entrevista.

Como é uma entrega

POST /webhooks/voxscreen HTTP/1.1
Content-Type: application/json
User-Agent: VoxScreen-Webhooks/1
X-VoxScreen-Event: submission.scored
X-VoxScreen-Delivery: 18dbc0a7-b565-4edd-9696-0f730472d626
X-VoxScreen-Signature: sha256=0ed8eb269ad62155c2b7e60a1260f81f0…

{
  "event": "submission.scored",
  "created_at": "2026-08-08T02:09:04.713338+00:00",
  "data": {
    "submission_id": "d46e6040-0000-4000-8000-000000000001",
    "results_url": "https://voxscreen.com/submissions/d46e6040-0000-4000-8000-000000000001",
    "status": "scored",
    "overall_score": 4.2,
    "percentile": 78.0,
    "language_proficiency": "B2",
    "ai_summary": "Strong communication and relevant backend experience.",
    "started_at": "2026-08-07T16:01:15Z",
    "completed_at": "2026-08-07T16:08:40Z",
    "interview": {
      "id": "9c1a0f10-0000-4000-8000-000000000001",
      "title": "Backend Tech Lead"
    },
    "candidate": {
      "id": "7d900000-0000-4000-8000-000000000001",
      "full_name": "Alex Silva",
      "email": "alex.silva@example.com"
    }
  }
}

candidate.invited traz invitation_id, status, sent_at, interview e candidate no lugar disso.

X-VoxScreen-Delivery é único por tentativa. Use para deixar seu handler idempotente, já que uma nova tentativa repete o mesmo payload.

Verificando uma entrega

Calcule HMAC-SHA256 sobre o corpo bruto da requisição usando o segredo da sua inscrição e compare em tempo constante.

import hashlib
import hmac

def is_valid(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

const crypto = require("crypto");

function isValid(secret, rawBody, signatureHeader) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Novas tentativas e falhas

Qualquer resposta fora da faixa 2xx é tentada mais cinco vezes com espera exponencial, ou seja, até seis tentativas por evento. Responda 2xx rápido e faça o trabalho de forma assíncrona: as entregas expiram em 10 segundos.

• ·30s · 60s · 120s · 240s · 480s
• ·Retorne 410 Gone para cancelar a inscrição na hora. É assim que um consumidor sinaliza que o endpoint saiu do ar, e isso interrompe todas as entregas seguintes.
• ·As tentativas são contadas uma a uma, incluindo as repetições, e a inscrição é desativada após 10 falhas seguidas. Como cada evento é tentado seis vezes, isso dá menos de dois eventos com falha, ou cerca de 20 minutos com o endpoint fora do ar. Qualquer 2xx zera a contagem. A inscrição desativada continua visível nas suas configurações, então monitore seu próprio endpoint em vez de contar com novas tentativas nossas.

Os erros retornam {"detail": "..."}. Erros de validação retornam uma lista em detail nomeando cada campo com problema.

120 requisições por minuto, por chave, por endpoint. Zapier e Make consultam bem abaixo disso.

Você não precisa escrever nada disso. Zapier e Make conectam a VoxScreen a milhares de ferramentas, e dá para adicionar um webhook direto em Configurações e depois Integrações, sem nem criar uma chave de API.