# MachineSignal

MachineSignal exposes a callable beta API for CRM systems, RevOps workflows and AI agents that need operational decisions on business domains before spending budget on enrichment or follow-up.

Base URL: https://machinesignal-api.beta-878.workers.dev

Useful endpoints:
- GET /health
- GET /openapi.json
- GET /postman_collection.json
- GET https://machinesignal.it/postman_public_collection.json
- GET /llms.txt
- GET /machine-onboarding.json
- GET /product-catalog.json
- GET https://machinesignal.it/score-decision-contract.json
- GET https://machinesignal.it/machine-discovery/machine-discovery-pack.json
- GET https://machinesignal.it/distribution/api-directory-submission.json
- GET https://machinesignal.it/distribution/rapidapi-listing.json
- GET https://machinesignal.it/distribution/rapidapi-provider-setup.json
- GET https://machinesignal.it/distribution/channel-shortlist.json
- GET https://machinesignal.it/.well-known/machine-discovery.json
- POST /v1/sandbox/customers
- GET /v1/onboarding
- GET /v1/usage
- POST /v1/intake
- POST /v1/order-intents
- GET /v1/order-intents/{order_intent_id} with X-MachineSignal-Order-Receipt for synthetic staging status only
- POST /v1/lead-opportunity-score
- POST /v1/purchase-intent
- GET /v1/orders
- GET /v1/orders/{order_intent_id}
- POST /v1/beta/customers
- GET /v1/beta/customers/{customer_id}
- PATCH /v1/beta/customers/{customer_id}
- GET /v1/admin/sandbox-metrics

Authentication:
- protected endpoints require header X-API-Key: <beta key>;
- public endpoints are /, /health, /openapi.json, /postman_collection.json, https://machinesignal.it/postman_public_collection.json, /product-catalog.json and /llms.txt.
- POST /v1/beta/customers requires the admin beta key and returns a dedicated customer key.
- GET/PATCH /v1/beta/customers/{customer_id} require the admin beta key and never return the full customer API key.
- GET /v1/admin/sandbox-metrics requires the admin beta key and returns only aggregated sandbox test metrics.

How a machine should call the decision endpoint:
1. Fetch /llms.txt, /machine-onboarding.json or /openapi.json.
2. Fetch /product-catalog.json to read products, exact beta prices, deliverables and credit rules.
3. If no beta key is available, POST /v1/sandbox/customers to create a limited sandbox key for safe testing.
4. If the machine is not sure what to buy or call, POST /v1/intake. Intake consumes no credits and returns recommended_product_code, billing_code, missing_inputs and next_api_call.
5. Read the required X-API-Key and Idempotency-Key headers.
6. POST /v1/lead-opportunity-score with JSON body: {"domain":"example.it","sector_hint":"dentist","country_hint":"IT"} when a reliable domain is available.
7. Read decision, machine_next_step and next_purchase.
8. Fetch https://machinesignal.it/score-decision-contract.json and route the response according to the allowed decision contract.
8. Read /v1/usage to verify consumed and remaining credits.
9. If next_purchase.next_product is not null, POST /v1/purchase-intent to create a beta order intent.
10. Use GET /v1/orders or GET /v1/orders/{order_intent_id} to retrieve previous orders and deliveries.

Controlled machine-origin order staging flow:
1. POST /v1/order-intents with a unique Idempotency-Key and staging_synthetic_order=true for a synthetic MS-DEC-250 probe.
2. Keep seller_review.order_receipt private and poll seller_review.status_url with X-MachineSignal-Order-Receipt.
3. Inspect seller_review.checkout_handoff_dry_run. The expected status is checkout_ready_dry_run_owner_release_required with live release, provider reference, provider call and checkout URL all false.
4. Stop before payment. The receipt is not a payment credential, and neither endpoint returns a checkout URL.
5. Never log, publish or reuse the receipt for another order.

