machinesignal-it Lead Opportunity Score API

openapi: 3.2.0
info:
  title: MachineSignal Controlled Lead Opportunity Score API
  version: 0.3.0
  description: Controlled scoring and usage API for approved B2B Italy customers. The production zero-touch order-intake contract is published separately at https://api.machinesignal.it/openapi.json and https://machinesignal.it/order-openapi.json.
servers:
- url: https://staging.machinesignal.it
  description: Staging health and controlled API surface. Private API access requires explicit approval.
security:
- ApiKeyAuth: []
tags:
- name: Lead Opportunity Score
paths:
  /v1/lead-opportunity-score:
    post:
      summary: Score one B2B Italy lead opportunity
      description: Controlled endpoint for approved B2B Italy customers. It returns a machine-readable lead decision and must not execute payment, issue invoices or contact external targets.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadOpportunityScoreRequest'
      responses:
        '200':
          description: Lead opportunity decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadOpportunityScoreResponse'
        '401':
          description: Missing or invalid private API key
        '403':
          description: Customer scope is not approved for B2B Italy
      tags:
      - Lead Opportunity Score
      operationId: postV1LeadOpportunityScore
      x-operation-id-source: derived
components:
  schemas:
    DecisionContractPointer:
      type: object
      properties:
        contract_url:
          type: string
          format: uri
          examples:
          - https://machinesignal.it/score-decision-contract.json
        route:
          type: string
          enum:
          - discard
          - watchlist
          - review
          - prioritize
        credit_rule:
          type: string
        payment_executed:
          type: boolean
          const: false
        invoice_issued:
          type: boolean
          const: false
        external_contact_executed:
          type: boolean
          const: false
    LeadOpportunityScoreResponse:
      type: object
      required:
      - domain
      - opportunity_score
      - confidence
      - decision
      - usage
      properties:
        domain:
          type: string
        opportunity_score:
          type: integer
          minimum: 0
          maximum: 100
        confidence:
          type: number
          minimum: 0
          maximum: 1
        decision:
          type: string
          enum:
          - discard
          - watchlist
          - review
          - prioritize
        priority:
          type: string
          enum:
          - low
          - medium
          - high
        reason:
          type: string
        suggested_route:
          type: string
        product_code:
          type: string
          const: MS-DEC-250
        request_id:
          type: string
        decision_contract:
          $ref: '#/components/schemas/DecisionContractPointer'
        usage:
          $ref: '#/components/schemas/UsageEnvelope'
        scope:
          type: string
          const: b2b_italy_controlled
        checkout_public:
          type: boolean
          const: false
        payment_executed:
          type: boolean
          const: false
        invoice_issued:
          type: boolean
          const: false
        external_contact_executed:
          type: boolean
          const: false
    UsageEvent:
      type: object
      properties:
        product_code:
          type: string
          const: MS-DEC-250
        status:
          type: string
          enum:
          - valid_output
          - not_consumed
        credits_consumed:
          type: integer
          minimum: 0
        request_id:
          type: string
        reason:
          type: string
        credits_remaining:
          type: integer
          minimum: 0
    LeadOpportunityScoreRequest:
      type: object
      required:
      - domain
      - country_hint
      properties:
        domain:
          type: string
          examples:
          - example-azienda.it
        country_hint:
          type: string
          const: IT
        sector_hint:
          type: string
          examples:
          - B2B services
        customer_scope:
          type: string
          const: B2B Italy
    UsageBalance:
      type: object
      properties:
        product_code:
          type: string
          const: MS-DEC-250
        credits_purchased:
          type: integer
          examples:
          - 250
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type: integer
          minimum: 0
    UsageEnvelope:
      type: object
      properties:
        customer_id:
          type: string
        ledger_persisted:
          type: boolean
        balances:
          type: array
          items:
            $ref: '#/components/schemas/UsageBalance'
        current_event:
          $ref: '#/components/schemas/UsageEvent'
        rule:
          type: string
        real_payment_executed:
          type: boolean
          const: false
        external_contact_executed:
          type: boolean
          const: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
externalDocs:
  description: Lead opportunity score API, product fit, JSON output and machine-origin purchase path
  url: https://machinesignal.it/api/lead-opportunity-score/
x-machinesignal-discovery-pages:
- https://machinesignal.it/api/lead-opportunity-score/
- https://machinesignal.it/resources/lead-decision-api-b2b-italy/
- https://machinesignal.it/risorse/prioritizzazione-aziende-target-api/
- https://machinesignal.it/risorse/analisi-mercato-potenziale-api/
x-machinesignal-product-status:
  live_approved:
  - MS-DEC-250
  - MS-ACT-25
  MS-DEC-250_example_output_url: https://machinesignal.it/ms-dec-250-example.json
  MS-ACT-25: live_post_purchase_only
  MS-ACT-25_order_intent_allowed_only_with_signed_entitlement: true
  MS-ACT-25_example_output_url: https://machinesignal.it/ms-act-25-example.json
  MS-ACT-25_output_contract:
    product_promise: A complete execution-ready campaign package for exactly 25 qualified targets, prepared for a buyer-controlled CRM or workflow.
    package_scope:
      target_count: 25
      deep_analysis_included: true
      explicit_mini_check_required: true
      cluster_strategy_required: true
      initial_follow_up_nurturing_messages_required: true
      crm_workflow_payload_required: true
      campaign_sequence_days:
      - 0
      - 7
      - 21
      - 60
      automatic_contact_stop_nurture_rules_required: true
      reputation_spam_risk_assessment_required: true
      audit_trail_required: true
    output_validity_rule: Every cited mini-check must list each explicit problem, observed evidence, recommended intervention and connected CRM/workflow action.
    fulfillment_release_policy: Fail closed unless the complete 25-target output contract and delivery readiness are verified.