machinesignal-it Order Intents API

openapi: 3.2.0
info:
  title: MachineSignal controlled B2B Italy order intake Order…
  version: 2026-08-24.mini-dec-preview.v2
  description: Zero-touch B2B Italy flow for MS-DEC-250 and its conditional MS-ACT-25 continuation. ACT is available only to the same buyer after a paid, completed DEC delivery and a signed entitlement for exactly 25 qualified records.
servers:
- url: https://api.machinesignal.it
tags:
- name: Order Intents
paths:
  /v1/order-intents:
    post:
      operationId: createMachineSignalOrderIntent
      summary: Submit one DEC order or one entitled ACT continuation
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 160
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderIntentRequest'
      responses:
        '200':
          description: Intent stored and zero-touch checkout creation queued. Keep order_tracking.order_receipt private and poll order_tracking.status_url.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderIntentAcceptedResponse'
        '202':
          description: Intent stored and asynchronous checkout creation queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderIntentAcceptedResponse'
        '403':
          description: Synthetic orders are forbidden on the public origin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid or ineligible order intent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Intake is fail-closed or temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Order Intents
  /v1/order-intents/{order_intent_id}:
    get:
      operationId: getMachineSignalOrderIntentStatus
      summary: Read authenticated order-intake status
      parameters:
      - name: order_intent_id
        in: path
        required: true
        schema:
          type: string
      - name: X-MachineSignal-Order-Receipt
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Authenticated status. It may contain the buyer-specific checkout URL, post-payment dataset instructions, or an expiring artifact token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderStatusResponse'
        '404':
          description: Order or receipt not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Status service temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Order Intents
  /v1/order-intents/{order_intent_id}/inputs:
    post:
      operationId: submitMachineSignalPaidOrderInputs
      summary: Submit up to 250 company-only targets after verified DEC payment
      parameters:
      - name: order_intent_id
        in: path
        required: true
        schema:
          type: string
      - name: X-MachineSignal-Order-Receipt
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - targets
              properties:
                targets:
                  type: array
                  minItems: 1
                  maxItems: 250
                  items:
                    $ref: '#/components/schemas/CompanyTarget'
      responses:
        '202':
          description: Dataset accepted and fulfillment queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetAcceptedResponse'
        '409':
          description: Verified payment required or dataset conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Dataset contains invalid or personal fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Order Intents
  /v1/order-intents/{order_intent_id}/artifact:
    get:
      operationId: getMachineSignalPaidOrderArtifact
      summary: Retrieve the completed DEC artifact or ACT campaign
      parameters:
      - name: order_intent_id
        in: path
        required: true
        schema:
          type: string
      - name: X-MachineSignal-Order-Receipt
        in: header
        required: true
        schema:
          type: string
      - name: X-MachineSignal-Artifact-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Purchased artifact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactResponse'
        '404':
          description: Order, receipt, artifact, or token not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Artifact not ready, expired, or retrieval limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Order Intents