Three machine buying flows:
1. Customer machine has a list: call POST /v1/lead-opportunity-score for each domain, then route each result by decision.
2. Customer machine has no list: call POST /v1/purchase-intent with product_code target_discovery, market, area and commercial_objective. The objective must say what kind of opportunity the machine wants to find, for example "find real estate agency websites worth scoring for digital presence improvement opportunities".
3. Customer machine wants an action: after a strong score and Deep Analysis, call POST /v1/purchase-intent with product_code action_pack to receive CRM-ready JSON: crm_record_patch, workflow_payload, webhook_event, agent_instructions, message angle, stop rules and follow-up sequence.

Public demos for software, agents and partners:
- Machine Discovery Pack: https://machinesignal.it/machine-discovery/
- Machine Discovery Pack JSON: https://machinesignal.it/machine-discovery/machine-discovery-pack.json
- Technical Distribution Pack: https://machinesignal.it/distribution/
- API Directory Submission JSON: https://machinesignal.it/distribution/api-directory-submission.json
- RapidAPI Listing JSON: https://machinesignal.it/distribution/rapidapi-listing.json
- RapidAPI Provider Setup JSON: https://machinesignal.it/distribution/rapidapi-provider-setup.json
- Distribution Channel Shortlist JSON: https://machinesignal.it/distribution/channel-shortlist.json
- Postman Public Collection JSON: https://machinesignal.it/postman_public_collection.json
- Well-known Machine Discovery JSON: https://machinesignal.it/.well-known/machine-discovery.json
- Full machine buyer flow: https://machinesignal.it/demo/machine-buyer-flow/
- Full flow JSON: https://machinesignal.it/demo/machine-buyer-flow/flow.json
- Score results JSON: https://machinesignal.it/demo/machine-buyer-flow/score_results.json
- Order events JSON: https://machinesignal.it/demo/machine-buyer-flow/order_events.json
- CRM consumer demo: https://machinesignal.it/demo/crm-consumer/
- CRM records JSON: https://machinesignal.it/demo/crm-consumer/crm_records.json
- Webhook events JSON: https://machinesignal.it/demo/crm-consumer/webhook_events.json

Beta tester onboarding resources:
- Beta tester onboarding packet: https://machinesignal.it/beta/onboarding-packet.html
- Onboarding packet JSON: https://machinesignal.it/beta/onboarding-packet.json
- Feedback schema JSON: https://machinesignal.it/beta/feedback-schema.json
- Machine beta test kit: https://machinesignal.it/beta/machine-test-kit.html
- Machine beta test kit JSON: https://machinesignal.it/beta/machine-test-kit.json

Commercial model under test:
- MS-BND-DISC-250 / Target Discovery Pack 250 Bundle: EUR 299 for 250 targets + operational decisions;
- MS-BND-DOM-100 / Domain Enrichment Pack 100 Bundle: EUR 149 for 100 domain enrichment records + operational decisions on valid records;
- MS-DEC-250 / Lead Decision Pack 250: EUR 49 for 250 valid operational decisions on a clean customer list;
- MS-ANA-100 / Deep Analysis Pack 100: EUR 199 for 100 valid deep analyses;
- MS-ACT-25 / Opportunity Action Pack 25: EUR 399 + EUR 2 stamp duty, total EUR 401; live_post_purchase_only after a signed entitlement proves the same buyer paid for and completed MS-DEC-250; no anonymous checkout;
- MS-ACT-UPG-25 / Opportunity Action Pack Upgrade 25: not currently offered;
- MS-BND-FEED-4X4-250 / Opportunity Feed 4+4 Bundle: EUR 199/month for 4 scans, 4 deliveries, 1 market/area and max 250 valid targets/month;
- MS-SUB-STARTER-250 / MachineSignal Starter Monthly: EUR 199/month with 250 targets/month + operational decisions;

Machine purchase flow:
- MachineSignal Starter Monthly is the simple recurring monthly flow with 250 targets/month and operational decisions included;
- Target Discovery is used when no list exists and the customer wants a one-off target bundle;
- Lead Decision Pack returns operational decisions for an existing list;
- Domain Enrichment fixes unreliable domains before decisioning;
- Deep Analysis explains promising decisions;
- Opportunity Action Pack prepares CRM/workflow actions after positive Deep Analysis;
- Opportunity Feed monitors one market/area over time with capped monthly output.
- API Pro: EUR 499/month with 3000 valid operational decisions, 50 deep analyses and 1 monthly feed.

