- 1
Gere uma chave de API de Desenvolvedor
No app, vá em Configurações → API e crie uma chave de API de Desenvolvedor. Defina seus escopos e nível de acesso (leitura vs leitura-escrita) para o mínimo que a integração precisa. O segredo é mostrado uma vez — copie-o imediatamente para um gerenciador de segredos; o app só armazena uma forma ocultada.
Revogue e regenere na mesma página se uma chave for exposta.
- 2
Verifique a identidade com whoami
A URL base é
https://api.app.firstsales.io. A autenticação é um token Bearer. Comece sempre confirmando que a chave resolve para a organização e o workspace esperados —GET /api/v1/whoami:curl https://api.app.firstsales.io/api/v1/whoami \ -H "Authorization: Bearer $FIRSTSALES_API_KEY" - 3
Encontre os IDs da sua organização e workspace
Todo recurso está vinculado a uma organização e um workspace, então a maioria dos caminhos se parece com
/api/v1/organizations/{orgId}/workspaces/{workspaceId}/…. Liste-os:# Organizações que você pode acessar curl https://api.app.firstsales.io/api/v1/organizations \ -H "Authorization: Bearer $FIRSTSALES_API_KEY" # Workspaces dentro de uma organização curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces \ -H "Authorization: Bearer $FIRSTSALES_API_KEY" - 4
Crie um contato (de forma idempotente)
Faça um POST de um contato em um workspace. Passe um cabeçalho Idempotency-Key para que uma requisição repetida nunca crie um duplicado — seguro para repetir em caso de falha de rede.
curl -X POST \ https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \ -H "Authorization: Bearer $FIRSTSALES_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: jane-acme-2026-01" \ -d '{ "email": "jane@acme.com", "first_name": "Jane", "company_name": "Acme" }' - 5
Leia as análises da campanha
Extraia métricas de funil e engajamento de uma campanha para sincronizar resultados com seus próprios relatórios — sem raspar o dashboard:
curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/campaigns/CAMPAIGN_ID/analytics \ -H "Authorization: Bearer $FIRSTSALES_API_KEY" - 6
Leia as respostas da caixa de entrada
Liste os tópicos da caixa de entrada para extrair envios, aberturas, respostas e bounces para seus sistemas. Os corpos dos tópicos são ocultados na visão de lista; busque um único tópico para o detalhe. É assim que você direciona respostas positivas para um CRM enquanto conectores nativos ainda não chegaram.
curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/inbox/threads \ -H "Authorization: Bearer $FIRSTSALES_API_KEY" - 7
Fique dentro da superfície pública
A API só expõe a superfície pública
/api/v1. Não chame rotas privadas do app, callbacks de provedores, pixels de rastreamento, handlers de cancelamento de inscrição ou rotas internas de cron — elas não fazem parte do contrato e vão quebrar. Se uma chamada retornarunsupported_operation, pare e trate como “não disponível via API”, não como algo para contornar.Códigos de status padrão se aplicam:
401chave inválida/revogada,422validação (o corpo nomeia o campo),429limite de taxa (espere e tente de novo).
Dicas de especialista
Atalhos conquistados na prática que mantêm o aquecimento nos trilhos.
whoami antes de escrever
Confirme que a chave resolve para a organização/workspace pretendidos antes de qualquer chamada de mutação. Uma chave vinculada ao workspace errado é a forma mais comum de escrever dados no lugar errado.
Sempre envie um Idempotency-Key em criações
Retentativas de rede acontecem. Um Idempotency-Key transforma um POST repetido em uma operação nula em vez de um contato duplicado ou uma cobrança em dobro.
Armazene a chave uma vez, nunca a imprima
O segredo é mostrado uma única vez e armazenado ocultado. Coloque-o direto em um gerenciador de segredos; nunca registre em log, faça commit ou envie em um bundle de cliente.
Trate unsupported_operation como uma parada obrigatória
Se a API retornar unsupported_operation, o que você quer não está no contrato público. Não recorra a rotas privadas do app para forçar — reporte a limitação.
Perguntas frequentes
Onde consigo uma chave de API?
Configurações → API. Crie uma chave de API de Desenvolvedor com os escopos e nível de acesso que você precisa; ela é mostrada uma vez, então copie imediatamente. Revogue e regenere na mesma página se ela for exposta.
Qual é a URL base e a autenticação?
URL base https://api.app.firstsales.io; autentique com Authorization: Bearer $FIRSTSALES_API_KEY e envie JSON. Comece com GET /api/v1/whoami para confirmar o contexto.
Por que os caminhos são tão longos?
Os recursos são vinculados a uma organização e workspace, então os caminhos são /api/v1/organizations/{orgId}/workspaces/{workspaceId}/…. Obtenha os IDs em /api/v1/organizations e seu sub-recurso /workspaces (ou em whoami).
Como evito escritas duplicadas?
Envie um cabeçalho Idempotency-Key em requisições de criação. Uma requisição repetida com a mesma chave retorna o resultado original em vez de criar um segundo registro — seguro para repetir após um timeout.
Posso ler métricas de campanha e respostas?
Sim — GET …/campaigns/{id}/analytics para funil/engajamento, e GET …/inbox/threads para atividade de conversa. Os corpos dos tópicos são ocultados na lista; busque um único tópico para o detalhe completo.
Existe uma integração com Zapier ou CRM em vez disso?
Não há conector Zapier, e conectores nativos de CRM (Salesforce, HubSpot, Pipedrive) ainda estão por vir. Até que sejam lançados, a API REST — ou o CLI — é a forma suportada de integrar e sincronizar.
O que significa unsupported_operation?
A ação solicitada não faz parte do contrato público /api/v1. Pare e reporte — não chame rotas privadas do app, callbacks, pixels ou endpoints internos para contornar isso; eles não são suportados e vão quebrar.
Pronto para colocar isso em prática?
Comece seu teste do FirstSales e lance uma caixa de e-mail aquecida e autenticada em minutos.
Comece por $1