> ## Documentation Index
> Fetch the complete documentation index at: https://developers.marko.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Résoudre une société par SIREN via Pappers

> Résout d'abord les données locales puis réserve de façon idempotente tout appel Pappers facturable. Requiert le header Idempotency-Key.

**Scope requis :** `operateurs:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



## OpenAPI

````yaml /openapi.json post /enrichment/siren/{siren}/resolve
openapi: 3.1.0
info:
  title: MARKO External Partner API
  version: v1
  description: >-
    Stable external API contract for the live environment.


    Authentication flow for partner integrations:

    1. Generate an API key from the MARKO entity admin API section.

    2. Keep the raw API secret server-side and use it only to sign `POST
    /v1/auth/token`.

    3. Build the canonical message
    `MARKO-EXTERNAL-API-TOKEN-V1\n{key_id}\n{timestamp}\n{nonce}`.

    4. Sign that message with HMAC-SHA256 and send the hex signature with
    `key_id`, `timestamp` and `nonce`.

    5. Use the returned short-lived bearer on business endpoints as
    `Authorization: Bearer <access_token>`.

    The raw API secret must never be sent on business endpoints.


    This public contract intentionally excludes beta endpoints.


    Référence enrichie pour les développeurs et les assistants IA. Exemples
    synthétiques; les champs sont extraits des modèles et sérialiseurs de la
    version indiquée dans x-documentation-provenance.
servers:
  - url: https://partner-api.marko.fr/v1
security:
  - BearerAuth: []
tags:
  - name: auth
    x-group: Authentification
  - name: entity
    x-group: Entité
  - name: portfolio
    x-group: Portefeuille
  - name: deals
    x-group: Deals
  - name: fonds
    x-group: Fonds
  - name: spvs
    x-group: SPV
  - name: operations
    x-group: Opérations
  - name: taxonomies
    x-group: Taxonomies
  - name: import-jobs
    x-group: Imports par lot
  - name: comments
    x-group: Commentaires
  - name: documents
    x-group: Documents
  - name: users
    x-group: Utilisateurs
  - name: settings
    x-group: Paramètres
  - name: rcci
    x-group: Conformité RCCI
  - name: field-definitions
    x-group: Champs métier
  - name: search
    x-group: Recherche
  - name: operateurs
    x-group: Opérateurs
  - name: alerts
    x-group: Alertes
  - name: notifications
    x-group: Notifications
  - name: calendar
    x-group: Calendrier
  - name: enrichment
    x-group: Enrichissement SIREN
  - name: reports
    x-group: Exports
  - name: reporting
    x-group: Templates de reporting
  - name: workflows
    x-group: Workflows et extraction IA
  - name: tasks
    x-group: Tâches
externalDocs:
  description: Download the matching Postman collection.
  url: /v1/postman.json
paths:
  /enrichment/siren/{siren}/resolve:
    post:
      tags:
        - enrichment
      summary: Résoudre une société par SIREN via Pappers
      description: >-
        Résout d'abord les données locales puis réserve de façon idempotente
        tout appel Pappers facturable. Requiert le header Idempotency-Key.


        **Scope requis :** `operateurs:write`. [Scopes et
        délégation](/scopes-and-delegation).


        **Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre
        la même mutation, réutiliser la même clé et le même contenu. [Écritures
        et idempotence](/writes-and-idempotency).
      operationId: enrichment_siren_resolve
      parameters:
        - in: path
          name: siren
          required: true
          schema:
            type: string
            title: Siren
          example: '552120222'
          description: >-
            SIREN français sur 9 chiffres; le service vérifie aussi le checksum
            lorsque la route le prévoit.
        - in: header
          name: X-Request-ID
          required: false
          description: >-
            Partner-generated correlation identifier echoed in logs and error
            payloads.
          schema:
            type: string
          example: marko-enrichment-siren-resolve
        - in: header
          name: Idempotency-Key
          required: true
          description: >-
            Required for every write, including environments where replay
            deduplication is disabled. Reuse the same value when retrying the
            same logical write and use a new value for a different write.
          schema:
            type: string
            maxLength: 255
            pattern: ^[!-~]+$
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SIRENEnrichmentResponse'
              example:
                success: true
                data:
                  siren: '552120222'
                  raison_sociale: Societe Generale
                  forme_juridique: SA
                  source: pappers
                  is_radiee: false
                cached: false
                error: null
          headers:
            Idempotency-Key:
              schema:
                type: string
              description: Clé d'idempotence utilisée pour l'action.
            X-Marko-Idempotency-Key-Source:
              schema:
                type: string
                enum:
                  - client
                  - server
              description: Origine de la clé utilisée.
            X-Marko-Idempotency-TTL-Seconds:
              schema:
                type: integer
              description: Durée de rétention annoncée pour cette action, en secondes.
        '400':
          description: Invalid Idempotency-Key header
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Bad Request
                status: 400
                detail: >-
                  Idempotency-Key must contain at most 255 visible ASCII
                  characters without spaces.
                request_id: req_example_partner_call
        '401':
          description: Authentication required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: A valid bearer token is required.
                request_id: req_example_partner_call
        '403':
          description: Scope, route or IP restriction
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: The API key does not allow this operation.
                request_id: req_example_partner_call
        '409':
          description: Idempotency or write target conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: >-
                  The idempotency key payload, external reference, target, or
                  source conflicts with an existing write.
                request_id: req_example_partner_call
        '422':
          description: Validation failed
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unprocessable Content
                status: 422
                detail: The request payload or parameters are invalid.
                request_id: req_example_partner_call
        '428':
          description: Required Idempotency-Key header is missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Precondition Required
                status: 428
                detail: The Idempotency-Key header is required.
                request_id: req_example_partner_call
        '429':
          description: Rate limit or progressive ban
          headers:
            Retry-After:
              description: Cooldown in seconds before retrying the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: The request rate limit was exceeded.
                request_id: req_example_partner_call
        '500':
          description: Unexpected server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: An unexpected server error occurred.
                request_id: req_example_partner_call
      deprecated: false
      security:
        - BearerAuth: []
components:
  schemas:
    SIRENEnrichmentResponse:
      properties:
        success:
          type: boolean
          title: Success
          default: true
          description: Indique si l'enrichissement SIREN a produit un résultat exploitable.
        data:
          anyOf:
            - $ref: '#/components/schemas/SIRENData'
            - type: 'null'
          description: >-
            Données métier de l'opération. Consultez GET /field-definitions pour
            les clés, types et unités disponibles; ne déduisez pas les unités
            des noms.
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Message d'échec de l'enrichissement SIREN, lorsqu'il existe.
        cached:
          type: boolean
          title: Cached
          default: false
          description: >-
            Indique que les données SIREN proviennent d'un résultat déjà
            disponible.
      type: object
      title: SIRENEnrichmentResponse
      description: API response wrapper for SIREN enrichment.
    ProblemDetails:
      type: object
      required:
        - title
        - status
        - detail
      properties:
        type:
          type: string
          default: about:blank
          description: >-
            URI identifiant le type de problème; about:blank lorsque seul le
            statut HTTP le caractérise.
        title:
          type: string
          description: Titre affiché pour l'événement ou le problème.
        status:
          type: integer
          description: Statut HTTP de la réponse d'erreur.
        detail:
          type: string
          description: Informations détaillées sur le problème ou le dossier.
        request_id:
          type: string
          description: Identifiant de corrélation pour le diagnostic de la requête.
        scope:
          type: string
          description: Scope concerné par le refus d'accès, lorsqu'il est renseigné.
        route_id:
          type: string
          description: Identifiant de la route concernée par le problème.
        reason_code:
          type: string
          description: >-
            Code structuré du motif de refus; préférable au texte du message
            pour le diagnostic.
    SIRENData:
      properties:
        identite_entreprise:
          anyOf:
            - $ref: '#/components/schemas/SIRENCompanyIdentity-Output'
            - type: 'null'
          description: Identité structurée de la société et informations de registre.
        kyb_comparison:
          anyOf:
            - $ref: '#/components/schemas/KYBComparison'
            - type: 'null'
          description: >-
            Comparaison des informations de registre avec les pièces
            disponibles.
        siren:
          type: string
          title: Siren
          description: >-
            SIREN français sur 9 chiffres; le service vérifie aussi le checksum
            lorsque la route le prévoit.
        raison_sociale:
          anyOf:
            - type: string
            - type: 'null'
          title: Raison Sociale
          description: Dénomination légale de la société.
        forme_juridique:
          anyOf:
            - type: string
            - type: 'null'
          title: Forme Juridique
          description: Forme juridique déclarée de la société.
        capital_social:
          anyOf:
            - type: number
            - type: 'null'
          title: Capital Social
          description: Capital social déclaré de la société.
        adresse_siege:
          anyOf:
            - type: string
            - type: 'null'
          title: Adresse Siege
          description: Adresse du siège social issue des données de la société.
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
          description: Région géographique déclarée de la société.
        date_creation:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Creation
          description: >-
            Date de création de la société, du fonds ou du dossier; distincte de
            created_at dans MARKO.
        siret:
          anyOf:
            - type: string
            - type: 'null'
          title: Siret
          description: >-
            Identifiant SIRET de l'établissement sur 14 chiffres, distinct du
            SIREN sur 9 chiffres.
        dirigeants:
          items:
            $ref: '#/components/schemas/SIRENDirigeant'
          type: array
          title: Dirigeants
          description: Dirigeants connus de la société.
        procedures_collectives:
          anyOf:
            - items:
                $ref: '#/components/schemas/SIRENProcedure'
              type: array
            - type: 'null'
          title: Procedures Collectives
          description: Procédures collectives connues de la société.
        beneficiaires_effectifs:
          items:
            type: string
          type: array
          title: Beneficiaires Effectifs
          description: Bénéficiaires effectifs connus dans les données de la société.
        source:
          type: string
          title: Source
          description: >-
            Origine des données de registre: registre_public, pappers, manual ou
            none.
          default: manual
        fetched_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Fetched At
          description: Date de récupération des données SIREN auprès de leur source.
        is_radiee:
          type: boolean
          title: Is Radiee
          default: false
          description: Indique si la société est radiée du registre.
      type: object
      required:
        - siren
      title: SIRENData
      description: |-
        Enriched company data resolved from a SIREN number.

        Fields align across local, public-registry and commercial providers.
    SIRENCompanyIdentity-Output:
      properties:
        siren:
          type: string
          pattern: ^\d{9}$
          title: Siren
          description: >-
            SIREN français sur 9 chiffres; le service vérifie aussi le checksum
            lorsque la route le prévoit.
        siret:
          anyOf:
            - type: string
            - type: 'null'
          title: Siret
          description: >-
            Identifiant SIRET de l'établissement sur 14 chiffres, distinct du
            SIREN sur 9 chiffres.
        representant_legal:
          anyOf:
            - $ref: '#/components/schemas/SIRENDirigeant'
            - type: 'null'
          description: Représentant légal connu de la société.
        presidents:
          anyOf:
            - items:
                $ref: '#/components/schemas/SIRENDirigeant'
              type: array
            - type: 'null'
          title: Presidents
          description: Présidents connus de la société.
        beneficiaires_effectifs:
          anyOf:
            - items:
                $ref: '#/components/schemas/SIRENBeneficiaireEffectif'
              type: array
            - type: 'null'
          title: Beneficiaires Effectifs
          description: Bénéficiaires effectifs connus dans les données de la société.
        adresse_siege:
          anyOf:
            - $ref: '#/components/schemas/SIRENAdresse'
            - type: 'null'
          description: Adresse du siège social issue des données de la société.
        is_radiee:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Radiee
          description: Indique si la société est radiée du registre.
        entreprise_cessee:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Entreprise Cessee
          description: Indique si la société est déclarée en cessation d'activité.
        date_radiation:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Radiation
          description: Date de radiation de la société du registre.
        date_cessation:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Cessation
          description: Date de cessation d'activité de la société.
        numero_tva_intracommunautaire:
          anyOf:
            - type: string
            - type: 'null'
          title: Numero Tva Intracommunautaire
          description: Numéro de TVA intracommunautaire connu pour la société.
        date_cloture_exercice:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Cloture Exercice
          description: Date de clôture de l'exercice de la société.
        date_prochaine_cloture_exercice:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Prochaine Cloture Exercice
          description: Prochaine date de clôture d'exercice connue.
        date_cloture_exercice_exceptionnelle:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Cloture Exercice Exceptionnelle
          description: >-
            Date de clôture exceptionnelle de l'exercice, si elle est
            renseignée.
      type: object
      required:
        - siren
      title: SIRENCompanyIdentity
      description: Selected registry identity, bound to the company it describes.
    KYBComparison:
      properties:
        status:
          type: string
          enum:
            - not_compared
            - matched
            - differences
          title: Status
          default: not_compared
          description: >-
            État de la comparaison entre les informations de registre et les
            pièces disponibles.
        documents_compared:
          type: integer
          title: Documents Compared
          default: 0
          description: Documents utilisés pour la comparaison KYB.
        review_required:
          type: boolean
          title: Review Required
          default: false
          description: Indique que le résultat demande une revue humaine.
        alert_persistence_failed:
          type: boolean
          title: Alert Persistence Failed
          default: false
          description: >-
            Indique que la comparaison a produit un résultat mais que
            l'enregistrement de son alerte a échoué.
        differences:
          items:
            $ref: '#/components/schemas/KYBDifference'
          type: array
          title: Differences
          description: Écarts constatés entre les données du Kbis et celles du fournisseur.
      type: object
      title: KYBComparison
    SIRENDirigeant:
      properties:
        nom:
          anyOf:
            - type: string
            - type: 'null'
          title: Nom
          description: Nom de famille de la personne.
        prenom:
          anyOf:
            - type: string
            - type: 'null'
          title: Prenom
          description: Prénom de la personne.
        qualite:
          anyOf:
            - type: string
            - type: 'null'
          title: Qualite
          description: Fonction ou qualité du dirigeant.
        date_naissance:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Naissance
          description: Date de naissance du dirigeant.
        denomination:
          anyOf:
            - type: string
            - type: 'null'
          title: Denomination
          description: Dénomination du dirigeant lorsqu'il s'agit d'une personne morale.
        siren:
          anyOf:
            - type: string
            - type: 'null'
          title: Siren
          description: >-
            SIREN français sur 9 chiffres; le service vérifie aussi le checksum
            lorsque la route le prévoit.
        personne_morale:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Personne Morale
          description: Indique si le dirigeant est une personne morale.
        qualites:
          items:
            type: string
          type: array
          title: Qualites
          description: Fonctions ou qualités connues du dirigeant.
        date_prise_de_poste:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Prise De Poste
          description: Date de prise de fonction du dirigeant.
        adresse:
          anyOf:
            - $ref: '#/components/schemas/SIRENAdresse'
            - type: 'null'
          description: Adresse postale déclarée pour la société ou le dirigeant.
        forme_juridique:
          anyOf:
            - type: string
            - type: 'null'
          title: Forme Juridique
          description: Forme juridique déclarée de la société.
      type: object
      title: SIRENDirigeant
      description: A single dirigeant (director/officer) of the company.
    SIRENProcedure:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: Nature de la procédure collective déclarée.
        date:
          anyOf:
            - type: string
            - type: 'null'
          title: Date
          description: >-
            Date métier; le type et le format ci-dessous font autorité pour
            cette route.
        tribunal:
          anyOf:
            - type: string
            - type: 'null'
          title: Tribunal
          description: Tribunal associé à la procédure collective.
      type: object
      title: SIRENProcedure
      description: A collective proceeding reported by the company provider.
    SIRENBeneficiaireEffectif:
      properties:
        nom:
          type: string
          maxLength: 300
          minLength: 1
          title: Nom
          description: Nom de famille de la personne.
        prenom:
          anyOf:
            - type: string
              maxLength: 300
            - type: 'null'
          title: Prenom
          description: Prénom de la personne.
      type: object
      required:
        - nom
      title: SIRENBeneficiaireEffectif
      description: Only the declared person's name; no private address or birth data.
    SIRENAdresse:
      properties:
        adresse_ligne_1:
          anyOf:
            - type: string
            - type: 'null'
          title: Adresse Ligne 1
          description: Première ligne de l'adresse postale.
        adresse_ligne_2:
          anyOf:
            - type: string
            - type: 'null'
          title: Adresse Ligne 2
          description: Deuxième ligne de l'adresse postale.
        adresse_ligne_3:
          anyOf:
            - type: string
            - type: 'null'
          title: Adresse Ligne 3
          description: Troisième ligne de l'adresse postale.
        complement_adresse:
          anyOf:
            - type: string
            - type: 'null'
          title: Complement Adresse
          description: Complément d'adresse postale.
        code_postal:
          anyOf:
            - type: string
            - type: 'null'
          title: Code Postal
          description: Code postal de l'adresse.
        ville:
          anyOf:
            - type: string
            - type: 'null'
          title: Ville
          description: Ville de l'adresse postale.
        pays:
          anyOf:
            - type: string
            - type: 'null'
          title: Pays
          description: Nom du pays dans l'adresse fournie.
        code_pays:
          anyOf:
            - type: string
            - type: 'null'
          title: Code Pays
          description: Code pays fourni avec l'adresse.
        latitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Latitude
          description: Latitude géographique de l'adresse.
        longitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Longitude
          description: Longitude géographique de l'adresse.
      type: object
      title: SIRENAdresse
    KYBDifference:
      properties:
        document_id:
          type: string
          title: Document Id
          description: UUID MARKO du document.
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: Nom du fichier.
        field:
          type: string
          title: Field
          description: Propriété sur laquelle porte la différence KYB.
        kbis_value:
          type: string
          title: Kbis Value
          description: Valeur lue dans le Kbis pour la propriété comparée.
        pappers_value:
          type: string
          title: Pappers Value
          description: Valeur fournie par Pappers pour la propriété comparée.
        message:
          type: string
          title: Message
          description: Message destiné à l'affichage ou au diagnostic.
      type: object
      required:
        - document_id
        - field
        - kbis_value
        - pappers_value
        - message
      title: KYBDifference
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: MARKO short-lived bearer
      description: >-
        Use the `access_token` returned by `POST /v1/auth/token`. Do not send
        the raw API secret on business endpoints.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.