Quote

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/handsforagents-com/json-schema/handsforagents-com-quote-schema.json",
  "title": "Quote",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/handsforagents-com-openapi.yaml#/components/schemas/Quote",
  "type": "object",
  "required": [
    "quote_id",
    "status"
  ],
  "properties": {
    "quote_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "received",
        "quoted",
        "refused",
        "expired"
      ]
    },
    "refusal_reason": {
      "type": "string",
      "description": "Present when status is refused. Refused requests are not invoiced."
    },
    "refusal_code": {
      "type": "string",
      "enum": [
        "credentials",
        "impersonation",
        "surveillance",
        "social-manipulation",
        "verification-bypass",
        "referral-fraud",
        "weapons-regulated",
        "counterfeit",
        "reshipping-fraud",
        "illegal",
        "capability-limit",
        "sensitive-unverified",
        "other"
      ],
      "description": "Present when status is refused: the category from the task policy, or capability-limit / sensitive-unverified / other."
    },
    "task_id": {
      "type": "string",
      "description": "Present once create_task was called for this quote."
    },
    "price": {
      "type": "object",
      "required": [
        "amount",
        "currency"
      ],
      "properties": {
        "amount": {
          "type": "number",
          "description": "Fixed total. No VAT is added; the provider is not VAT-registered."
        },
        "currency": {
          "type": "string",
          "enum": [
            "EUR",
            "USD"
          ]
        }
      }
    },
    "payment_schedule": {
      "type": "object",
      "required": [
        "mode"
      ],
      "description": "Up to 150 EUR: full_prepayment or card_hold. Above: deposit_and_balance.",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "full_prepayment",
            "card_hold",
            "deposit_and_balance"
          ]
        },
        "deposit": {
          "type": "object",
          "required": [
            "amount",
            "currency"
          ],
          "properties": {
            "amount": {
              "type": "number",
              "description": "Fixed total. No VAT is added; the provider is not VAT-registered."
            },
            "currency": {
              "type": "string",
              "enum": [
                "EUR",
                "USD"
              ]
            }
          }
        },
        "balance": {
          "type": "object",
          "required": [
            "amount",
            "currency"
          ],
          "properties": {
            "amount": {
              "type": "number",
              "description": "Fixed total. No VAT is added; the provider is not VAT-registered."
            },
            "currency": {
              "type": "string",
              "enum": [
                "EUR",
                "USD"
              ]
            }
          }
        }
      }
    },
    "scope": {
      "type": "string"
    },
    "deliverables": {
      "type": "string"
    },
    "evidence": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "What the evidence package will contain."
    },
    "subcontracted": {
      "type": "string",
      "description": "Processes done by subcontractors, if any."
    },
    "delivery_date": {
      "type": "string",
      "format": "date"
    },
    "inbound_address": {
      "type": "string",
      "description": "Where to send parts or parcels, if the task needs them."
    },
    "operator_verification_required": {
      "type": "boolean",
      "description": "True for the sensitive task categories."
    },
    "valid_until": {
      "type": "string",
      "format": "date"
    },
    "terms_version": {
      "type": "string"
    },
    "next_action": {
      "type": "string",
      "description": "One or two sentences in English: what the agent or the client should do now."
    },
    "messages": {
      "$ref": "#/$defs/OperatorMessages"
    },
    "duplicate_ignored": {
      "type": "boolean",
      "description": "Present and true only in the answer to a POST whose message was ignored because the same text was already the newest message of the thread (sent within the last 10 minutes)."
    },
    "message_sent": {
      "type": "boolean",
      "description": "Present only in the answer to a POST with a message: true, the message was stored and e-mailed to the operator; false, it was NOT stored because the operator had written something you had not read yet (that message is in messages, now marked as read; next_action says so): send your answer again. Absent when the same text was ignored (duplicate_ignored) and in every plain status call."
    },
    "test_mode": {
      "type": "boolean",
      "description": "Present and true only for a test quote: an order made from it is a test order."
    }
  },
  "$defs": {
    "OperatorMessages": {
      "type": "array",
      "description": "The thread with the operator, newest first: the operator's notes and your own replies (from: agent over REST; the MCP tools show your own replies as from: you). An operator message you have not been shown yet is always included, also in the answer to your own reply (a message of yours sent while it is unread is not stored: message_sent is false). Read the operator's message first, then reply: call get_status with message (POST with a JSON body over REST); e-mailing the tasks address with the quote_id in the subject also works.",
      "items": {
        "type": "object",
        "required": [
          "at",
          "from",
          "text"
        ],
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "from": {
            "type": "string",
            "enum": [
              "operator",
              "agent"
            ]
          },
          "text": {
            "type": "string",
            "description": "Plain text, at most 2000 characters. Never HTML."
          }
        }
      }
    }
  }
}