components:
  schemas:
    DatasetAcceptedResponse:
      type: object
      additionalProperties: true
      required:
      - decision
      - order_intent_id
      - dataset_sha256
      - target_count
      - retention_expires_at
      - duplicate
      - raw_dataset_returned
      - fulfillment_status
      properties:
        decision:
          const: paid_order_dataset_accepted
        order_intent_id:
          type: string
          pattern: ^order_intent_
        dataset_sha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        target_count:
          type: integer
          minimum: 1
          maximum: 250
        retention_expires_at:
          type: string
          format: date-time
        duplicate:
          type: boolean
        raw_dataset_returned:
          const: false
        fulfillment_status:
          type: string
    ErrorResponse:
      type: object
      additionalProperties: true
      description: Fail-closed machine-readable error. No checkout, payment, invoice, dataset or artifact is released on failure.
      properties:
        decision:
          type: string
        code:
          type: string
        error:
          type: string
        message:
          type: string
    ArtifactResponse:
      type: object
      additionalProperties: true
      required:
      - decision
      - order_intent_id
      - product_code
      - artifact
      - artifact_sha256
      properties:
        decision:
          enum:
          - dec_artifact_retrieved
          - act_campaign_retrieved
        order_intent_id:
          type: string
          pattern: ^order_intent_
        product_code:
          enum:
          - MS-DEC-250
          - MS-ACT-25
        artifact:
          oneOf:
          - $ref: '#/components/schemas/DecDecisionArtifact'
          - $ref: '#/components/schemas/ActCampaignArtifact'
          description: Purchased machine-readable DEC decisions or the entitled ACT campaign, typed according to the existing production fulfillment contracts.
        artifact_sha256:
          type: string
          pattern: ^[a-f0-9]{64}$
    ActCampaignArtifact:
      type: object
      additionalProperties: true
      required:
      - contract_version
      - mode
      - product_code
      - campaign_id
      - source_delivery_id
      - delivery_scope
      - campaign_summary
      - action_packs
      - shared_campaign_controls
      - side_effects
      - generated_at
      properties:
        contract_version:
          type: string
        mode:
          const: production_real_fulfillment
        product_code:
          const: MS-ACT-25
        campaign_id:
          type: string
          pattern: ^campaign_
        source_delivery_id:
          type: string
        delivery_scope:
          type: object
          additionalProperties: true
        campaign_summary:
          type: object
          additionalProperties: true
        action_packs:
          type: array
          minItems: 25
          maxItems: 25
          items:
            type: object
            additionalProperties: true
        shared_campaign_controls:
          type: object
          additionalProperties: true
        side_effects:
          type: object
          additionalProperties: true
        generated_at:
          type: string
          format: date-time
    DecisionRecord:
      type: object
      additionalProperties: true
      required:
      - source_record_id
      - company_name
      - domain
      - opportunity_score
      - confidence
      - decision
      - reason
      - suggested_route
      - evidence
      - scoring_version
      properties:
        source_record_id:
          type: string
        company_name:
          type: string
        domain:
          type: string
        opportunity_score:
          type: integer
          minimum: 0
          maximum: 100
        confidence:
          type: number
          minimum: 0
          maximum: 1
        decision:
          enum:
          - needs_verification
          - discard
          - watchlist
          - nurture
          - buy_deep_analysis
        reason:
          type: string
        suggested_route:
          type: string
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/DecisionEvidence'
        page_snapshots:
          type: array
          items:
            type: object
            additionalProperties: true
        collection_errors:
          type: array
          items:
            type: string
        scoring_version:
          type: string
    DecisionEvidence:
      type: object
      additionalProperties: true
      required:
      - fact_type
      - observed
      - source_url
      - observed_at
      - content_sha256
      properties:
        fact_type:
          type: string
        observed:
          type: boolean
        source_url:
          type: string
          format: uri
        observed_at:
          type: string
          format: date-time
        content_sha256:
          type: string
          pattern: ^[a-f0-9]{64}$
    OrderStatusResponse:
      type: object
      additionalProperties: true
      required:
      - decision
      - order_intent_id
      - product_code
      - order_status
      - payment_status
      - fulfillment_status
      - checkout_url_returned
      - dataset_upload_authorized
      - dataset_status
      - artifact_ready
      - duplicate
      - next_machine_action
      - normal_order_human_intervention_required
      - updated_at
      properties:
        decision:
          const: authenticated_real_zero_touch_order_status
        order_intent_id:
          type: string
          pattern: ^order_intent_
        product_code:
          enum:
          - MS-DEC-250
          - MS-ACT-25
        order_status:
          enum:
          - accepted_checkout_queued
          - checkout_ready
          - paid_awaiting_dataset
          - paid_dataset_received
          - paid_processing
          - paid_processing_act_campaign
          - fulfilled
          - failed_closed
        payment_status:
          enum:
          - unpaid
          - paid_verified
        invoice_status:
          enum:
          - not_started
          - created
          - sdi_submitted
          - sdi_processing
          - accepted
          - delivered
          - not_delivered
          - rejected
          - discarded
          - error
        fulfillment_status:
          enum:
          - awaiting_payment
          - dataset_received
          - evidence_processing
          - completed
        checkout_url_returned:
          type: boolean
        dataset_upload_authorized:
          type: boolean
        dataset_status:
          enum:
          - not_received
          - received
          - purged
          - not_applicable_predecessor_records_bound
        artifact_ready:
          type: boolean
        duplicate:
          type: boolean
        next_machine_action:
          enum:
          - poll_authenticated_status
          - open_buyer_specific_checkout
          - submit_company_inputs
          - retrieve_artifact
        checkout:
          $ref: '#/components/schemas/BuyerSpecificCheckout'
        dataset_upload:
          $ref: '#/components/schemas/DatasetUploadInstruction'
        artifact_release:
          $ref: '#/components/schemas/ArtifactReleaseInstruction'
        normal_order_human_intervention_required:
          const: false
        updated_at:
          type: string
          format: date-time
    OrderIntentAcceptedResponse:
      type: object
      additionalProperties: true
      required:
      - order_intent_id
      - product_code
      - order_tracking
      properties:
        decision:
          type: string
        order_intent_id:
          type: string
          pattern: ^order_intent_
        product_code:
          enum:
          - MS-DEC-250
          - MS-ACT-25
        order_status:
          type: string
        order_tracking:
          type: object
          additionalProperties: true
          required:
          - order_receipt
          - status_url
          - next_machine_action
          properties:
            order_receipt:
              type: string
              description: Private bearer receipt. Never log, publish or reuse it outside this order.
            status_url:
              type: string
              format: uri
            next_machine_action:
              type: string
            checkout_handoff_status:
              type: string
            dataset_upload_authorized:
              type: boolean
    CompanyTarget:
      type: object
      additionalProperties: false
      required:
      - source_record_id
      - domain
      - company_name
      properties:
        source_record_id:
          type: string
          minLength: 3
          maxLength: 160
        domain:
          type: string
          description: Public company domain; no URL credentials or personal data.
        company_name:
          type: string
          minLength: 2
          maxLength: 200
        sector_hint:
          type: string
          maxLength: 160
        country_hint:
          type: string
          default: IT
    DecDecisionArtifact:
      type: object
      additionalProperties: true
      required:
      - protocol
      - job_id
      - source_order_intent_id
      - product_code
      - record_count
      - records
      - scoring_version
      - generated_at
      - raw_html_retained
      - provider_calls
      - provider_writes
      properties:
        protocol:
          const: machinesignal_evidence_result_v1
        job_id:
          type: string
          pattern: ^evidence_job_
        source_order_intent_id:
          type: string
          pattern: ^order_intent_
        product_code:
          const: MS-DEC-250
        record_count:
          type: integer
          minimum: 1
          maximum: 250
        records:
          type: array
          minItems: 1
          maxItems: 250
          items:
            $ref: '#/components/schemas/DecisionRecord'
        scoring_version:
          type: string
        generated_at:
          type: string
          format: date-time
        raw_html_retained:
          const: false
        provider_calls:
          const: false
        provider_writes:
          const: false
    DatasetUploadInstruction:
      type: object
      additionalProperties: false
      required:
      - method
      - path
      - receipt_header
      - max_company_records
      - personal_data_forbidden
      properties:
        method:
          const: POST
        path:
          type: string
          pattern: ^/v1/order-intents/order_intent_.+/inputs$
        receipt_header:
          const: X-MachineSignal-Order-Receipt
        max_company_records:
          const: 250
        personal_data_forbidden:
          const: true
    OrderIntentRequest:
      type: object
      additionalProperties: false
      required:
      - buyer_business_name
      - buyer_country
      - buyer_vat_or_tax_identifier
      - buyer_sdi_or_pec
      - buyer_billing_address
      - buyer_contact_email
      - product_code
      - price_eur
      - stamp_duty_eur
      - total_due_eur
      - currency
      - requested_outputs
      - b2b_italy_confirmation
      - terms_privacy_refund_acceptance
      - onerous_clauses_specific_approval
      - jurisdiction_forum
      - buyer_authorizes_business_card_payment
      properties:
        buyer_business_name:
          type: string
          minLength: 2
        buyer_country:
          const: IT
        buyer_vat_or_tax_identifier:
          type: string
          minLength: 6
        buyer_sdi_or_pec:
          type: string
          minLength: 6
        buyer_billing_address:
          type: object
          additionalProperties: false
          required:
          - line1
          - postal_code
          - city
          - province
          - country
          properties:
            line1:
              type: string
            postal_code:
              type: string
            city:
              type: string
            province:
              type: string
            country:
              const: IT
        buyer_contact_email:
          type: string
          format: email
        product_code:
          enum:
          - MS-DEC-250
          - MS-ACT-25
        price_eur:
          enum:
          - 49
          - 399
        stamp_duty_eur:
          enum:
          - 0
          - 2
        total_due_eur:
          enum:
          - 49
          - 401
        currency:
          const: EUR
        requested_outputs:
          enum:
          - 250
          - 25
        b2b_italy_confirmation:
          const: true
        terms_privacy_refund_acceptance:
          const: true
        onerous_clauses_specific_approval:
          const: true
        jurisdiction_forum:
          const: Court of Milan, Italy
        buyer_authorizes_business_card_payment:
          const: true
        source_product_code:
          const: MS-DEC-250
        source_order_intent_id:
          type: string
        source_delivery_id:
          type: string
        qualified_record_refs:
          type: array
          minItems: 25
          maxItems: 25
          uniqueItems: true
          items:
            type: string
        continuation_entitlement:
          type: string
          minLength: 64
      allOf:
      - if:
          properties:
            product_code:
              const: MS-DEC-250
        then:
          properties:
            price_eur:
              const: 49
            stamp_duty_eur:
              const: 0
            total_due_eur:
              const: 49
            requested_outputs:
              const: 250
      - if:
          properties:
            product_code:
              const: MS-ACT-25
        then:
          required:
          - source_product_code
          - source_order_intent_id
          - source_delivery_id
          - qualified_record_refs
          - continuation_entitlement
          properties:
            price_eur:
              const: 399
            stamp_duty_eur:
              const: 2
            total_due_eur:
              const: 401
            requested_outputs:
              const: 25
    ArtifactReleaseInstruction:
      type: object
      additionalProperties: false
      required:
      - path
      - receipt_header
      - artifact_token_header
      - artifact_token
      - expires_at
      - max_retrievals
      properties:
        path:
          type: string
          pattern: ^/v1/order-intents/order_intent_.+/artifact$
        receipt_header:
          const: X-MachineSignal-Order-Receipt
        artifact_token_header:
          const: X-MachineSignal-Artifact-Token
        artifact_token:
          type: string
          minLength: 64
        expires_at:
          type: string
          format: date-time
        max_retrievals:
          const: 3
    BuyerSpecificCheckout:
      type: object
      additionalProperties: false
      required:
      - url
      - session_id
      - expires_at
      - buyer_specific
      properties:
        url:
          type: string
          format: uri
          pattern: ^https://checkout\.stripe\.com/
        session_id:
          type: string
          pattern: ^cs_
        expires_at:
          type: integer
        buyer_specific:
          const: true
