Pular para o conteúdo
NovoVeja como

Guia Rápido da API do FirstSales

Gere uma chave de API e faça suas primeiras chamadas — crie contatos, inscreva-os em campanhas e obtenha respostas da caixa de entrada via API REST.

Tutoriais
Desenvolvedor e CLI
min de leitura
9 min
etapas
7 · Avançado

  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": "[email protected]", "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 retornar unsupported_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: 401 chave inválida/revogada, 422 validação (o corpo nomeia o campo), 429 limite de taxa (espere e tente de novo).

Dicas de especialista

  • 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.

Desenvolvedor e CLI

Prospecção que continua quando você desconecta.Leads, emails, follow-ups e respostas, resolvidos.

Conecte caixas ilimitadas e deixe os agentes de IA encontrarem leads, escreverem cada email e fazerem follow-up. Ou envie seus próprios modelos no modo manual. A partir de $29/mês.

Comece seu teste de $1 Ver preços

$1 por 3 dias · Cancele quando quiser · Sem contrato

Instalar com IA

Seu agente de código configura a CLI e as skills do FirstSales para você.

Prompt para Claude Code

I'm setting up FirstSales (https://firstsales.io), an AI outbound sales platform: campaigns, contacts, a reply inbox, deliverability and lead signals. Help me get my workspace sending real, good emails end to end, from Claude Code.

Read these first so you know how FirstSales works:
- Developer docs and API: https://developer.firstsales.io
- CLI: https://www.npmjs.com/package/@firstsales.io/cli
- Skills for coding agents: https://github.com/firstsalesio/firstsales-skills (read README.md and GUIDE.md)

Setup
1. Install the CLI: npm install -g @firstsales.io/cli
2. Install the FirstSales skills:
   claude plugin marketplace add firstsalesio/firstsales-skills
   claude plugin install firstsales@firstsales
3. Ask me if I already have a FirstSales account. If not, send me to https://app.firstsales.io to sign up.
4. Ask me to create an API key under Settings → API → API Keys, with only the scopes we need.
   Never ask me to paste the key into this chat. Tell me to run this in my own terminal, so the key stays hidden:
   read -rs FS_KEY && firstsales auth login --api-key "$FS_KEY"; unset FS_KEY
5. Run `firstsales whoami` and tell me which workspace and organisation we are connected to.

Then ask me about my business: what I sell, who I sell to (roles, company size, countries), my best customers, and what I use today for outbound (tools, lists, mailboxes). Walk me through:
1. Teaching FirstSales my business: website, offer, proof points and case studies in the knowledge base, so the AI writes like someone who knows the product.
2. Connecting my sending mailboxes and checking my sending domain: SPF, DKIM, DMARC and warm-up. If anything is unhealthy, tell me the exact DNS record to add.
3. Bringing in contacts: import my CSV or CRM export into a clean list, remove duplicates and bad emails, and block domains I must never email (customers, competitors, my own).
4. Building my first campaign: the right list, senders, steps and timing. Write the sequence with me, show me the drafts, and do not launch until I say yes.
5. Setting up Signals if it fits: find people engaging with LinkedIn posts about topics my buyers care about, and turn them into leads.
6. Inviting my team and giving each person the right access.

Once campaigns run, show me how to work the reply inbox from here: which replies need an answer, draft responses in my voice, and move good conversations into deals. If I use Cal.com, connect it so follow-ups can offer my booking link (not the first email).

Throughout, as you learn about my business, proactively suggest and help create:
- Reply templates for the questions and objections my prospects are likely to raise, based on my product, site and codebase if you can see them.
- Campaign ideas and segments worth testing, with the reason for each.

Safety rules:
- Show every change as a dry run (--dry-run) first and wait for my yes. Never send emails, launch campaigns or delete anything without my yes.
- Tell me before anything that spends credits, and how many.

Be opinionated. If the docs give a sensible default, just use it. Don't make me choose between five options.
Developer docs ↗npm: @firstsales.io/cli ↗GitHub: firstsales-skills ↗