Aller au contenu
NouveauDécouvrir comment

Démarrage rapide de l'API FirstSales

Générez une clé API et effectuez vos premiers appels — créez des contacts, inscrivez-les dans des campagnes et récupérez les réponses de la boîte de réception via l'API REST.

Tutoriels
Développeur & CLI
min de lecture
9 min
étapes
7 · Avancé

  1. Générer une clé API développeur

    Dans l'application, allez dans Settings → API et créez une clé API développeur. Définissez ses scopes et son niveau d'accès (lecture seule ou lecture-écriture) au minimum nécessaire pour votre intégration. Le secret n'est affiché qu'une seule fois : copiez-le immédiatement dans un gestionnaire de secrets ; l'application n'en conserve qu'une forme masquée.

    Révoquez et régénérez la clé sur la même page si elle venait à fuiter.

  2. Vérifier l'identité avec whoami

    L'URL de base est https://api.app.firstsales.io. L'authentification se fait par jeton Bearer. Commencez toujours par vérifier que la clé pointe bien vers l'organisation et le workspace attendus : GET /api/v1/whoami :

    curl https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

  3. Trouver vos identifiants d'organisation et de workspace

    Chaque ressource est rattachée à une organisation et à un workspace, donc la plupart des chemins ressemblent à /api/v1/organizations/{orgId}/workspaces/{workspaceId}/…. Listez-les :

    # Organisations auxquelles vous avez accès
curl https://api.app.firstsales.io/api/v1/organizations \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

# Workspaces au sein d'une organisation
curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

  4. Créer un contact (de façon idempotente)

    Envoyez un contact en POST dans un workspace. Passez un en-tête Idempotency-Key pour qu'une requête rejouée ne crée jamais de doublon : cela permet de la renvoyer sans risque en cas d'échec réseau.

    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. Lire les analytics d'une campagne

    Récupérez les métriques d'entonnoir et d'engagement d'une campagne pour synchroniser les résultats avec votre propre reporting : sans avoir à scraper le 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. Lire les réponses depuis l'inbox

    Listez les threads de l'inbox pour récupérer envois, ouvertures, réponses et bounces dans vos systèmes. Le corps des messages est masqué dans la vue liste ; récupérez un thread individuel pour le détail. C'est ainsi que vous pouvez router les réponses positives vers un CRM en attendant l'arrivée des connecteurs natifs.

    curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/inbox/threads \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

  7. Rester dans le périmètre public

    L'API n'expose que le périmètre public /api/v1. N'appelez pas les routes privées de l'application, les callbacks des fournisseurs, les pixels de tracking, les gestionnaires de désabonnement ou les routes cron internes : ils ne font pas partie du contrat et casseront. Si un appel renvoie unsupported_operation, arrêtez-vous et considérez que c'est « non disponible via l'API », pas quelque chose à contourner.

    Les codes de statut standards s'appliquent : 401 clé invalide/révoquée, 422 erreur de validation (le corps précise le champ), 429 limite de débit atteinte (patientez puis réessayez).

Astuces de pro

  • whoami avant d'écrire

    Vérifiez que la clé pointe vers l'organisation/le workspace visé avant tout appel mutateur. Une clé rattachée au mauvais workspace est la cause la plus fréquente d'écriture de données au mauvais endroit.

  • Envoyez toujours une Idempotency-Key sur les créations

    Les tentatives réseau se produisent. Une Idempotency-Key transforme un POST rejoué en no-op plutôt qu'en contact dupliqué ou en double facturation.

  • Stockez la clé une seule fois, ne l'affichez jamais

    Le secret n'est affiché qu'une fois et stocké sous forme masquée. Placez-le directement dans un gestionnaire de secrets ; ne le loggez jamais, ne le commitez jamais, ne l'expédiez jamais dans un bundle client.

  • Traitez unsupported_operation comme un arrêt strict

    Si l'API renvoie unsupported_operation, ce que vous voulez faire n'est pas dans le contrat public. N'utilisez pas de routes privées de l'application pour forcer le passage : signalez la limitation.

Questions fréquentes

Où puis-je obtenir une clé API ?

Settings → API. Créez une clé API développeur avec les scopes et le niveau d'accès dont vous avez besoin ; elle n'est affichée qu'une fois, copiez-la donc immédiatement. Révoquez-la et régénérez-en une sur la même page si elle a été exposée.

Quels sont l'URL de base et l'authentification ?

URL de base https://api.app.firstsales.io ; authentifiez-vous avec Authorization: Bearer $FIRSTSALES_API_KEY et envoyez du JSON. Commencez par GET /api/v1/whoami pour confirmer le contexte.

Pourquoi les chemins sont-ils aussi longs ?

Les ressources sont rattachées à une organisation et à un workspace, donc les chemins sont de la forme /api/v1/organizations/{orgId}/workspaces/{workspaceId}/…. Récupérez les identifiants via /api/v1/organizations et sa sous-ressource /workspaces (ou via whoami).

Comment éviter les écritures en double ?

Envoyez un en-tête Idempotency-Key sur les requêtes de création. Une requête rejouée avec la même clé renvoie le résultat original au lieu de créer un second enregistrement : sans risque après un timeout.

Puis-je lire les métriques de campagne et les réponses ?

Oui : GET …/campaigns/{id}/analytics pour l'entonnoir/l'engagement, et GET …/inbox/threads pour l'activité des conversations. Le corps des messages est masqué dans la liste ; récupérez un thread individuel pour le détail complet.

Existe-t-il une intégration Zapier ou CRM à la place ?

Il n'y a pas de connecteur Zapier, et les connecteurs CRM natifs (Salesforce, HubSpot, Pipedrive) ne sont pas encore disponibles. En attendant, l'API REST (ou le CLI) reste le moyen pris en charge pour intégrer et synchroniser.

Que signifie unsupported_operation ?

L'action demandée ne fait pas partie du contrat public /api/v1. Arrêtez-vous et signalez-le : n'appelez pas les routes privées de l'application, les callbacks, les pixels ou les endpoints internes pour contourner cette limite ; ils ne sont pas pris en charge et casseront.

Développeur & CLI

Une prospection qui continue quand vous vous déconnectez.Leads, emails, relances et réponses, gérés.

Connectez des boîtes illimitées et laissez les agents IA trouver les leads, écrire chaque email et relancer. Ou envoyez vos propres modèles en mode manuel. À partir de $29/mois.

Démarrez votre essai à $1 Voir les tarifs

$1 pour 3 jours · Annulez quand vous voulez · Sans engagement

Installer avec l'IA

Votre agent de code installe la CLI et les skills FirstSales pour vous.

Prompt pour 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 ↗