externalDocs:
  description: Lead opportunity score API, exact product fit, JSON output and machine-origin purchase path
  url: https://machinesignal.it/api/lead-opportunity-score/
x-machinesignal-discovery-pages:
- https://machinesignal.it/it/prova/
- 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-safety:
  live_product_chain:
  - MS-DEC-250
  - MS-ACT-25 post-purchase only
  b2b_italy_only: true
  free_public_preview_enabled: true
  free_public_preview_max_domains: 3
  free_public_preview_is_ms_dec_250: false
  free_public_preview_is_limited_dec_method_illustration: true
  free_public_preview_ranks_only_submitted_domains: true
  free_public_preview_persists_submitted_domains: false
  free_public_preview_creates_order_or_checkout: false
  public_checkout: false
  buyer_specific_checkout_after_validation: true
  dataset_upload_authorized_at_intake: false
  dataset_upload_authorized_after_verified_payment: true
  payment_executed_at_intake: false
  invoice_or_sdi_executed_at_intake: false
  invoice_and_sdi_automatic_after_verified_payment: true
  normal_order_human_intervention_required: false
  ms_act_25_requires_paid_completed_dec_entitlement: true
  ms_act_25_price_eur: 399
  ms_act_25_stamp_duty_eur: 2
  ms_act_25_total_due_eur: 401
  ms_act_25_target_count: 25