DirectorEmailReveal

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/insourcia-io/json-schema/insourcia-io-director-email-reveal-schema.json",
  "title": "DirectorEmailReveal",
  "description": "Réponse de `POST /companies/directors/reveal-email`. Seuls les champs de la forme de réponse obtenue sont présents.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/insourcia-io-openapi.yaml#/components/schemas/DirectorEmailReveal",
  "type": "object",
  "properties": {
    "email": {
      "type": [
        "string",
        "null"
      ],
      "description": "Email professionnel principal. `null` quand aucun email exploitable n'est trouvé (voir `reason`). Absent tant que la recherche est en cours."
    },
    "emails": {
      "type": "array",
      "description": "Toutes les adresses professionnelles trouvées, la principale en premier.",
      "items": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "verification_status": {
            "type": "string"
          },
          "deliverability_proven": {
            "type": "boolean"
          }
        }
      }
    },
    "verification_status": {
      "type": "string",
      "description": "Statut de vérification de `email` : `DELIVERABLE` ou `HIGH_PROBABILITY` (adresse vérifiée), `CATCH_ALL` (le domaine accepte toutes les adresses, la boîte n'est pas prouvée), `UNVERIFIED` (le fournisseur ne vérifie pas la délivrabilité, cas de Lusha)."
    },
    "deliverability_proven": {
      "type": "boolean",
      "description": "`true` quand l'existence de la boîte est confirmée ; `false` sur un domaine catch-all ou une adresse non contrôlée."
    },
    "provider": {
      "type": "string",
      "description": "Le fournisseur qui a mené la recherche : `fullenrich`, `dropcontact`, `apollo` ou `lusha`."
    },
    "paid_with": {
      "type": "string",
      "enum": [
        "connected_account",
        "insourcia_included",
        "insourcia_unproven"
      ],
      "description": "Qui a payé : votre compte connecté (`connected_account`), les crédits Insourcia de l'organisation (`insourcia_included`), ou rien parce que l'adresse n'est pas prouvée (`insourcia_unproven`). Absent quand rien n'a été facturé : relecture d'un dirigeant déjà révélé, email introuvable, recherche en cours."
    },
    "credits_used": {
      "type": "integer",
      "description": "Crédits consommés par cet appel, sur votre compte connecté ou en crédits Insourcia (100 par email trouvé). 0 pour une relecture, une recherche en cours ou un email introuvable, sauf la recherche que Lusha et Apollo facturent quand ils trouvent la personne sans email."
    },
    "reason": {
      "type": "string",
      "enum": [
        "not_found",
        "rejected_by_verification",
        "inactive_mandate",
        "not_a_director",
        "linkedin_profile_required"
      ],
      "description": "Pourquoi `email` vaut `null` :\n- `not_found` : aucun email professionnel exploitable ;\n- `rejected_by_verification` : une adresse a été trouvée, puis écartée par la vérification ;\n- `inactive_mandate` : le mandat ou la société n'est plus actif ;\n- `not_a_director` : ce prénom et ce nom ne figurent pas parmi les dirigeants de la société, ni parmi les représentants d'une personne morale dirigeante (aucun appel, aucun crédit) ;\n- `linkedin_profile_required` : le fournisseur connecté ne cherche que par profil LinkedIn, inconnu pour ce dirigeant (aucun appel, aucun crédit).\n\nPour `not_found` et `rejected_by_verification`, inutile de réessayer.\n"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending"
      ],
      "description": "Présent seulement quand la recherche est en cours."
    },
    "retrieval_token": {
      "type": "string",
      "description": "Avec `status: pending` : le jeton à renvoyer seul pour récupérer le résultat. Valable une heure."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "Avec `status: pending` : délai conseillé avant de rappeler, de 15 à 70 secondes selon le fournisseur et la recherche."
    },
    "started_by_colleague": {
      "type": "boolean",
      "description": "La recherche a été lancée par un autre membre de votre équipe : rien ne vous est facturé."
    },
    "attempts": {
      "type": "array",
      "description": "Avec le repli entre payeurs activé : chaque payeur essayé, dans l'ordre réglé par l'utilisateur. La révélation passe au suivant quand un payeur ne trouve rien ou ne peut pas payer, et s'arrête au premier email trouvé.",
      "items": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "string",
            "description": "`fullenrich`, `dropcontact`, `apollo`, `lusha`, `kaspr`, ou `coordinate` pour les crédits Insourcia."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "found",
              "not_found",
              "out_of_credits",
              "unavailable",
              "pending"
            ]
          },
          "credits_used": {
            "type": "number",
            "description": "Crédits débités par ce payeur, rate facturé compris (Apollo, Lusha)."
          }
        }
      }
    },
    "fallback_notice": {
      "type": "string",
      "description": "Avec le repli : le premier payeur n'avait plus de crédits et un autre a pris le relais. Absent sur un simple raté."
    },
    "_notice": {
      "type": "string",
      "description": "Mention d'information à reprendre lors du premier contact avec la personne."
    },
    "_note": {
      "type": "string",
      "description": "Explication en français de la réponse, pour un humain ou un agent."
    }
  }
}