Machine-readable decisions:
- discard: do not spend more budget now;
- watchlist: save and rescore later;
- nurture: save in nurturing and consider low-cost enrichment;
- buy_deep_analysis: buy a paid deeper analysis before human/campaign spend;
- needs_verification: verify data quality before spending more budget.

How a machine should create a beta order intent:
- POST /v1/purchase-intent with X-API-Key and Idempotency-Key;
- body example: {"product_code":"domain_enrichment","target_name":"Studio Dentistico Demo","batch_id":"dentists-lombardy-demo"};
- supported product_code values: target_discovery, domain_enrichment, verification, nurture_signal, deep_analysis, action_pack, opportunity_feed;
- the beta order intent consumes one corresponding pack credit;
- the response includes delivery, an immediate machine-readable beta output with what_is_included, output_contract, next_machine_call and stop_rules when relevant;
- no real payment is executed in beta.

Action Pack delivery contract:
- action_pack returns Deep Analysis context, cluster_strategy, an explicit mini_check, campaign_plan, message_drafts, CRM/workflow payloads, reputation_and_spam_risk, approval gate, stop rules, audit trail and the day 0/7/21/60 follow-up sequence;
- if action_pack mentions a mini-check, interventions, recommended steps or passages, the output must list the concrete points with problem, evidence, recommended intervention and connected CRM/workflow action;
- generic wording such as "3 interventions" or "mini-check in 3 steps" without the actual points is not a valid action_pack output;
- webhook_event.event_type is machinesignal.action_pack.ready;
- the customer machine should create/update CRM records first, run a compliance gate, and only then prepare any external action.

How a machine should retrieve previous orders:
- GET /v1/orders with X-API-Key;
- optional filters: product_code, domain, status;
- GET /v1/orders/{order_intent_id} to retrieve one order and its delivery;
- order history is beta ledger data, not invoice data.

How beta onboarding works:
- an evaluator machine can create a limited sandbox key with POST /v1/sandbox/customers;
- an admin creates a beta customer with POST /v1/beta/customers;
- the response returns a dedicated API key once;
- the customer machine then uses that key for score, purchase intent, usage and order history;
- initial credits are assigned in the customer's ledger;
- an admin can top up credits, reset usage, suspend or reactivate a customer with PATCH /v1/beta/customers/{customer_id}.

Sandbox limits:
- POST /v1/sandbox/customers is for low-risk evaluation only;
- sandbox keys receive 5 decision credits, 1 target discovery credit, 1 deep analysis credit, 1 action pack credit, 1 verification credit, 1 nurture signal credit and 1 domain enrichment credit;
- sandbox keys expire after 7 days by default;
- sandbox creation is limited daily to reduce abuse;
- sandbox keys do not execute real payment and do not contact external targets;
- for larger tests, request a private beta key.

7-day sandbox test metrics:
- admins and agents monitor GET /v1/admin/sandbox-metrics daily;
- tracked targets are 10 sandbox keys, 300 scores, 15 Deep Analysis orders and 3 Action Pack orders;
- score_decisions separates valid decisions, interesting decisions, strong decisions and decision breakdown;
- the endpoint also verifies safety flags: real_payment_executed=false and external_contact_executed=false;
- use this endpoint to decide whether distribution, onboarding or product packaging needs improvement.

Machine-first rule:
- MachineSignal does not require human email persuasion as the primary channel;
- the public onboarding manifest explains the contract to software and agents;
- authenticated onboarding tells a machine what it can do with its own key;
- humans may supervise, approve or audit, but they are not the primary buyer interface.

Important operating rules:
- send an Idempotency-Key with each scoring request;
- repeated requests with the same Idempotency-Key do not consume a second credit;
- credits are consumed only when the API produces a valid usable output;
- the beta does not execute real payments;
- the beta does not contact external targets.

Contact: beta@machinesignal.it
Website: https://machinesignal.it/